IDXSurfaceModifier Interface

The IDXSurfaceModifier interface is a procedural surface that uses up to two input surfaces. You use its methods to set background colors, background surfaces, and foreground surfaces, which the DXSurfaceModifier object (Surface Modifier) will use to create another surface based on the options you set. Because a Surface Modifier is a procedural surface, you don't need to call IDXTransform::Execute to produce output. The Surface Modifier exposes an IDXSurface interface, so you can call the QueryInterface method on the Surface Modifier and use the returned object as a read-only DXSurface.

Although the name "Surface Modifier" might imply that use of this interface will make permanent changes to an existing surface, the original input surfaces are not changed. The only way to see the modifications is to read samples from the DXSurface exposed by the Surface Modifier.

It is important to understand the relationship between the background surface, foreground surface, fill color, compositing function, and the Surface Modifier's bounds. The following table shows the result of setting different foreground and background surfaces with different options.

Background Surface Exists?	Foreground Surface Exists?	Result
Yes	Yes	The foreground surface will either be tiled or placed at the correct origin, depending on the option specified in the SetForeground method. If the compositing operation is set to DXSURFMOD_COMP_OVER, the tiled or centered foreground will be composited over the background surface. If the compositing operation is set to DXSURFMOD_COMP_ALPHA_MASK, all nonzero alpha pixels in the background will be used to scale the tiled or placed foreground image.
Yes	No	The fill color will fill the area of the Surface Modifier on top of the background surface if the current compositing operation is set to DXSURFMOD_COMP_OVER. But if the compositing operation is set to DXSURFMOD_COMP_ALPHA_MASK, all nonzero alpha pixels in the background will be used to scale the fill color. For example, if the background surface contained a color-keyed picture of a cat on a transparent background, and the fill color was set to blue, the result would be a blue cat.
No	Yes	If the compositing operation is set to DXSURFMOD_COMP_OVER (the default), the fill color will fill the area of the Surface Modifier and will be seen behind the foreground image. If the compositing operation is set to DXSURFMOD_COMP_ALPHA_MASK, the alpha value of the fill color will be used to scale the pixels of the foreground image.
No	No	If a fill color is specified, the background will be filled with the specified color.

If there is a background surface, the bounds of the background surface become the bounds of the surface modifier. If there is no background surface, the bounds of the surface modifier can be set to any valid value. If there is a foreground surface, it can either be placed within the bounds of the background (usually used to center an image on a larger virtual surface), or it can be tiled over the background.

The opacity and lookup table operations apply only to the foreground surface. In all cases, the opacity and lookup operations will be performed on the foreground prior to compositing with the background.

Information such as the fill color or foreground surface that has been set by previous calls to SetFillColor, SetForeground, and so on, can be cleared (or unset). You can clear this information by calling that set method again with either a zero value or NULL pointer.

To use a Surface Modifier, call the COM CoCreateInstance method, requesting a pointer to a Surface Modifier, as shown.

	IDXSurfaceModifier* cpSurfMod;
	hr = CoCreateInstance( CLSID_DXSurfaceModifier, NULL, CLSCTX_INPROC,
                                     IID_IDXSurfaceModifier, (void **)&cpSurfMod );

The background surface, fill color, and foreground surface of a Surface Modifier can be set with the IDXSurfaceModifier::SetBackground, IDXSurfaceModifier::SetFillColor, and IDXSurfaceModifier::SetForeground methods, respectively. Finally, call the QueryInterface method on the Surface Modifier to retrieve a pointer to the modified surface.

       hr = cpSurfMod->QueryInterface( IID_IDXSurface, (void**)&g_cpInSurf );

IDXSurfaceModifier Methods

GetBackground Retrieves a pointer to the DXSurface used as a background.

GetCompositeOperation Retrieves the method used for image compositing.

GetFillColor Retrieves the surface's fill color.

GetForeground Retrieves a pointer to the DXSurface used as a foreground.

GetLookup Retrieves the interface to the currently selected color lookup table.

GetOpacity Retrieves the opacity of the foreground surface.

SetBackground Sets the surface modifier background surface.

SetBounds Sets the surface's boundary structure.

SetCompositeOperation Selects the method used for image compositing.

SetFillColor Sets the surface's fill color.

SetForeground Selects the DXSurface that will be used as a foreground.

SetLookup Sets the interface to use for color lookup table operations on the foreground surface.

SetOpacity Sets the opacity of the foreground surface.

IDXSurfaceModifier::GetBackground

IDXSurfaceModifier Interface

Retrieves a pointer to the DXSurface used as a background.

Syntax

HRESULT GetBackground(
    IDXSurface **ppSurface
);

Parameters

ppSurface
[out] Address of a pointer to the interface through which you access the background surface.

Return Value

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

Remarks

If there is currently no background surface, this method will return S_OK, but ppSurface will be set to NULL. When the method is implemented, it will automatically call AddRef on the interface. The client is responsible for calling Release on the interface when it is no longer needed.

See Also

IDXSurfaceModifier::SetBackground

IDXSurfaceModifier::GetCompositeOperation

IDXSurfaceModifier Interface

Retrieves the method used for image compositing.

Syntax

HRESULT GetCompositeOperation(
    DXSURFMODCOMPOP *pCompOp
);

Parameters

pCompOp
[out] Pointer to a value that determines the method used for compositing.

Return Value

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

See Also

IDXSurfaceModifier::SetCompositeOperation, DXSURFMODCOMPOP

IDXSurfaceModifier::GetFillColor

IDXSurfaceModifier Interface

Retrieves the surface's fill color.

Syntax

HRESULT GetFillColor(
    DXSAMPLE *pColor
);

Parameters

pColor
[out] Pointer to the DXSAMPLE structure containing this surface's fill color.

Return Value

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

Remarks

If the fill color's alpha channel value is zero, no fill color has been set.

See Also

IDXSurfaceModifier::SetFillColor

IDXSurfaceModifier::GetForeground

IDXSurfaceModifier Interface

Retrieves a pointer to the DXSurface used as a foreground.

Syntax

HRESULT GetForeground(
    IDXSurface **ppSurface,
    BOOL *pbTile,
    POINT *pOrigin
);

Parameters

ppSurface
[out] Optional address of a pointer to the interface through which you access the foreground surface.

pbTile
[out] Optional pointer to a Boolean value indicating whether the foreground surface is currently tiled. If the value is TRUE, the surface will be tiled over the background. Otherwise, the value is FALSE.

pOrigin
[out] Optional pointer to the coordinates currently used as the origin.

Return Value

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

Remarks

All parameters to this method are optional. If you do not need to retrieve a particular piece of data, pass a NULL pointer for that argument.
If there is currently no foreground surface, this method will return S_OK, but ppSurface will be set to NULL. When a pointer to the interface for the foreground surface is retrieved, the method will automatically call AddRef on the interface. The client is responsible for calling Release on the interface when it is no longer needed.

See Also

IDXSurfaceModifier::SetBackground

IDXSurfaceModifier::GetLookup

IDXSurfaceModifier Interface

Retrieves the interface to the currently selected color lookup table.

Syntax

HRESULT GetLookup(
    IDXLookupTable **ppLookupTable
);

Parameters

ppLookupTable
[out] Address of a pointer that will be initialized to the current lookup table object of the Surface Modifier.

Return Value

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

Remarks

If there is currently no lookup table operator, this function will return S_OK, but ppLookupTable will be set to NULL. Otherwise, the returned pointer will point to an IDXLookupTable interface. When the method is implemented, it will automatically call AddRef on the interface. The client is responsible for calling Release on the interface when it is no longer needed.
The lookup table is applied to the foreground surface only.

See Also

IDXSurfaceModifier::SetLookup

IDXSurfaceModifier::GetOpacity

IDXSurfaceModifier Interface

Retrieves the opacity of the foreground surface.

Syntax

HRESULT GetOpacity(
    float *pOpacity
);

Parameters

pOpacity
[out] Pointer to a value that indicates the opacity of the foreground surface. Values can range from 0.0 (fully transparent) to 1.0 (fully opaque).

Return Value

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

Remarks

The opacity value is applied to the foreground surface when it is composited over the background surface.

See Also

IDXSurfaceModifier::SetOpacity

IDXSurfaceModifier::SetBackground

IDXSurfaceModifier Interface

Sets the surface modifier background surface.

Syntax

HRESULT SetBackground(
    IDXSurface *pSurface
);

Parameters

pSurface
[in] Pointer to the surface to be used as a background surface; this parameter can be NULL to indicate no background surface.

Return Value

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

Remarks

If pSurface is NULL, the current bounds of the surface will not be changed. If there is a fill color, the Surface Modifier will use the fill color as the background color.
If pSurface is not NULL, the Surface Modifier will use the size of the background surface as its bounds, overriding any previous call to SetBounds. Any subsequent calls to SetBounds must specify a bounds equal to the bounds of the background surface or else an error will result. For more information about the relationship of various properties of Surface Modifiers, see the introduction.

See Also

IDXSurfaceModifier::GetBackground

IDXSurfaceModifier::SetBounds

IDXSurfaceModifier Interface

Sets the surface's volume boundary structure.

Syntax

HRESULT SetBounds(
    const DXBNDS *pBounds
);

Parameters

pBounds
[in] Pointer to the DXBNDS boundary structure containing this surface's bounding volume. This pointer can be NULL to clear a previous call to SetBounds.

Return Value

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

Remarks

The SetBounds method is only used to set the height and width of the entire visible surface; it does not specify where the image will be blitted on the output surface.
If there is a set background surface, this call will fail if the bounds specified are any size other than the bounds of the background surface. If no background surface is set, the bounds can be any valid size.

IDXSurfaceModifier::SetCompositeOperation

IDXSurfaceModifier Interface

Selects the method used for image compositing.

Syntax

HRESULT SetCompositeOperation(
    DXSURFMODCOMPOP CompOp
);

Parameters

CompOp
[in] A DXSURFMODCOMPOP value that determines the method used for compositing.

Return Value

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

Remarks

By default, the compositing operation is DXSURFMOD_COMP_OVER.
When the compositing operation is DXSURFMOD_COMP_OVER, the foreground surface will be composited over the background surface. If there is no background surface, the foreground surface will be composited over the fill color.
When the compositing operation is DXSURFMOD_COMP_ALPHA_MASK, the foreground surface will use the alpha values of the background surface to weight the foreground surface pixel values; the colors of the background surface will be ignored. If there is no background surface, the alpha value of the fill color will be used to weight the foreground surface pixel values. However, this is much less efficient than using the SetOpacity method.

See Also

IDXSurfaceModifier::GetCompositeOperation, IDXSurfaceModifier::SetOpacity, DXSURFMODCOMPOP

IDXSurfaceModifier::SetFillColor

IDXSurfaceModifier Interface

Sets the surface's fill color.

Syntax

HRESULT SetFillColor(
    DXSAMPLE Color
);

Parameters

Color
[in] DXSAMPLE structure containing the surface's fill color. Sending a value of zero clears the previous color value.

Return Value

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

Remarks

The alpha value of the fill color is used and must be set to 255 if you want a solid fill color. Any fill color that has an alpha value of zero will be interpreted without a fill color.
Calling SetFillColor before or after SetBackground will have no effect on the resulting image.

See Also

IDXSurfaceModifier::GetFillColor

IDXSurfaceModifier::SetForeground

IDXSurfaceModifier Interface

Selects the DXSurface that will be used as a foreground.

Syntax

HRESULT SetForeground(
    IDXSurface *pSurface,
    BOOL bTile,
    const POINT *pOrigin
);

Parameters

pSurface
[in] Pointer to the interface on the surface you intend to modify. Specifying NULL clears the previous foreground surface selection.

bTile
[in] Boolean value which selects whether the surface should be tiled.

pOrigin
[in] Optional point that represents the new location of the coordinate origin.

Return Value

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

Remarks

If a non-NULL pSurface is passed to this interface, the Surface Modifier's foreground surface is set to the new pSurface. If pOrigin is NULL, the origin used is (0,0). The origin's interpretation is based on the setting of bTile. If bTile is false, the foreground surface will be placed within the bounds of the Surface Modifier with the upper-left pixel of the surface appearing at the specified origin within the Surface Modifier. If bTile is TRUE, the origin specifies the first pixel within the foreground surface to start at when tiling the image.
When you call the SetForeground method, the bounds of the output surface will match the bounds of the foreground surface, regardless of previous calls to SetBounds. However, calling SetBounds after SetForeground will change the size of the output surface to the specified bounds.
Tiled images repeat infinitely to the bounds of the surface. Non-tiled foreground surfaces can be used to place the image within a larger virtual space or to clip the image to a smaller size. Negative origins are valid for images that are not tiled. Setting negative values for the origin on tiled foregrounds will result in an error.
The following code shows an example of this.
POINT p;
p.x = p.y = 20;

// The foreground surface positioned at (20,20) within
// the Surface Modifier's virtual surface.
SetForeground(pDXSurface, FALSE, &p);    

// The Surface Modifier's pixel value at (0,0) will be
// the foreground surface's pixel at (20,20).                                     
SetForeground(pDXSurface, TRUE, &p);     


// The left 10 pixels of the foreground surface will be
// clipped, and the first row will appear at row 20 of
// the Surface Modifier.
p.x = -10;
SetForeground(pDXSurface, FALSE, &p)   

See Also

IDXSurfaceModifier::GetForeground, IDXSurfaceModifier::SetBounds

IDXSurfaceModifier::SetLookup

IDXSurfaceModifier Interface

Sets the interface to use for color lookup table operations on the foreground surface.

Syntax

HRESULT SetLookup(
    IDXLookupTable *pLookupTable
);

Parameters

pLookupTable
[in] Pointer to and IDXLookupTable interface to use for color adjustment to the foreground surface.

Return Value

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

Remarks

To set a lookup table for a Surface Modifier, you must first build one with the IDXLUTBuilder interface and get from it a pointer to an IDXLookupTable interface. To clear a previous lookup table selection, call this method with a NULL pointer.
The lookup table is applied to the foreground surface only.

See Also

IDXSurfaceModifier::GetLookup

IDXSurfaceModifier::SetOpacity

IDXSurfaceModifier Interface

Sets the opacity of the foreground surface.

Syntax

HRESULT SetOpacity(
    float Opacity
);

Parameters

Opacity
[in] Value that indicates the opacity of the foreground surface. Values can range from 0.0 (fully transparent) to 1.0 (fully opaque).

Return Value

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

Remarks

The opacity value is applied to the foreground surface when it is composited over the background surface.

See Also

IDXSurfaceModifier::GetOpacity

GetBackground	Retrieves a pointer to the DXSurface used as a background.
GetCompositeOperation	Retrieves the method used for image compositing.
GetFillColor	Retrieves the surface's fill color.
GetForeground	Retrieves a pointer to the DXSurface used as a foreground.
GetLookup	Retrieves the interface to the currently selected color lookup table.
GetOpacity	Retrieves the opacity of the foreground surface.
SetBackground	Sets the surface modifier background surface.
SetBounds	Sets the surface's boundary structure.
SetCompositeOperation	Selects the method used for image compositing.
SetFillColor	Sets the surface's fill color.
SetForeground	Selects the DXSurface that will be used as a foreground.
SetLookup	Sets the interface to use for color lookup table operations on the foreground surface.
SetOpacity	Sets the opacity of the foreground surface.