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:
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.