APTR handle = hw_LockBrush(lua_ID *id, struct hwTagList *tags,
                  struct hwos_LockBrushStruct *brlock);

You also have to pass a pointer to a struct hwos_LockBrushStruct which will be filled with all the information you need by hw_LockBrush(). struct hwos_LockBrushStruct looks like this:

struct hwos_LockBrushStruct { APTR RGBData; // [out] int RGBModulo; // [out] UBYTE *AlphaData; // [out] int AlphaModulo; // [out] UBYTE *MaskData; // [out] int MaskModulo; // [out] int PixelFormat; // [out] int BytesPerPixel; // [out] int Width; // [out] int Height; // [out] UBYTE *CLUTData; // [out] -- V9.0 int CLUTModulo; // [out] -- V9.0 ULONG *Palette; // [out] -- V9.0 ULONG TransPen; // [out] -- V9.0 int Depth; // [out] -- V9.0 };

hw_LockBrush() will write to the structure members as follows:

RGBData:

This member will be set to a pointer to the raw RGB 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, RGBData 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. This member will only be set if the brush is an RGB brush. For palette brushes, the pixel data will be returned in CLUTData (see below).

RGBModulo:

This contains the number of pixels in a single row. This can be more than returned in Width because Hollywood might choose to allocate some padding bytes for optimized blitting. Note that the value returned in RGBModulo is specified in pixels, not in bytes. This member will only be set if the brush is an RGB brush. For palette brushes, the modulo will be returned in CLUTModulo (see below).

AlphaData:

If the brush contains an alpha channel, this member is set to the raw alpha channel data as an array of unsigned bytes. Otherwise this member will be set to NULL.

AlphaModulo:

If the brush contains an alpha channel, this member will be set to the number of pixels stored in one row of the AlphaData array. This can be more than what has been returned in the Width member because Hollywood might use padding bytes for optimized blitting.

MaskData:

If the brush contains a mask, this member will be set to the raw mask bits. Otherwise it is set to NULL. 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.

MaskModulo:

If the brush contains a mask, this member will be set to the number of bytes that is used for one row of mask data. Note that this value is specified in bytes and often contains some padding.

PixelFormat:

This member is set to the pixel format used by the pixel array written to the RGBData 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 RGBData array.

Width:

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

Height:

This will be set to the brush's actual height.

CLUTData:

If the brush is a palette brush, this will be set to the raw pixel data. Note that pixels will always be stored as 8 bits per pixel, even if the palette brush's depth is less than 8. Also note that palette brushes are only supported if you set the HWLBRSHTAG_PALETTE tag to True (see below). This is necessary to maintain compatibility with older versions of Hollywood. The CLUTData member (and the other members required for palette support, see below) are new in Hollywood 9.0 so of course Hollywood may only write to these fields if it knows that the caller has allocated member for them. (V9.0)

CLUTModulo:

If the brush is a palette brush, this will be set to the number of pixels per row. This is often identical to Width. (V9.0)

Palette:

If the brush is a palette brush, this will be set to a pointer to an array of ULONGs which contains the palette colors for the brush. The palette colors are stored as raw RGB values. (V9.0)

TransPen:

If the brush is a palette brush and has a transparent pen, this pen will be returned in this member. (V9.0)

Depth:

This will be set to the brush's depth. Note that this member will only ever be set if you set the HWLBRSHTAG_DEPTH tag to True (see below). This is necessary to maintain compatibility with older versions of Hollywood. The Depth member is new in Hollywood 9.0 so of course Hollywood may only write to this field if it knows that the caller has allocated member for it. (V9.0)

The following tags can be passed in tag list parameter:

HWLBRSHTAG_READONLY:

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

HWLBRSHTAG_PALETTE:

If you want hw_LockBrush() to support palette brushes as well, you need to set the iData member of this tag item to True. Otherwise only RGB brushes will be supported and the fields in struct hwos_LockBrushStruct that are new in Hollywood 9.0 will never be touched. Explicitly requesting palette support via the HWLBRSHTAG_PALETTE tag is necessary to maintain compatibility with previous versions of Hollywood. (V9.0)

HWLBRSHTAG_DEPTH:

If you want hw_LockBrush() to return the brush depth in the Depth field of struct hwos_LockBrushStruct, you need to set the iData member of this tag item to True. Otherwise the Depth member in struct hwos_LockBrushStruct will never be touched. This is necessary to maintain compatibility with older versions of Hollywood which didn't have the Depth field. (V9.0)

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

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

If you only need to read a brush's raw pixel data, it might be more convenient to use the hw_GetARGBBrush() function instead. This will give you the pixels as readily formatted 32-bit ARGB values. The downside is that hw_GetARGBBrush() is slower because it needs to copy and convert the pixels first. See hw_GetARGBBrush for details.

id

object identifier of brush to be locked

tags

pointer to a taglist specifying additional options (see above) or NULL

brlock

pointer to a struct hwos_LockBrushStruct that is to be filled by this function

handle

handle to the locked brush or NULL on error