Name
hw_LockBitMap -- gain access to the raw pixels of a bitmap (V6.0)
Synopsis
APTR handle = hw_LockBitMap(APTR bmap, ULONG flags, struct
                hwos_LockBitMapStruct *bmlock, struct hwTagList *tags);
Function
This function locks the specified bitmap and allows you to access its raw pixel data. The bitmap can be either an RGB bitmap, a CLUT bitmap, a monochrome mask bitmap or an alpha channel bitmap. You have to pass a pointer to a struct hwos_LockBitMapStruct which will be filled with all the information you need by hw_LockBitMap(). struct hwos_LockBitMapStruct looks like this:

 
struct hwos_LockBitMapStruct
{
    APTR Data;           // [out]
    int Modulo;          // [out]
    int PixelFormat;     // [out]
    int BytesPerPixel;   // [out]
    int Width;           // [out]
    int Height;          // [out]
};

hw_LockBitMap() will write the following values to the structure members:

Data:
This member will be set to a pointer to the raw pixel data. The actual format used by the individual pixels is determined by the PixelFormat member. Please note that even if a 32-bit pixel format is used, Data will never contain any alpha channel information because Hollywood always stores the alpha channel separately in order to be compatible with 15-bit and 16-bit screenmodes. See Bitmap information for details.

Modulo:
This contains the bitmap's row modulo, i.e. the number of pixels or bytes in a single row of image data. This can be more than returned in Width because Hollywood might choose to allocate some padding bytes for optimized blitting. Please note that the value in Modulo is returned in pixels for RGB bitmaps and in bytes for mask, CLUT and alpha channel bitmaps.

PixelFormat:
This member is set to the pixel format used by the pixel array written to the Data member. See Pixel format information for details.

BytesPerPixel:
This will be set to the number of bytes that are needed to represent one pixel in the Data array. If the bitmap is a monochrome mask, this member will be set to 1 although in reality only 1 bit is needed for a single pixel in case of a monochrome mask. For CLUT bitmaps this will always be 1, even if the bit depth is less than 8 bits.

Width:
This will be set to the bitmap's actual width, without any row padding.

Height:
This will be set to the bitmap's actual height.

The following tags can be passed in tag list parameter:

HWLBMAPTAG_READONLY:
If you set the iData member of this tag item to True, the bitmap will be locked for read-only access. This might be faster with some bitmap backends. By default, the bitmap is locked for read and write access.

Do not hold bitmap locks longer than necessary. In particular, do not return control to the script while holding a bitmap lock because the script might try to modify the bitmap then and this will lead to trouble in case the bitmap is still locked. You should call hw_UnLockBitMap() as soon as possible.

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

If you only need to read a bitmap's raw pixel data, it might be more convenient to use the hw_BitMapToARGB() function instead. This will give you the pixels as readily formatted 32-bit ARGB values as it also takes potential mask and alpha channel bitmaps into account. The downside is that hw_BitMapToARGB() is slower because it needs to copy and convert the pixels first. See hw_BitMapToARGB for details.

Designer compatibility
Unsupported

Inputs
bmap
bitmap to lock
flags
reserved for future use; pass 0 for now
bmlock
pointer to a struct hwos_LockBitMapStruct that is to be filled by this function
tags
pointer to a taglist specifying additional options (see above) or NULL
Results
handle
handle to the locked bitmap or NULL on error
Show TOC