[id] = CreateBrush(id, width, height[[, color], table])

Starting with Hollywood 4.5, there is an optional table argument which you can use to create a mask or an alpha channel for this brush. The following tags are recognized by the optional table:

Mask:

Set this tag to True if CreateBrush() should attach a mask to the new brush. If this is True, AlphaChannel must be False. Defaults to False.

AlphaChannel:

Set this tag to True if CreateBrush() should attach an alpha channel to the new brush. If this is set to True, Mask must be set to False. Defaults to False.

Clear:

This tag is only handled if either AlphaChannel or Mask was set to True. If that is the case, Clear specifies whether or not the mask or alpha channel should be cleared (i.e. fully transparent) or not (i.e. opaque). This defaults to False which means that by default, the new mask or alpha channel will be opaque.

Hardware:

If you set this tag to True, Hollywood will create this brush entirely in video memory for hardware-accelerated drawing in connection with a hardware double buffer. Hardware brushes are subject to several restrictions. See hardware brushes for details. (V6.0)

Display:

If you specify the identifier of a display here, Hollywood will create a display-dependent hardware brush for you. Display-dependent hardware brushes can only be drawn to the display they belong to. This tag is only handled if the Hardware tag has been set to True. Also note that Hollywood's inbuilt display adapter does not support display-dependent hardware brushes, but plugins can install custom display adapters which support display-dependent hardware brushes. This tag defaults to the identifier of the currently active display. See hardware brushes for details. (V6.0)

SmoothScale:

If you set this tag to True and the Hardware tag has also been set to True, Hollywood (or display adapters) will use bilinear interpolation when transforming this brush. Normally, whether interpolation shall be used or not is set when calling a brush transformation command like ScaleBrush() or RotateBrush() but some display adapters need to know this information already at the time a hardware brush is created, and this is why this tag is here, though it's probably of not much use because it's only needed in rather special situations with display adapters like RebelSDL or hardware brushes on Android, because normally you can just specify whether interpolation shall be used or not in the transformation command directly. Note that SmoothScale is only supported when Hardware is set to True. (V8.0)

Palette:

If this tag is set to the identifier of a palette, Hollywood will create a palette brush for you. Palettes can be created using functions like CreatePalette() or LoadPalette(). Alternatively, you can also set this tag to one of Hollywood's inbuilt palettes, e.g. #PALETTE_AGA. See SetStandardPalette for a list of inbuilt palettes. (V9.0)

FillPen:

If the Palette tag is set (see above), you can use this tag to set the pen that should be used for filling the brush's background. Note that the color parameter that is passed to CreateBrush() is ignored if Palette is True. That's why this tag is here to allow you to specify a pen that will be used when initializing the brush's pixels. Defaults to 0. (V9.0)

TransparentPen:

If Palette is set to True, this tag can be used to specify a pen that should be made transparent in the new brush. Defaults to #NOPEN which means that there should be no transparent pen. (V9.0)

Depth:

This tag allows you to set the desired brush depth. If this is less than or equal to 8, CreateBrush() will create a palette brush. You can also specify the Palette tag together with the Depth tag. If the specified palette has more colors than the specified depth, those colors will be discarded. If it has less colors, the unused pens will be set to black. By default, CreateBrush() will create 24-bit or 32-bit brushes, depending on whether the AlphaChannel tag is set to True or False. (V10.0)

Callback:

If you set this tag to a callback function, CreateBrush() will create a custom-drawn brush for you. In comparison to normal brushes, custom-drawn brushes are backed by a callback function that Hollywood will call whenever the dimensions of the brush change or a transformation is applied. This allows you to create brushes which dynamically adapt themselves to new resolutions and transformations. This is very similar to what vector brushes do except that custom-drawn brushes allow you to assume full control over the process because your callback does all the drawing. Your callback will also be called immediately by CreateBrush() to do the initial drawing of the brush.

Custom-drawn brushes can be very useful to implement your own vector brush type. Since custom-drawn brushes get the chance to redraw themselves whenever their resolution or transformation changes, you can use them to create brushes which can be scaled or transformed without any losses in quality because your callback redraws the graphics whenever the brush dimensions change instead of just scaling its pixels using conventional lossy scaling. This is especially useful when using the layerscale engine with custom graphics. If you use custom-drawn brushes for a layer, you can be sure that that layer will scale losslessly to all resolutions.

The callback function you specify in Callback will receive a message as parameter 1 with the following fields initialized:

Action:

Initialized to Draw.

ID:

Identifier of the brush to draw to. Note that this won't be the same identifier as the brush you created using CreateBrush(). Your callback needs to call SelectBrush() on the brush specified in ID and draw the desired graphics to the brush, taking the current transformation into account (see below). You can also call SelectMask() and SelectAlphaChannel() on the brush in case you need to adjust transparency setting.

Width:

Current width of the brush.

Height:

Current height of the brush.

SX:

Specifies the amount of scaling on the x axis. If it is negative, the image is flipped on the y axis. This will never be 0.

RX:

Specifies the amount of rotation on the x axis. This can be 0.

RY:

Specifies the amount of rotation on the y axis. This can be 0.

SY:

Specifies the amount of scaling on the y axis. If it is negative, the image is flipped on the x axis. This will never be 0.

UserData:

This will be set to the user data you passed in the UserData tag of the optional table argument supported by CreateBrush() (see below). If you haven't passed any user data in your call to CreateBrush(), this tag won't be set.

(V10.0)

UserData:

If you have set the Callback tag (see above), you can use this tag to store some user data that will be passed to your callback whenever Hollywood calls it. The user data can be of any type. (V10.0)

id

id for the new brush or Nil for auto id selection

width

width for the brush

height

height for the brush

color

optional: RGB color for background (defaults to #BLACK)

table

optional: table for specifying further options (see above) (V4.5)

id

optional: identifier of the brush; will only be returned when you pass Nil as argument 1 (see above)

CreateBrush(2, 320, 256, #BLUE)

CreateBrush(2, 320, 256, #BLUE, {AlphaChannel = True, Clear = True})

CreateBrush(1, 320, 240, 0, {AlphaChannel = True, Clear = True, Callback =
    Function(msg)
        SelectBrush(msg.id, #SELMODE_COMBO)
        SetFormStyle(#ANTIALIAS)
        SetFillStyle(#FILLCOLOR)
        Ellipse(0, 0, msg.width / 2, msg.height / 2, #RED)
        EndSelect
    EndFunction
})
ScaleBrush(1, 640, 480)
DisplayBrush(1, 0, 0)