DIVE Image Buffers

Because DIVE will use off-screen VRAM where available for acceleration of blitting operations, the application should allocate all source blitting buffers from DIVE whenever possible. To allocate a buffer, the application would make the following call:

ULONG   ulBufNum;
FOURCC  fccColorSpace;
ULONG   ulWidth, ulHeight, ulLineSizeBytes;
PBYTE   pbImageBuffer;

ulErrorCode = DiveAllocImageBuffer(
        hDive,          /* DIVE handle  */
        &ulBufNum,     /* Buffer number (output)       */
        fccColorSpace,  /* Color format */
        ulWidth, ulHeight,     /* Size of maximum image        */
        ulLineSizeBytes,
        &pbImageBuffer);

A corresponding DiveFreeImageBuffer function call is used to deallocate the buffer when it is no longer needed. The color format of the image buffer is described by fccColorSpace. The DIVE interface defines constants for a variety of 8-, 16-, and 24-bit color encoding schemes. After a buffer is allocated and before it can be used for blitting, it must be accessed as shown in the following example:

PBYTE   pbImageBuffer;
ULONG   ulBufferScanLineBytes, ulBufferScanLines;

ulErrorCode = DiveBeginImageBufferAccess(
        hDiveInst,          /* DIVE handle   */
        ulBufferNumber,       /* Buffer number */
        &pbImageBuffer,    /* Ptr to image buffer (output) */
        &ulBufferScanLineBytes);  /* Scan line length (output)    */
        &ulBufferScanLines);  /* Scan lines (output)    */

DIVE calculates the number of bytes per scan line for the image buffer (based on the color format) and returns the value in ulBufferScanLineBytes. The application can now write color data into pbImageBuffer. For example, the application could open a bit-map file and read the bit-map data directly into the image buffer. After the data has been written, the application calls DiveEndImageBufferAccess to deaccess the buffer. Be sure to use scan line bytes (you might have to read a line at a time).