View source for DiveAllocImageBuffer

{{DISPLAYTITLE: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==
<PRE>
#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);
</PRE>

[[Category:Dive]]