Most display hardware imposes restrictions on displaying overlay surfaces. You must carefully meet these restrictions in order to successfully display an overlay surface. You can retrieve information about these restrictions by calling the IDirectDraw2::GetCaps method. The DDCAPS structure that the method fills contains information about overlay capabilities and their usage restrictions. Hardware restrictions vary, so always look at the flags included in the dwFlags member to determine which restrictions apply to you.
The Mosquito sample starts by retrieving the hardware capabilities, then takes action based upon the minimum stretch factor, as shown in the following code fragment:
// Get driver capabilities
ddrval = g_lpdd->GetCaps(&capsDrv, NULL);
if (FAILED(ddrval))
return FALSE;
// Check the minimum stretch and set the local variable accordingly.
if(capsDrv.dwCaps & DDCAPS_OVERLAYSTRETCH)
uStretchFactor1000 = (capsDrv.dwMinOverlayStretch>1000) ? capsDrv.dwMinOverlayStretch : 1000;
else
uStretchFactor1000 = 1000;
The code above calls IDirectDraw2::GetCaps to retrieve only the hardware capabilities. For this call, the first parameter is a pointer the DDCAPS structure that will be filled with the capability information for the device driver, and the second parameter is NULL to indicate that emulation information is not to be retrieved.
The example retains the minimum stretch factor in a temporary variable for use later. (Keep in mind that stretch factors are reported multiplied by 1000, so 1300 really means 1.3.) If the driver reports a value greater than 1000, it means that the driver requires that all destination rectangles must be stretched along the X-axis by a ratio of the reported value. For example, if the driver reports a stretch factor 1.3 and the source rectangle is 320 pixels wide, the destination rectangle must be at least 416 pixels wide. If the driver reports a stretch factor less than 1000, it means that the driver can display overlays smaller than the source rectangle, but can also stretch the overlay if desired.
Next, the sample examines values describing the driver's size alignment restrictions, as shown in the following example:
// Grab any alignment restrictions and set the local variables acordingly.
uSrcSizeAlign = (capsDrv.dwCaps & DDCAPS_ALIGNSIZESRC)?capsDrv.dwAlignSizeSrc:0;
uDestSizeAlign= (capsDrv.dwCaps & DDCAPS_ALIGNSIZESRC)?capsDrv.dwAlignSizeDest:0;
The sample uses more temporary variables to hold the reported size alignment restrictions taken from the dwAlignSizeSrc and dwAlignSizeDest members. These values provide information about pixel width alignment restrictions and are needed when setting the dimensions of the source and destination rectangles to reflect these restrictions later. Source and destination rectangles must have a pixel width that is a multiple of the values in these members.
Last, the sample examines the value that describes the destination rectangle boundary alignment:
// Set the "destination position alignment" global so we won't have to
// keep calling GetCaps() every time we move the overlay surface.
if (capsDrv.dwCaps & DDCAPS_ALIGNBOUNDARYDEST)
g_dwOverlayXPositionAlignment = capsDrv.dwAlignBoundaryDest;
else
g_dwOverlayXPositionAlignment = 0;
The preceding code uses a global variable to hold the value for the destination rectangle's boundary alignment, as taken from the dwAlignBoundaryDest member. This value will be used when the program repositions the overlay later. (For details, see Step 5: Updating the Overlay Display Position) You must set the x-coordinate of the destination rectangle's top left corner to be aligned with this value, in pixels. That is, if the value specified is 4, you can only specify destination rectangles whose top-left corner has an x-coordinate at pixels 0, 4, 8, 12, and so on. The Mosquito application initially displays the overlay at 0,0, so alignment compliance is assumed and the sample doesn't need to retrieve the restriction information until after displaying the overlay the first time. Your implementation might vary, so you will probably need to check this information and adjust the destination rectangle before displaying the overlay.