Name
hw_RawBltBitMap -- blit source to destination pixel buffer (V6.0)
Synopsis
void hw_RawBltBitMap(APTR src, APTR dst, struct hwRawBltBitMapCtrl *ctrl,
         ULONG flags, struct hwTagList *tags);
Function
This function can be used to blit data from a source to a destination raw pixel buffer. Note that this function does not accept Hollywood bitmaps, but expects you to pass raw pixel buffers only. This makes it possible to use hw_RawBltBitMap() in lots of different contexts. If you want to use hw_RawBltBitMap() on Hollywood bitmaps, you need to lock those bitmaps first using hw_LockBitMap() and then pass the raw pixel buffer pointer obtained by hw_LockBitMap() to hw_RawBltBitMap().

Optionally, hw_RawBltBitMap() can take a mask or alpha channel pixel buffer into account. In case an alpha channel pixel buffer is specified, hw_RawBltBitMap() will also do the blending for you.

You have to pass source and destination pixel buffer pointers as well as a pointer to a struct hwRawBltBitMapCtrl to this function. struct hwRawBltBitMapCtrl looks like this:

 
struct hwRawBltBitMapCtrl
{
    int SrcX;           // [in]
    int SrcY;           // [in]
    int DstX;           // [in]
    int DstY;           // [in]
    int Width;          // [in]
    int Height;         // [in]
    int PixFmt;         // [in]
    UBYTE *MaskData;    // [in]
    UBYTE *AlphaData;   // [in]
    int SrcModulo;      // [in]
    int DstModulo;      // [in]
    int MaskModulo;     // [in]
    int AlphaModulo;    // [in]
};

Here's an explanation of the individual structure members:

SrcX:
Contains the x position in the source buffer that marks the start offset for the copy operation. This is relative to the upper-left corner of the source buffer.

SrcY:
Contains the y position in the source buffer that marks the start offset for the copy operation. This is relative to the upper-left corner of the source buffer.

DstX:
Contains the destination x position relative to the upper-left corner.

DstY:
Contains the destination y position relative to the upper-left corner.

Width:
Contains the number of columns to copy.

Height:
Contains the number of rows to copy.

PixFmt:
Contains the pixel format used by the source and destination pixel buffers. Both buffers must use the same pixel format. See Pixel format information for details.

SrcModulo:
This must be set to the number of pixels per row in the source buffer. This can be more than the actual image width in case there are padding pixels.

DstModulo:
This must be set to the number of pixels per row in the destination buffer. This can be more than the actual destination image width in case there are padding pixels.

MaskData:
This can be set to a pointer containing an array of raw mask bits. Hollywood masks only know two different states: visible (1) and invisible (0) pixels. The bits are stored from left to right in chunks of one byte, i.e. the most significant bit of the first byte describes the transparency setting for the first pixel. The buffer provided here must be exactly MaskModulo bytes wide and must match the source buffer's height. If you don't want to use masked blitting, set this to NULL.

MaskModulo:
If you specify a mask bitplane in MaskData, you need to set this member to the number of bytes that is used for one row of mask data. Note that this value is specified in bytes and often needs to use some padding. For example, if the source buffer is 123 pixels wide, the MaskModulo value would usually be set to 16 because 15 bytes are not enough for 123 pixels.

AlphaData:
This member can be set to an array containing alpha channel values for every pixel. This array must use one byte for every pixel and must match the source buffer's height. The width of the alpha channel array can be specified by setting the AlphaModulo member (see below). If this member is specified, hw_RawBltBitMap() will do blit the source pixel buffer to the destination pixel buffer with alpha blending. If you don't want to use alpha blending, set this to NULL.

AlphaModulo:
If AlphaData has been provided, this member must be set to the number of pixels stored in one row of the AlphaData array. This can be more than the source buffer's width in case you need padding.

The following tags are recognized by hw_RawBltBitMap():

HWRBBTAG_CLIPRECT:
This tag can be used to make hw_RawBltBitMap() clip its output to the specified clipping rectangle. If you pass this tag, you must set the pData member of the tag to a struct hwRect containing the desired clipping rectangle. Note that by default there is no clipping at all, so you must make sure that the destination raw pixel buffer is large enough. (V8.0)

Designer compatibility
Unsupported

Inputs
src
pointer to source raw pixel buffer
dst
pointer to destination raw pixel buffer
ctrl
pointer to a struct hwRawBltBitMapCtrl containing the blit parameters
flags
reserved for future use; pass 0
tags
reserved for future use; pass NULL
Show TOC