GPE::BltPrepare

This method, which is called prior to a sequence of clipped blit operations, identifies the appropriate functions needed to perform individual blits.

Syntax

SCODE GPE::BltPrepare(GPEBltParms *pBltParms );

Parameters

pBltParms

Pointer to a GPEBltParms structure containing parameters for the blit operation.

Return Values

S_OK indicates success.

Remarks

The following code example shows the simplest acceptable implementation for GPE::BltPrepare.

pBltParms->pBlt = EmulatedBlt;
return S_OK;

This action causes the emulated blit function provided with GPE to be used for blit operations.

For improved performance, the BltPrepare method can examine the characteristics of the blit and the associated surfaces defined in GPEBltParms to determine whether an accelerated form of the blit is used. The following code example shows how to determine the operations that are likely to be implemented in hardware.

if( pBltParms->pDst->InVideoMemory() && pBltParms->rop4 == 0x0000 )
    // This is a fill of BLACKNESS in video memory.
if( pBltParms->pDst->InVideoMemory() && pBltParms->rop4 == 0xFFFF )
    // This is a fill of WHITENESS in video memory.
if( pBltParms->pDst->InVideoMemory()
&& pBltParms->rop4 == 0xF0F0
&& pBltParms->solidColor != 0xFFFFFFFF )
    // This is a fill of a solid color in video memory.
if( pBltParms->pDst->InVideoMemory()
&& pBltParms->pSrc->InVideoMemory()
&& pBltParms->rop4 == 0xCCCC
&& !pBltParms->pLookup
&& !pBltParms->pConvert )
    // This is a source copy (SRCCOPY) between two surfaces, both in
    // video memory, with no color translation.

To accelerate these types of blit, BltPrepare places the address of the accelerated function in the pBlt member of the GPEBltParms structure, instead of in the pointer to the EmulatedBlt function. For operations such as solid color fills, the driver can prepare the hardware. For example, the driver can place a solid color into the appropriate register of the hardware. This obviates the need to repeat the same action in every call to the accelerated blit handler.