DiveSetupBlitter
This function sets up blitter operations.
Syntax
_DiveSetupBlitter(hDiveInst, pSetupBlitter)
Parameters
- hDiveInst (HDIVE) - input
- Display engine DIVE instance.
- pSetupBlitter (PSETUP_BLITTER) - input
- Pointer to SETUP_BLITTER. This data structure contains parameters that will be used during the subsequent DiveBlitImage call. If this pointer is **zero** on input, this function will deinitialize the blitter and subsequent calls to DiveBlitImage will return **DIVE_ERR_BLITTER_NOT_SETUP**.
- The ulStructLen field specifies the number of fields that are valid on input. Fields that are not specified as valid on input are considered to be unchanged from previous calls to DiveSetupBlitter. For example, if the visible rectangles have not changed, the structure length can be set to exclude the ulNumDstRects and pVisDstRects fields of SETUP_BLITTER, thereby enabling a performance optimization in the function.
Returns
- rc (ULONG) - returns
- Return codes indicating success or type of failure:
- DIVE_SUCCESS If the function succeeds, 0 is returned.
- DIVE_ERR_INVALID_CONVERSION The source image format cannot be converted as requested to the destination image format.
- DIVE_ERR_INVALID_INSTANCE The DIVE instance handle specified in the hDiveInst parameter is invalid.
- DIVE_ERR_SOURCE_FORMAT The source format is not a recognized FOURCC.
- DIVE_WARN_NO_SIZE No blitting will occur because either the destination width or height is zero.
Remarks
The visible rectangles are passed using the pVisDstRects parameter of SETUP_BLITTER. These rectangles are relative to the destination window origin. The display engine will determine if it is fully visible if ulNumDstRects = 1 and the first **pVisDstRects** = {0, 0, width, height}. The display engine will also assume the image is fully clipped if ulNumDstRects = 0 or if ulNumDstRects = 1 and the rectangle width or height are zero.
If DiveSetupBlitter determines that the requested blitter operations to follow can be performed partially or wholly using display hardware features, it will do so. If the requested input format is supported by the software emulation within the display engine but not by the display hardware, DiveSetupBlitter will enable conversion to a format that is supported by the hardware to an internally allocated buffer. The converted image will, in turn, be transferred from the internal buffer to the screen by the hardware.
When PM sends a WM_VRNDISABLED message, the application must inform DIVE that the visible regions are about to enter a changing state. This is done with a call to `DiveSetupBlitter( hDive, 0 )`. When the state of visible regions again becomes static, PM sends a WM_VRNENABLED message and a normal call to DiveSetupBlitter is used.
DiveSetupBlitter was not intended to be called at high frequency. If several different source/destination size pairs are to be used, try opening several instances to increase performance.
- Note: The fNonScreenInstance parameter specified on DiveOpen indicates whether or not DiveSetupBlitter should use acceleration hardware when present.
Example Code
#include <dive.h> HDIVE hDiveInst; /* Display engine DIVE instance. */ PSETUP_BLITTER pSetupBlitter; /* Pointer to SETUP_BLITTER. */ ULONG rc; /* Return codes. */ rc = DiveSetupBlitter(hDiveInst, pSetupBlitter);