Name
hw_BitMapToARGB -- convert Hollywood bitmap to ARGB pixel buffer (V6.0)
Synopsis
ULONG *rgb = hw_BitMapToARGB(APTR bmap, APTR mask, APTR alpha,
                 struct hwTagList *tags);
Function
This function can be used to get the pixels of a Hollywood bitmap as a 32-bit ARGB pixel buffer. Optionally, this function can also take an additional mask or alpha channel bitmap into account and combine its transparency information into the pixel buffer it returns. The advantage over functions like hw_LockBitMap() is that hw_BitMapToARGB() will convert the pixels to the 32-bit ARGB format automatically so you don't have to be able to deal with dozens of different pixel formats. This conversion, however, means overhead which makes hw_BitMapToARGB() slower than hw_LockBitMap().

hw_BitMapToARGB() accepts a tag list that allows you to fine-tune its behaviour. The following tags are currently recognized:

HWBM2ARGBTAG_X:
If you set the iData member of this tag to an x-offset within your bitmap boundaries, hw_BitMapToARGB() will start fetching pixels at this offset. This tag allows you to convert only a part of the bitmap to a pixel buffer. Defaults to 0.

HWBM2ARGBTAG_Y:
If you set the iData member of this tag to an y-offset within your bitmap boundaries, hw_BitMapToARGB() will start fetching pixels at this offset. This tag allows you to convert only a part of the bitmap to a pixel buffer. Defaults to 0.

HWBM2ARGBTAG_WIDTH:
If you only want to convert a part of the bitmap to an ARGB pixel buffer, set the iData member of this tag to the number of columns to convert. Defaults to bitmap width.

HWBM2ARGBTAG_HEIGHT:
If you only want to convert a part of the bitmap to an ARGB pixel buffer, set the iData member of this tag to the number of rows to convert. Defaults to bitmap height.

HWBM2ARGBTAG_CLUT:
If you set the iData member of this tag to True, the bitmap is a CLUT one. In that case, you must also set the tag HWBM2ARGBTAG_PALETTE below. (V9.0)

HWBM2ARGBTAG_PALETTE:
If you set HWBM2ARGBTAG_CLUT to True (see above), you must set the pData member of this tag to a ULONG array containing the palette pens as RGB colors. Note that the ULONG array must always contain 256 entries, even if the bitmap depth is less than 8 bits. (V9.0)

HWBM2ARGBTAG_TRANSPEN:
If you set HWBM2ARGBTAG_CLUT to True (see above), you may set the iData member of this tag to a pen that should be made transparent. By default, no pen will be made transparent. (V9.0)

Please note that alpha byte will always be set, even if you didn't pass a mask or alpha channel bitmap. In that case the alpha byte for every pixel will be set to 255, i.e. fully opaque.

The memory buffer that is returned by this function must be freed by using the hw_TrackedFree() function. See hw_TrackedFree for details.

Note that hw_BitMapToARGB() can only be used with software bitmaps. It is not possible to get the raw pixels of hardware (video) bitmaps.

Designer compatibility
Unsupported

Inputs
bmap
source bitmap
mask
mask bitmap or NULL
alpha
alpha channel bitmap or NULL
tags
pointer to a taglist specifying additional options (see above)
Results
rgb
raw 32-bit ARGB pixel buffer or NULL on error

Show TOC