The information in this section pertains only to applications written in C and C++. See DirectDraw Visual Basic Tutorials.

After displaying the overlay surface, you might not need to do anything else. However, some software might need to reposition the overlay surface. The Mosquito sample uses the IDirectDrawSurface7::SetOverlayPosition method to reposition the overlay, as shown in the following example.

    // Set x- and y-coordinates
    .
    .
    .
    // We need to check for any alignment restrictions on the 
    // x-position and align it if necessary.
    if (g_dwOverlayXPositionAlignment)
        dwXAligned = g_nOverlayXPos - g_nOverlayXPos % g_dwOverlayXPositionAlignment;
    else
        dwXAligned = g_nOverlayXPos;
 
    // Set the overlay to its new position.
    ddrval = g_lpddsOverlay->SetOverlayPosition(dwXAligned, g_nOverlayYPos);
    if (ddrval == DDERR_SURFACELOST)
    {
        if (!RestoreAllSurfaces()) 
            return;
    }
 

The preceding example starts by aligning the rectangle to meet any destination rectangle boundary alignment restrictions that might exist. The global variable that it checks, g_dwOverlayXPositionAlignment, was set earlier to equal the value reported in the dwAlignBoundaryDest member of the DDCAPS structure when the application previously called the IDirectDraw7::GetCaps method. (For details, see Step 4.1: Determine the Minimum Display Requirements). If destination alignment restrictions exist, the example adjusts the new x-coordinate to be pixel-aligned accordingly. Failing to meet this requirement will cause the overlay surface not to be displayed.

After making any requisite adjustments to the new x-coordinate, the example calls IDirectDrawSurface7::SetOverlayPosition method to reposition the overlay. For the call, the first parameter is the aligned x-coordinate, and the second parameter is the new y-coordinate. These values represent the new location of the overlay's top-left corner. Width and height information are not accepted, nor are they needed because DirectDraw already knows the dimensions of the surface from the IDirectDrawSurface7::UpdateOverlay method made to initially display the overlay. If the call fails because one or more surfaces were lost, the example calls an application-defined function to restore them and reload their bitmaps.

Note  Take care not to use coordinates too close to the bottom or right edge of the target surface. The IDirectDraw7::SetOverlayPosition method does not perform clipping for you; using coordinates that would potentially make the overlay run off the edge of the target surface will cause the method to fail, returning DDERR_INVALIDPOSITION.

Next: Step 6: Hide the Overlay Surface