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

After you've set up the source and destination rectangles, you can display the overlay for the first time. If you've prepared correctly, this will be simple. The Mosquito sample uses the following code to initially display the overlay:

    // Set the flags we'll send to UpdateOverlay
    dwUpdateFlags = DDOVER_SHOW | DDOVER_DDFX;
 
    // Does the overlay hardware support source color keying?
    // If so, we can hide the black background around the image.
    // This probably won't work with YUV formats
    if (capsDrv.dwCKeyCaps & DDCKEYCAPS_SRCOVERLAY)
        dwUpdateFlags |= DDOVER_KEYSRCOVERRIDE;
 
    // Create an overlay FX structure so we can specify a source color key.
    // This information is ignored if the DDOVER_SRCKEYOVERRIDE flag isn't set.
    ZeroMemory(&ovfx, sizeof(ovfx));
    ovfx.dwSize = sizeof(ovfx);
 
    ovfx.dckSrcColorkey.dwColorSpaceLowValue=0; // Specify black as the color key
    ovfx.dckSrcColorkey.dwColorSpaceHighValue=0;
 
    // Call UpdateOverlay() to displays the overlay on the screen.
    ddrval = g_lpddsOverlay->UpdateOverlay(&rs, g_lpddsPrimary, &rd, dwUpdateFlags, &ovfx);
    if(FAILED(ddrval))
        return FALSE;
 

The preceding example starts by setting the DDOVER_SHOW and DDOVER_DDFX flags in the dwUpdateFlags temporary variable, indicating that the overlay is to be displayed for the first time, and that the hardware should use the effects information included in an associated DDOVERLAYFX structure to do so. Next, the example checks a previously existing DDCAPS structure to determine if overlay source color keying is supported. If it is, the DDOVER_KEYSRCOVERRIDE is included in the dwUpdateFlags variable to take advantage of source color keying and the example sets color key values accordingly.

After preparation is complete, the example calls the IDirectDrawSurface7::UpdateOverlay method to display the overlay. For the call, the first and third parameters are the addresses of the adjusted source and destination rectangles. The second parameter is the address of the primary surface over which the overlay will be displayed. The fourth parameter consists of the flags placed in the previously prepared dwUpdateFlags variable, and the fifth parameter is the address of DDOVERLAYFX structure whose members were set to match those flags.

If the hardware only supports one overlay surface and that surface is in use, the UpdateOverlay method fails, returning DDERR_OUTOFCAPS. Additionally, if UpdateOverlay fails, you might try increasing the width of the destination rectangle to accommodate for the possibility that the hardware incorrectly reported a minimum stretch factor that was too small. However, this rarely occurs and Mosquito simply fails if UpdateOverlay doesn't succeed.

Next: Step 5: Update the Overlay Display Position