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.
Selects the DXSurface to use as a foreground.
HRESULT SetForeground( IDXSurface *pSurface, BOOL bTile, const POINT *pOrigin );
- [in] Pointer to the interface on the surface to modify. Specifying NULL clears the previous foreground surface selection.
- [in] BOOL value which selects whether the surface should be tiled.
- [in] Optional POINT that represents the new location of the coordinate origin.
Returns an HRESULT value that depends on the implementation of the interface.
If a non-NULL pSurface is passed to this interface, the Surface Modifier 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 is 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 IDXSurfaceModifier::SetForeground method, the bounds of the output surface match the bounds of the foreground surface, regardless of previous calls to IDXSurfaceModifier::SetBounds. However, calling IDXSurfaceModifier::SetBounds after IDXSurfaceModifier::SetForeground changes the size of the output surface to the specified bounds.
Tiled images repeat infinitely to the bounds of the surface. Nontiled 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 results in an error.
The following code shows an example of this.
POINT p; p.x = p.y = 20; // The foreground surface is positioned at (20,20) within // the Surface Modifier virtual surface. SetForeground(pDXSurface, FALSE, &p); // The left 10 pixels of the foreground surface are // clipped, and the first row appears at row 20 of // the Surface Modifier. p.x = -10; SetForeground(pDXSurface, FALSE, &p)