Export (0) Print
Expand All

IDXSurfaceModifier Interface

This topic documents a feature of Visual Filters and Transitions, which is deprecated as of Windows Internet Explorer 9 and obsolete as of Internet Explorer 10.

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.

IDXSurfaceModifier Members

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

Interface Information

Stock Implementation dxtrans.dll
Custom Implementation No
Inherits from IUnknown
Header and IDL files dxtrans.h, dxtrans.idl
Minimum availability Internet Explorer 4.0
Minimum operating systems Windows 95, Windows NT 4.0

Community Additions

ADD
Show:
© 2014 Microsoft