IDXSurfaceModifier interface

The IDXSurfaceModifier interface is a procedural surface that uses up to two input surfaces. The methods of this interface set background colors, background surfaces, and foreground surfaces, which the DXSurfaceModifier object (Surface Modifier) uses to create another surface based on the options you set.

Members

The IDXSurfaceModifier interface inherits from the IUnknown interface. IDXSurfaceModifier also has these types of members:

• Methods

Methods

The IDXSurfaceModifier interface has these methods.

Method	Description
GetBackground	Retrieves a pointer to the DXSurface used as a background.
GetCompositeOperation	Retrieves the method used for image compositing.
GetFillColor	Retrieves the surface fill color.
GetForeground	Retrieves a pointer to the DXSurface used as a foreground.
GetLookup	Retrieves the interface to the selected color lookup table.
GetOpacity	Retrieves the opacity of the foreground surface.
SetBackground	Sets the surface modifier background surface.
SetBounds	Sets the surface's volume boundary structure.
SetCompositeOperation	Selects the method used for image compositing.
SetFillColor	Sets the surface fill color.
SetForeground	Selects the DXSurface to use 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.

 

Remarks

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 term Surface Modifier implies that this interface makes 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 is either tiled or placed at the correct origin, depending on the option specified in the IDXSurfaceModifier::SetForeground method. If the compositing operation is set to DXSURFMOD_COMP_OVER, the tiled or centered foreground is composited over the background surface. If the compositing operation is set to DXSURFMOD_COMP_ALPHA_MASK, all nonzero alpha pixels in the background are used to scale the tiled or placed foreground image.
Yes	No	The fill color fills 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 are used to scale the fill color. For example, if the background surface contains a color-keyed picture of a cat on a transparent background, and the fill color is set to blue, the result is a blue cat.
No	Yes	If the compositing operation is set to DXSURFMOD_COMP_OVER (the default), the fill color fills the area of the Surface Modifier and is seen behind the foreground image. If the compositing operation is set to DXSURFMOD_COMP_ALPHA_MASK, the alpha value of the fill color is used to scale the pixels of the foreground image.
No	No	If a fill color is specified, the background is 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 are 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 IDXSurfaceModifier::SetFillColor, IDXSurfaceModifier::SetForeground, and so on, can be cleared. You can clear this information by calling the set method again with either a zero value or NULL pointer.

To use a Surface Modifier, call the Component Object Model (COM) CoCreateInstance method, requesting a pointer to a Surface Modifier, as shown in the following code example.

   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 );

Requirements

Minimum supported client	Windows XP
Minimum supported server	Windows 2000 Server
Header	Dxtrans.h
IDL	Dxtrans.idl
DLL	Dxtrans.dll