IDXTConvolution Interface

The IDXTConvolution interface performs image convolutions for DXSurface objects. This is more commonly known as filtering. The convolution works by combining the colors of surrounding samples to determine the color of a sample on the destination surface. The way in which surrounding pixels are combined is determined by a filter, which is a rectangular matrix of numbers. Each number in the matrix is a weighting for the pixel at that position. The contributions from each weighting are added to produce the output color on the destination surface. Negative weighting values are subtracted from the total. Each filter matrix has a center pixel that is scanned over each sample of the input image to produce the output image.

The filter matrix has a width and height that determine how many pixels of the source image will contribute to the color of the destination's center pixel. Most matrices are square and have an odd number of rows and columns, though you can define custom filters of arbitrary size. There are also predefined filters described in the DXCONVFILTERTYPE enumeration.

Sometimes convolution can reduce or increase the brightness of an image. To compensate, you can define a bias that is added to the filtered result.

IDXTConvolution Methods

GetBias Retrieves the bias value used for the convolution.

GetConvertToGray Retrieves whether the filter output color will be converted to grayscale.

GetExcludeAlpha Retrieves whether the alpha channel should be filtered along with the color data.

GetFilterType Retrieves the currently selected filter type for the convolution.

SetBias Sets the bias value used for the convolution.

SetConvertToGray Sets whether the filter output color will be converted to grayscale.

SetCustomFilter Sets the convolution to use a custom filter.

SetExcludeAlpha Sets whether the alpha channel should be filtered along with the color data.

SetFilterType Sets the currently selected filter type for the convolution.

IDXTConvolution::GetBias

IDXTConvolution Interface

Retrieves the bias value used for the convolution.

Syntax

HRESULT GetBias(
    float *pBias
);

Parameters

pBias
[out] Pointer to a float value, from –1.0 to 1.0, used for the filter bias.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The bias is a percentage of a byte value added to each color component of the filtered result. Larger bias values lead to brighter filtered images.

IDXTConvolution::GetConvertToGray

IDXTConvolution Interface

Retrieves whether the filter output color will be converted to grayscale.

Syntax

HRESULT GetConvertToGray(
    BOOL *pbConvertToGray
);

Parameters

pbConvertToGray

[out] Pointer to a Boolean value that indicates whether an image is converted to grayscale after a convolution. If TRUE, the colors of the image are converted to gray after filtering.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDXTConvolution::GetExcludeAlpha

IDXTConvolution Interface

Retrieves whether the alpha channel should be filtered along with the color data.

Syntax

HRESULT GetExcludeAlpha(
    BOOL *pbExcludeAlpha
);

Parameters

pbExcludeAlpha
[out] Pointer to a Boolean value that indicates whether the alpha channel of an image should be filtered. If TRUE, only the RGB color components are modified by the filter. If FALSE, the weighted alpha value is written to the output sample with the color value.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDXTConvolution::GetFilterType

IDXTConvolution Interface

Retrieves the currently selected filter type for the convolution.

Syntax

HRESULT GetFilterType(
     DXCONVFILTERTYPE *peType
);

Parameters

peType
[out] Pointer to a member of the DXCONVFILTERTYPE enumeration that indicates the currently selected filter.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDXTConvolution::SetBias

IDXTConvolution Interface

Sets the bias value used for the convolution.

Syntax

HRESULT SetBias(
	float Bias
);

Parameters

Bias
[in] Float value, from –1.0 to 1.0, to use for the filter bias.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The bias is a percentage of a byte value added to each color component of the filtered result. Larger bias values lead to brighter filtered images.

IDXTConvolution::SetConvertToGray

IDXTConvolution Interface

Sets whether the filter output color will be converted to grayscale.

Syntax

HRESULT SetConvertToGray(
    BOOL bConvertToGray
);

Parameters

bConvertToGray

[in] Boolean value that indicates whether an image is converted to grayscale after a convolution. If TRUE, the colors of the image are converted to gray after filtering.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDXTConvolution::SetCustomFilter

IDXTConvolution Interface

Sets the convolution to use a custom filter.

Syntax

HRESULT SetCustomFilter(
    float *pFilter,
    SIZE Size
);

Parameters

pFilter
[in] Pointer to an array of custom filter values.

Size
[in] Size of the custom filter, in pixels.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The height and width of the custom filter must be greater than or equal to 1. Most filters define a center pixel that is scanned over the input image to produce the output image. For even-sized dimensions, the center pixel for that dimension is the length divided by two. For example, a 5 × 4 custom filter has a center pixel at (2,2).

IDXTConvolution::SetExcludeAlpha

IDXTConvolution Interface

Sets whether the alpha channel should be filtered along with the color data.

Syntax

HRESULT SetExcludeAlpha(
    BOOL bExcludeAlpha
);

Parameters

bExcludeAlpha
[in] Boolean value that indicates whether the alpha channel of an image should be filtered. If TRUE, only the RGB color components are modified by the filter. If FALSE, the weighted alpha value is written to the output sample with the color value.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDXTConvolution::SetFilterType

IDXTConvolution Interface

Sets the currently selected filter type for the convolution.

Syntax

HRESULT SetFilterType(
    DXCONVFILTERTYPE eType
);

Parameters

eType
[in] Member of the DXCONVFILTERTYPE enumeration that indicates the currently selected filter.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

If you set the filter type to DXCFILTER_SRCCOPY, all other properties that were previously set, such as SetConvertToGray, are ignored.

GetBias	Retrieves the bias value used for the convolution.
GetConvertToGray	Retrieves whether the filter output color will be converted to grayscale.
GetExcludeAlpha	Retrieves whether the alpha channel should be filtered along with the color data.
GetFilterType	Retrieves the currently selected filter type for the convolution.
SetBias	Sets the bias value used for the convolution.
SetConvertToGray	Sets whether the filter output color will be converted to grayscale.
SetCustomFilter	Sets the convolution to use a custom filter.
SetExcludeAlpha	Sets whether the alpha channel should be filtered along with the color data.
SetFilterType	Sets the currently selected filter type for the convolution.