Click or drag to resize
ConvolveMatrixEffect Class
[NoComposition] Applies an arbitrary 2D filter kernel to an image. This can perform operations such as edge detect, emboss, sharpen, or blur.
Inheritance Hierarchy
SystemObject
  Microsoft.Graphics.Canvas.EffectsConvolveMatrixEffect

Namespace:  Microsoft.Graphics.Canvas.Effects
Assembly:  Microsoft.Graphics.Canvas (in Microsoft.Graphics.Canvas.dll) Version: 0.0.0.0
Syntax
C#
Copy
public sealed class ConvolveMatrixEffect : ICanvasEffect, 
	IGraphicsEffect, IGraphicsEffectSource, ICanvasImage, IDisposable

The ConvolveMatrixEffect type exposes the following members.

Constructors
  NameDescription
Public methodConvolveMatrixEffect
Initializes a new instance of the ConvolveMatrixEffect class.
Top
Properties
  NameDescription
Public propertyBorderMode
Gets and sets the border mode for edge pixels.
Public propertyBufferPrecision
Specifies what precision to use for intermediate buffers when drawing this effect.
Public propertyCacheOutput
Enables caching the output from drawing this effect.
Public propertyClampOutput
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.
Public propertyDivisor
After the filter kernel is applied to a pixel, the result is divided by this value. Default 1.
Public propertyInterpolationMode
Interpolation mode used to scale the source image to the specified KernelScale. Default value Linear.
Public propertyKernelHeight
Height of the filter kernel matrix. Default value 3.
Public propertyKernelMatrix
The filter kernel matrix. This array must be sized KernelWidth * KernelHeight. Default value {0,0,0,0,1,0,0,0,0}.
Public propertyKernelOffset
Shifts the filter kernel from its default position centered on the output pixel. Default value (0,0).
Public propertyKernelScale
Scales how the filter kernel is mapped onto the 2D source image. Default value (1,1).
Public propertyKernelWidth
Width of the filter kernel matrix. Default value 3.
Public propertyName
Attaches a user-defined name string to the effect.
Public propertyOffset
After applying the filter kernel and divisor, this offset is added to the result. Default value 0.
Public propertyPreserveAlpha

Specifies whether the convolution filter is applied to alpha as well as the color channels.

When set to false, the filter applies equally to all of the red, green, blue, and alpha channels, operating on premultiplied alpha format data.

When set to true, only the color channels are filtered, while alpha values are kept unchanged. In this case the effect will temporarily unpremultiply the red, green, and blue color component values, apply the filter kernel only to the color channels, and then re-premultiply the result.

Default value false.

Public propertySource
Gets or sets the input source for ConvolveMatrix effect.
Top
Methods
  NameDescription
Public methodDispose
Releases all resources used by the effect.
Public methodGetBounds(ICanvasResourceCreator)
Retrieves the bounds of this ConvolveMatrixEffect.
Public methodGetBounds(ICanvasResourceCreator, Matrix3x2)
Retrieves the bounds of this ConvolveMatrixEffect.
Public methodGetInvalidRectangles
Queries what regions of the effect output have changed since it was last drawn.
Public methodCode exampleGetRequiredSourceRectangle
Queries what part of an effect source image is needed to draw an output region.
Public methodGetRequiredSourceRectangles
Queries what parts of the effect source images are needed to draw an output region.
Public methodInvalidateSourceRectangle
Notifies the effect that one of its source images has changed.
Top
Remarks

Supported by Win2D but not Windows.UI.Composition.

A convolve filter works by sampling a number of source pixels from around the location whose output value is being computed, weighting each sample by the corresponding value from the filter kernel matrix, and summing the results. Different filter kernels can produce a wide range of image processing effects. Although the following examples all use the default 3x3 KernelWidth and KernelHeight, this can be set to any size (note that large kernels are more expensive).

Edge detect filter:

Copy
effect.KernelMatrix = new float[]
{
    0,  1,  0,
    1, -4,  1,
    0,  1,  0,
};

Emboss filter:

Copy
effect.KernelMatrix = new float[]
{
    -2, -1,  0,
    -1,  1,  1,
     0,  1,  2,
};

Sharpen the image:

Copy
effect.KernelMatrix = new float[]
{
    -1, -2,  -1,
    -2,  13, -2,
    -1, -2,  -1,
};

Box blur (note that GaussianBlurEffect is usually a better way to blur an image):

Copy
effect.KernelMatrix = new float[]
{
    1, 1, 1,
    1, 1, 1,
    1, 1, 1,
};

effect.Divisor = 9;

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

See Also