SetForeground method

  • Article

Selects the DXSurface to use as a foreground.

Syntax

HRESULT retVal = object.SetForeground(pSurface, bTile, pOrigin);

Parameters

  • pSurface [in]
    Type: IDXSurface

    Pointer to the interface on the surface to modify. Specifying NULL clears the previous foreground surface selection.

  • bTile [in]
    Type: BOOL

    BOOL value which selects whether the surface should be tiled.

  • pOrigin [in]
    Type: const POINT

    Optional POINT that represents the new location of the coordinate origin.

Remarks

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.

Examples

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)

See also

Reference

IDXSurfaceModifier::GetForeground

IDXSurfaceModifier::SetBounds