[id] = ConvertToBrush(sourcetype, sourceid, dest[, t])

Having graphics as brushes is so convenient because brushes are the most flexible graphics type in Hollywood. Most of the image manipulating functions work only with brushes. That is why you will often want to convert your graphics data to the brush format.

The sourcetype argument specifies the type of the source object that shall be converted into a brush. It can be one of the following types:

#ANIM

Create a new brush from a single frame from an anim object. By default, the first anim frame will be converted to a brush. You can change this by passing the Frame tag in the optional table argument (see below).

#BGPIC

Create a new brush from a background picture.

#BRUSH

Create a new brush from an other brush. This does the same as the CopyBrush() command.

#ICON

Create a new brush from an image inside an icon. Since icons can contain multiple images, you can use the Frame tag of the optional table argument to specify the index of the image that should be converted to a brush. By default, the first image in the icon will be converted to a brush. You can also use the Selected tag of the optional table argument to specify whether or not the selected icon image should be converted to a brush. By default, the normal image will be converted to a brush. (V8.0)

This type requires you to pass the optional argument par which must be set to the index of icon image you wish to have converted into a brush. Icon image indices are counted from 1 until the number of images in the icon. Additionally, you can specify the optional argument par2: If you set this to True, the selected icon image will be converted to a brush, otherwise the normal image will be converted to a brush, which is also the default mode. (V8.0)

#LAYER

Create a new brush from a layer (requires layers to be enabled!). If the layer is an anim layer, you can use the Frame tag in the optional table argument to specify which frame of the anim layer should be converted to a brush (see below). By default, the first frame will be converted.

#SPRITE

Create a new brush from a single frame from a sprite object. By default, the first sprite frame will be converted to a brush. You can change this by passing the Frame tag in the optional table argument (see below).

#TEXTOBJECT

Create a new brush from a text object.

#VECTORPATH

Create a vector brush from one or more path object(s). If you use this type, the sourceid argument is unused. Instead, you need to pass a table argument in the Path tag in the optional table argument. This table must contain information about the individual paths to be embedded inside the new vector brush. The table uses the same layout as the table you have to pass to the PathToBrush() function. See PathToBrush for details. (V7.0)

The optional table argument allows you to pass the following additional options:

Frame:

If the source type specifies a graphics object that has multiple frames, you can use this tag to specify the frame that should be converted to a brush. Frames are counted from 1 until the number of frames. This tag defaults to 1.

Selected:

If the source type is #ICON, you can use this tag to specify whether the selected or normal image should be converted to a brush. Icon images have two states: normal and selected. If you set Selected to True, the selected image will be converted to a brush. Otherwise ConvertToBrush() will convert the normal image to a brush. Defaults to False. (V8.0)

Path:

If the source type is #VECTORPATH, you must set this tag to a table which contains information about the individual paths to be embedded inside the new vector brush. The table uses the same layout as the table you have to pass to the PathToBrush() function. See PathToBrush for details. (V7.0)

Vector:

By default, ConvertToBrush() will convert vector images to raster brushes. If you want to convert them to vector brushes, set this tag to True. This makes it possible to convert vector text objects or vector anim frames to vector brushes that can be scaled and rotated without any quality losses. Defaults to False. (V10.0)

sourcetype

type of the source object (see list above)

sourceid

identifier of the source object

dest

id for the brush to be created or Nil for auto id selection

t

optional: table argument containing further options (see above)

id

optional: handle to the new brush; will only be returned if you specified Nil in dest

ConvertToBrush(#SPRITE, 1, 10, {Frame = 5})