Win2D for WinUI3 (Work in progress)

ColorMatrixEffect Class |

Alters the colors of an image by applying a 5x4 transform matrix.

Inheritance Hierarchy

SystemObject

Microsoft.Graphics.Canvas.EffectsColorMatrixEffect

Microsoft.Graphics.Canvas.EffectsColorMatrixEffect

Syntax

C#

public sealed class ColorMatrixEffect : ICanvasEffect, IGraphicsEffect, IGraphicsEffectSource, ICanvasImage, IDisposable

The ColorMatrixEffect type exposes the following members.

Constructors

Name | Description | |
---|---|---|

ColorMatrixEffect | Initializes a new instance of the ColorMatrixEffect class. |

Properties

Name | Description | |
---|---|---|

AlphaMode | Specifies the treatment of alpha. Default value Premultiplied. | |

BufferPrecision | Specifies what precision to use for intermediate buffers when drawing this effect. | |

CacheOutput | Enables caching the output from drawing this effect. | |

ClampOutput | If set, the effect clamps color values to between 0 and 1 before passing
them on to the next effect in the graph. If false, the effect will not clamp
values, although subsequent effects or the output surface may later clamp if
they are not of high enough precision. Default value false. | |

ColorMatrix | The color transform matrix. | |

Name | Attaches a user-defined name string to the effect. | |

Source | Gets or sets the input source for ColorMatrix effect. |

Methods

Name | Description | |
---|---|---|

Dispose | Releases all resources used by the effect. | |

GetBounds(ICanvasResourceCreator) | Retrieves the bounds of this ColorMatrixEffect. | |

GetBounds(ICanvasResourceCreator, Matrix3x2) | Retrieves the bounds of this ColorMatrixEffect. | |

GetInvalidRectangles | Queries what regions of the effect output have changed since it was last drawn. | |

GetRequiredSourceRectangle | Queries what part of an effect source image is needed to draw an output region. | |

GetRequiredSourceRectangles | Queries what parts of the effect source images are needed to draw an output region. | |

InvalidateSourceRectangle | Notifies the effect that one of its source images has changed. |

Remarks

ColorMatrixEffect uses a Matrix5x4 to modify the colors of an image. It can be configured to produce a wide range of color manipulation effects such as brightness or contrast adjustment, desaturation, sepia tinting, hue rotation, and swapping or inverting color channels.

Mathematical explanation: an (r,g,b,a) color value can be interpreted as a 4 dimensional vector. This vector is extended to 5 dimensions as (r,g,b,a,1). The 5d vector is multiplied by a 5x4 matrix, then the 5th component of the result is discarded, producing an (r,g,b,a) result.

Practical explanation: each component of the output color is a weighted average of all the input components. The transform matrix specifies what weights to use (which may be fractional, arbitrarily large, or negative):

- result.R = (src.R * matrix.M11) + (src.G * matrix.M21) + (src.B * matrix.M31) + (src.A * matrix.M41) + matrix.M51
- result.G = (src.R * matrix.M12) + (src.G * matrix.M22) + (src.B * matrix.M32) + (src.A * matrix.M42) + matrix.M52
- result.B = (src.R * matrix.M13) + (src.G * matrix.M23) + (src.B * matrix.M33) + (src.A * matrix.M43) + matrix.M53
- result.A = (src.R * matrix.M14) + (src.G * matrix.M24) + (src.B * matrix.M34) + (src.A * matrix.M44) + matrix.M54

The identity matrix is a simple no-op transform which passes color values through unchanged:

var identity = new Matrix5x4 { M11 = 1, M12 = 0, M13 = 0, M14 = 0, M21 = 0, M22 = 1, M23 = 0, M24 = 0, M31 = 0, M32 = 0, M33 = 1, M34 = 0, M41 = 0, M42 = 0, M43 = 0, M44 = 1, M51 = 0, M52 = 0, M53 = 0, M54 = 0 };

This matrix swaps the red and blue color channels:

var swapRedAndBlue = new Matrix5x4 { M11 = 0, M12 = 0, M13 = 1, M14 = 0, M21 = 0, M22 = 1, M23 = 0, M24 = 0, M31 = 1, M32 = 0, M33 = 0, M34 = 0, M41 = 0, M42 = 0, M43 = 0, M44 = 1, M51 = 0, M52 = 0, M53 = 0, M54 = 0 };

This matrix separately adjusts the brightness of each color channel:

var adjustBrightness = new Matrix5x4 { M11 = redAmount, M12 = 0, M13 = 0, M14 = 0, M21 = 0, M22 = greenAmount, M23 = 0, M24 = 0, M31 = 0, M32 = 0, M33 = blueAmount, M34 = 0, M41 = 0, M42 = 0, M43 = 0, M44 = 1, M51 = 0, M52 = 0, M53 = 0, M54 = 0 };

This matrix desaturates the image, converting colors to monochrome:

var desaturate = new Matrix5x4 { M11 = 0.333f, M12 = 0.333f, M13 = 0.333f, M14 = 0, M21 = 0.333f, M22 = 0.333f, M23 = 0.333f, M24 = 0, M31 = 0.333f, M32 = 0.333f, M33 = 0.333f, M34 = 0, M41 = 0, M42 = 0, M43 = 0, M44 = 1, M51 = 0, M52 = 0, M53 = 0, M54 = 0 };

This matrix copies the luminance (brightness) of the RGB color into the alpha channel, and sets RGB to a constant white:

var luminanceToAlpha = new Matrix5x4 { M11 = 0, M12 = 0, M13 = 0, M14 = 0.333f, M21 = 0, M22 = 0, M23 = 0, M24 = 0.333f, M31 = 0, M32 = 0, M33 = 0, M34 = 0.333f, M41 = 0, M42 = 0, M43 = 0, M44 = 0, M51 = 1, M52 = 1, M53 = 1, M54 = 0 };

This Windows Runtime type corresponds to the D2D Color matrix effect.

See Also