int error = hw_AddBrush(lua_State *L, lua_ID *id, int width, int height,
                struct hwAddBrush *ctrl);

struct hwAddBrush { ULONG *Data; int LineWidth; ULONG Transparency; ULONG Flags; APTR Image; ULONG *(*GetImage)(APTR handle, struct LoadImageCtrl *ctrl); void (*FreeImage)(APTR handle); int (*TransformImage)(APTR handle, struct hwMatrix2D *m, int width, int height); int Depth; // V9.0 ULONG *Palette; // V9.0 };

You need to provide the following information in this structure:

Data:

This is only used if you want to create a raster brush, i.e. the HWABFLAGS_VECTORBRUSH flag is not set. The format of Data depends on whether you want hw_AddBrush() to create a palette brush or an RGB brush. For RGB brushes, set this structure member to a pointer to an array of 32-bit ARGB pixels that contain the image data for the new brush. hw_AddBrush() will only take the alpha byte into account if the HWABFLAGS_USEALPHA flag has been set. Otherwise the alpha byte is ignored. For palette brushes, you must provide an 8-bit array of pixels. Note that 8-bit pixels must be used even if the palette depth is less than 8 bits. The pixel array specified here must contain exactly as many pixels per row as passed in the LineWidth member. If you set Data to NULL and HWABFLAGS_VECTORBRUSH isn't set, hw_AddBrush() will create an uninitialized raster brush for you, i.e. it will be filled with random pixel data.

LineWidth:

This must only be set if you want to create a raster brush and Data is not NULL. In that case, you have to set this structure member to the number of pixels per row in the Data pixel array. This can be different from the value passed in the width parameter of hw_AddBrush() in case the pixel array you specified in Data contains some padding bytes. Please note that LineWidth must be specified in pixels, not in bytes.

Transparency:

If the HWABFLAGS_USETRANSPARENCY flag has been set, this member contains a 24-bit RGB color that should be made transparent. Hollywood will scan through the pixel array passed in Data and create a monochrome mask for the new brush in which all pixels which match the RGB color specified here are transparent. This member is only supported for raster brushes. Note that for palette brushes, i.e. if the HWABFLAGS_USEPALETTE flag is set, Transparency needs to specify a pen that should be made transparent instead. For no transparent pen, set this to HWPEN_NONE.

Depth:

If HWABFLAGS_USEPALETTE is set, this member must be set to the palette depth. This must be between 1 and 8. When creating RGB brushes, this member needn't be set. (V9.0)

Palette:

If HWABFLAGS_USEPALETTE is set, this member must be set to a ULONG array containing the palette colors, specified as raw RGB values. Note that the array you pass here must contain 256 entries, even if the palette depth is less than 8. (V9.0)

Flags:

This member controls several attributes for the new brush. It can be set to a combination of the following flags:

HWABFLAGS_USEALPHA:

The brush uses alpha channel transparency. If this flag is set, the pixel array specified in Data has to contain transparency information in the alpha byte. If a vector brush is created, your GetImage() implementation must return transparency information in the alpha byte as well. If this flag is not set, hw_AddBrush() will ignore whatever is in the alpha byte. This flag and HWABFLAGS_USETRANSPARENCY are mutually exclusive.

HWABFLAGS_USETRANSPARENCY:

This is only supported if you create a raster brush and a pixel array has been passed in Data. In that case, setting this flag indicates that you want hw_AddBrush() to create a mask in which all pixels that match the color specified in Transparency are made transparent. That is why you also need to set the Transparency member if you set this flag. This flag and HWABFLAGS_USEALPHA are mutually exclusive.

HWABFLAGS_VECTORBRUSH:

If this flag is set, hw_AddBrush() will create a vector brush for you. Vector brushes can be transformed without any quality loss and whenever the script wants to have a vector brush scaled, rotated, or transformed, Hollywood will call into your plugin to apply this transformation to your vector brush. That is why you need to provide several callbacks when creating a vector brush (see below).

HWABFLAGS_USEPALETTE:

Set this flag if you want to create a palette brush. In that case, you also have to set the Palette and Depth members (see above). (V9.0)

Image:

This must only be set if you want to create a vector brush. In that case, it must be set to a handle that you want Hollywood to pass to your vector brush callbacks whenever it needs something done.

GetImage:

This must only be set if you want to create a vector brush. In that case, it must be set to a callback function that returns the raw pixel data of the vector brush. The function that you specify here has to work exactly like the GetImage() function of image plugins. See GetImage for details.

FreeImage:

This must only be set if you want to create a vector brush. In that case, it must be set to a callback function that frees any data that your plugin has allocated for your vector brush. The function that you specify here has to work exactly like the FreeImage() function of image plugins. See FreeImage for details.

TransformImage:

This must only be set if you want to create a vector brush. In that case, it must be set to a callback function that applies transformation to a vector brush. The function that you specify here has to work exactly like the TransformImage() function of image plugins. See TransformImage for details.

You can free brushes by calling the hw_FreeBrush() function.

L

pointer to the lua_State

id

object identifier for the new brush

width

desired pixel width for the new brush

height

desired pixel height for the new brush

ctrl

pointer to a struct hwAddBrush containing additional information

error

error code or 0 on success