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