Convolve matrix effect

Use the convolve matrix effect to apply an arbitrary 2D kernel to an image. You can use this effect to blur, detect edges, emboss, or sharpen an image.

The CLSID for this effect is CLSID_D2D1ConvolveMatrix.

Example image

The example here shows the input and output of the convolve matrix effect with a 3 x 3 kernel.

Before
The image before the effect.
After
The image after the transform.

 


ComPtr<ID2D1Effect> convolveMatrixEffect;
m_d2dContext->CreateEffect(CLSID_D2D1ConvolveMatrix, &convolveMatrixEffect);

convolveMatrixEffect->SetInput(0, bitmap);
float matrix[9] = {-1, -1, -1, -1, 9, -1, -1, -1, -1};
convolveMatrixEffect->SetValue(D2D1_CONVOLVEMATRIX_PROP_KERNEL_MATRIX, matrix);

m_d2dContext->BeginDraw();
m_d2dContext->DrawImage(convolveMatrixEffect.Get());
m_d2dContext->EndDraw();

Effect properties

Display name and index enumerationDescription

KernelUnitLength

D2D1_CONVOLVEMATRIX_PROP_KERNEL_UNIT_LENGTH

The size of one unit in the kernel. The units are in (DIPs/kernel unit), where a kernel unit is the size of the element in the convolution kernel. A value of 1 (DIP/kernel unit) corresponds to one pixel in a image at 96 DPI.

The type is FLOAT.

The default value is 1.0f.

ScaleMode

D2D1_CONVOLVEMATRIX_PROP_SCALE_MODE

The interpolation mode the effect uses to scale the image to the corresponding kernel unit length. There are six scale modes that range in quality and speed.

The type is D2D1_CONVOLVEMATRIX_SCALE_MODE.

The default value is D2D1_CONVOLVEMATRIX_SCALE_MODE_LINEAR.

KernelSizeX

D2D1_CONVOLVEMATRIX_PROP_KERNEL_SIZE_X

The width of the kernel matrix. The units are specified in kernel units.

The type is UINT32.

The default value is 3.

KernelSizeY

D2D1_CONVOLVEMATRIX_PROP_KERNEL_SIZE_Y

The height of the kernel matrix. The units are specified in kernel units.

The type is UINT32.

The default value is 3.

KernelMatrix

D2D1_CONVOLVEMATRIX_PROP_KERNEL_MATRIX

The kernel matrix to be applied to the image. The kernel elements aren't bounded and are specified as floats.

The first set of KernelSizeX numbers in the FLOAT[] corresponds to the first row in the kernel. The second set of KernelSizeX numbers correspond to the second row, and so on up to KernelSizeY rows.

The type is FLOAT[].

The default value is {0.0f, 0.0f, 0.0f, 0.0f, 1.0f, 0.0f, 0.0f, 0.0f, 0.0f}.

Divisor

D2D1_CONVOLVEMATRIX_PROP_DIVISOR

The kernel matrix is applied to a pixel and then the result is divided by this value.

0 behaves as a value of float epsilon.

The type is FLOAT.

The default value is 1.0f.

Bias

D2D1_CONVOLVEMATRIX_PROP_BIAS

The effect applies the kernel matrix, the divisor, and then the bias is added to the result. The bias is unbounded and unitless.

The type is FLOAT.

The default value is 0.0f.

KernelOffset

D2D1_CONVOLVEMATRIX_PROP_KERNEL_OFFSET

Shifts the convolution kernel from a centered position on the output pixel to a position you specify left/right and up/down. The offset is defined in kernel units.

With some offsets and kernel sizes, the convolution kernel’s samples won't land on a pixel image center. The pixel values for the kernel sample are computed by bilinear interpolation.

The type is D2D1_VECTOR_2F.

The default value is {0.0f, 0.0f}.

PreserveAlpha

D2D1_CONVOLVEMATRIX_PROP_PRESERVE_ALPHA

Specifies whether the convolution kernel is applied to the alpha channel or only the color channels.

If you set this to TRUE the convolution kernel is applied only to the color channels.

If you set this to FALSE the convolution kernel is applied to all channels.

The type is BOOL.

The default value is FALSE.

BorderMode

D2D1_CONVOLVEMATRIX_PROP_BORDER_MODE

The mode used to calculate the border of the image, soft or hard. See Border modes for more info.

The type is D2D1_BORDER_MODE.

The default value is D2D1_BORDER_MODE_SOFT.

ClampOutput

D2D1_CONVOLVEMATRIX_PROP_CLAMP_OUTPUT

Whether the effect clamps color values to between 0 and 1 before the effect passes the values to the next effect in the graph. The effect clamps the values before it premultiplies the alpha .

If you set this to TRUE the effect will clamp the values. If you set this to FALSE, the effect will not clamp the color values, but other effects and the output surface may clamp the values if they are not of high enough precision.

The type is BOOL.

The default value is FALSE.

 

Scale modes

EnumerationDescription
D2D1_CONVOLVEMATRIX_SCALE_MODE_NEAREST_NEIGHBORSamples the nearest single point and uses that. This mode uses less processing time, but outputs the lowest quality image.
D2D1_CONVOLVEMATRIX_SCALE_MODE_LINEARUses a four point sample and linear interpolation. This mode outputs a higher quality image than nearest neighbor mode.
D2D1_CONVOLVEMATRIX_SCALE_MODE_CUBICUses a 16 sample cubic kernel for interpolation. This mode uses the most processing time, but outputs a higher quality image.
D2D1_CONVOLVEMATRIX_SCALE_MODE_MULTI_SAMPLE_LINEARUses 4 linear samples within a single pixel for good edge anti-aliasing. This mode is good for scaling down by small amounts on images with few pixels.
D2D1_CONVOLVEMATRIX_SCALE_MODE_ANISOTROPICUses anisotropic filtering to sample a pattern according to the transformed shape of the bitmap.
D2D1_CONVOLVEMATRIX_SCALE_MODE_HIGH_QUALITY_CUBICUses a variable size high quality cubic kernel to perform a pre-downscale the image if downscaling is involved in the transform matrix. Then uses the cubic interpolation mode for the final output.

 

Note  If you don't select a mode, the effect defaults to D2D1_CONVOLVEMATRIX_SCALE_MODE_LINEAR.

Border modes

NameDescription
D2D1_BORDER_MODE_SOFT

The effect pads the input image with transparent black pixels for samples outside of the input bounds when it applies the convolution kernel. This creates a soft edge for the image, and in the process expands the output bitmap by the size of the kernel.

D2D1_BORDER_MODE_HARD

The effect extends the input image with a mirror-type border transform for samples outside of the input bounds. The size of the output bitmap is equal to the size of the input bitmap.

 

Output bitmap

The size of the effect's output depends on the size of the convolution kernel, the kernel offset, the kernel unit length, and the border mode setting.

Sample code

For an example of this effect, download the Direct2D convolve matrix effect sample.

Requirements

Minimum supported clientWindows 8 and Platform Update for Windows 7 [desktop apps | Windows Store apps]
Minimum supported serverWindows 8 and Platform Update for Windows 7 [desktop apps | Windows Store apps]
Headerd2d1effects.h
Libraryd2d1.lib, dxguid.lib

 

Related topics

ID2D1Effect

 

 

Community Additions

ADD
Show:
© 2015 Microsoft