DiveAllocImageBuffer

This function allocates a buffer to contain an image. Source data buffers passed to DiveBlitImage must be allocated with this function in order to take advantage of hardware acceleration features of some display hardware.

Syntax

_DiveAllocImageBuffer(hDiveInst, pulBufferNumber, fccColorSpace, ulWidth, ulHeight, ulLineSizeBytes, pbImageBuffer)

Parameters

hDiveInst (HDIVE) - input

Display engine DIVE instance.

pulBufferNumber (PULONG) - output

Buffer number allocated for this instance.

fccColorSpace (FOURCC) - input

Indicates pel format of image color space this buffer will contain.

ulWidth (ULONG) - input

Indicates width (in pels) of DIVE memory to allocate.

ulHeight (ULONG) - input

Indicates height (in pels) of DIVE memory to allocate.

ulLineSizeBytes (ULONG) - input

Suggested scan line size for allocated buffer. Setting ulLineSizeBytes to 0 allows DIVE to calculate the optimum line size.

pbImageBuffer (PBYTE) - input

Use pbImageBuffer to associate a buffer (that has already been allocated by some means other than DIVE) to a DIVE buffer number. You must still call DiveFreeImageBuffer to free up the associated buffer and deallocate the buffer using the same means in which it was allocated.

Returns

rc (ULONG) - returns

Return codes indicating success or type of failure:

• DIVE_SUCCESS If the function succeeds, 0 is returned.
• DIVE_ERR_ALLOCATION_ERROR The hardware-blitter memory allocation failed.
• DIVE_ERR_INVALID_BUFFER_NUMBER The parameter pulBufferNumber must either point to zero (a newly associated buffer) or a currently associated buffer number (to reassociate the buffer to a new pointer).
• DIVE_ERR_INVALID_INSTANCE The DIVE instance handle specified in the hDiveInst parameter is invalid.
• DIVE_ERR_INVALID_LINESIZE The scan line size specified in the ulLineSizeBytes parameter is invalid.
• DIVE_ERR_SOURCE_FORMAT The source format is not a recognized FOURCC.
• DIVE_ERR_TOO_MANY_INSTANCES There are not enough resources for another DIVE instance.

Remarks

This function will allocate a buffer to contain an image. The buffer may be allocated in either system memory or in VRAM, depending on a number of factors. The entire image buffer will be allocated in video memory if all of the following conditions are met:

• Display hardware that accelerates certain operations is installed, and that hardware requires the source image data to reside in video memory.
• The source image data is in a format that the hardware accepts as an input for accelerating certain operations.
• Sufficient VRAM is available to hold the image.

If any of these conditions are not met, the buffer will be allocated in system memory.

If pbImageBuffer is 0, DIVE will allocate a buffer for the specified size and FOURCC. If pbImageBuffer is a pointer to a non-DIVE-allocated buffer, DIVE will associate a buffer number to that pointer.

Even though no memory is allocated by **DiveAllocImageBuffer** when user-allocated buffers are associated, DiveFreeImageBuffer should be called to release the buffer association to avoid using up available buffer indexes. The specified line size will be used if a buffer is allocated in system memory, or if a user buffer is associated. If the specified line size is zero, the allocated line size is rounded up to the nearest ULONG boundary.

Because only one blitter setup is supported at any time for an instance, if multiple source buffers are allocated in an instance, they must be of the same size and color space to work with DiveBlitImage.

Note: If hardware acceleration is present and the fccColorSpace format is supported as input to the hardware, the allocation will be performed with a devescape_imgbufalloc call to the display driver. If the format is not supported by hardware or if hardware acceleration is not available, the buffer will be allocated in system memory using DosAllocMem.

Example Code

#include <dive.h>

HDIVE hDiveInst;         /* Display engine DIVE instance. */
PULONG pulBufferNumber;  /* Buffer number allocated. */
FOURCC fccColorSpace;    /* Pel format of image color space. */
ULONG ulWidth;           /* Width of DIVE memory to allocate. */
ULONG ulHeight;          /* Height of DIVE memory to allocate. */
ULONG ulLineSizeBytes;   /* Suggested scan line size. */
PBYTE pbImageBuffer;     /* Image buffer. */
ULONG rc;                /* Return codes. */

rc = DiveAllocImageBuffer(hDiveInst, pulBufferNumber,
        fccColorSpace, ulWidth, ulHeight, ulLineSizeBytes,
        pbImageBuffer);