Name
ConvertToBrush -- convert object to brush (V2.5)
Synopsis
[id] = ConvertToBrush(sourcetype, sourceid, dest[, par, par2])
Function
This function allows you to create a new brush from an existing graphics object. This is useful, for example, to copy the image data from single anim or sprite frames to a brush. You could then modify them and convert them back into an animation or sprite. You can also access the graphics of layers with this function.

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. This type requires the optional argument par which specifies the frame you want to have converted to a brush. If you omit the optional argument, the first frame will be used. Frames are counted from 1 until the number of frames.

#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. 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 optional argument par to specify the layer frame to retrieve (defaults to 1 which means first frame).

#SPRITE
Create a new brush from a single frame from a sprite object. This type requires the optional argument par which specifies the frame you want to have converted to a brush. If you omit the optional argument, the first frame will be used. Frames are counted from 1 until the number of frames.

#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 par 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)

Inputs
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
par
optional: currently only required for types #ANIM, #SPRITE, #ICON (defaults to 1 which means convert the first frame) and #VECTORPATH
par2
optional: currently only supported for type #ICON (see above)
Results
id
optional: handle to the new brush; will only be returned if you specified Nil in dest
Example
ConvertToBrush(#SPRITE, 1, 10, 5)
The code above creates a new brush with the id 10 from frame 5 of sprite number 1.

Show TOC