DiveBlitImage
This function is called to transfer an image from a source to a destination, using parameters specified by DiveSetupBlitter. The internal operation of this function varies greatly, depending on whether hardware is present; the screen is bank-switched and the image is scaled or clipped.
Syntax
_DiveBlitImage(hDiveInst, ulSrcBufNumber, ulDstBufNumber)
Parameters
- hDiveInst (HDIVE) - input
- Display engine DIVE instance.
- ulSrcBufNumber (ULONG) - input
- Indicates DIVE instance buffer number of the buffer containing the source data. This value is returned by DiveAllocImageBuffer.
- ulDstBufNumber (ULONG) - input
- The following buffer numbers are reserved for blitting to the screen:
- DIVE_BUFFER_SCREEN Results in the image being transferred to either the graphics plane buffer or the alternate plane buffer, based on whether an alternate buffer exists and the suitability of the overlay plane to accelerate the scaling of the image. If DIVE chooses to use the alternate buffer, it will also paint the overlay "key" color on the graphics plane. This automatic painting does not occur if the alternate plane is explicitly specified.
- DIVE_BUFFER_GRAPHICS_PLANE Results in the image being transferred to the graphics plane.
- DIVE_BUFFER_ALTERNATE_PLANE Results in the image being transferred to the alternate (for example, overlay) plane. If your hardware does not support such a plane, this is an error.
Returns
- rc (ULONG) - returns
- Return codes indicating success or type of failure:
- DIVE_SUCCESS If the function succeeds, 0 is returned.
- DIVE_ERR_ACQUIRE_FAILED The acquire action did not complete successfully.
- DIVE_ERR_BLITTER_NOT_SETUP DiveSetupBlitter must be called before a call is made to **DiveBlitImage**.
- DIVE_ERR_BUFFER_NOT_ACCESSED The buffer has not been accessed (occurs on systems with accelerator-enabled hardware).
- DIVE_ERR_FATAL_EXCEPTION DIVE is unable to register the exception handler to handle bank switching.
- DIVE_ERR_INVALID_INSTANCE The DIVE instance handle specified in the hDiveInst parameter is invalid.
Remarks
The buffer passed as the source on **DiveBlitImage** should be allocated with DiveAllocImageBuffer. If the source buffer data format is a hardware-supported input format, DiveAllocImageBuffer attempts to allocate the buffer in video memory on devices that require the input image to the hardware to reside in video memory.
The buffer passed as the destination on **DiveBlitImage** should be allocated with DiveAllocImageBuffer or be one of the predefined buffer numbers for one of the display planes (for example, DIVE_BUFFER_SCREEN).
Note: The screen cannot be used as the source for blitting operations.
Example Code
#include <dive.h>
HDIVE hDiveInst; /* Display engine DIVE instance. */
ULONG ulSrcBufNumber; /* Buffer containing source data. */
ULONG ulDstBufNumber; /* Identifies buffer number. */
ULONG rc; /* Return codes. */
rc = DiveBlitImage(hDiveInst, ulSrcBufNumber,
ulDstBufNumber);