Name
LoadBrush -- load a brush
Synopsis
[id] = LoadBrush(id, filename$[, table])
Function
This function loads the brush specified by filename$ into memory and assigns the identifier id to it. If you pass Nil in id, LoadBrush() will automatically choose a vacant identifier and return it.

Image formats that are supported on all platforms are PNG, JPEG, BMP, IFF ILBM, GIF, and image formats you have a plugin for. Depending on the platform Hollywood is running on, more image formats might be supported. For example, on Amiga compatible systems Hollywood will be able to open all image formats you have datatypes for as well.

Starting with Hollywood 5.0, this function can also load vector formats like SVG if you have an appropriate plugin installed. Keep in mind, though, that when you load vector images using LoadBrush(), the brush will be a special vector brush which does not support all features of the normal brushes. You can, however, convert vector brushes to raster brushes by using the RasterizeBrush() function. See Vector brushes for more information on vector brushes.

The third argument is optional. It is a table that can be used to set further options for the loading operation. The following fields of the table can be used:

Transparency:
This field can be used to specify a color in RGB notation that shall be made transparent in the brush.

LoadAlpha:
Set this field to True if the alpha channel of the image shall be loaded, too. Please note that not all pictures have an alpha channel and that not all picture formats are capable of storing alpha channel information. It is suggested that you use the PNG format if you need alpha channel data. This field defaults to False.

X, Y, Width, Height:
These fields can be used to load only a part of the image into the brush. This is useful if you have one big image with many different small images in it and now you want to load the small images into single brushes. Using these fields you can specify a rectangle inside the image from which Hollywood will take the graphics data for the brush.

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. (V5.0)

ScaleWidth, ScaleHeight:
These fields can be used to load a scaled version of the image. If the image driver supports scaled loading, this will give you some significant speed-up for example in case you just want to load a thumbnail-sized version of a large image. If the image driver does not support scaled loading, the full image will be loaded first before it is scaled. This is not much faster than manually scaling the image after loading. You can pass an absolute pixel value or a string containing a percent specification here. (V5.3)

SmoothScale:
If ScaleWidth or ScaleHeight is set, you can use this item to specify whether or not Hollywood shall use anti-aliased scaling. Defaults to False which means no anti-aliasing. Note that anti-aliased scaling is much slower than normal scaling. (V5.3)

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)

Loader:
This tag allows you to specify one or more format loaders that should be asked to load this brush. This must be set to a string containing the name(s) of one or more loader(s). Defaults to default. See Loaders and adapters for details. (V6.0)

Adapter:
This tag allows you to specify one or more file adapters that should be asked to open the specified file. This must be set to a string containing the name(s) of one or more adapter(s). Defaults to default. See Loaders and adapters for details. (V6.0)

LoadTransparency:
If this tag is set to True, the monochrome transparency of the image will be loaded. Please note that this tag is specifically designed for monochrome transparency channels, i.e. a transparent pen in a palette-based image. If you want to load the alphachannel of an image, set the LoadAlpha tag to True. This tag defaults to False. (V6.0)

Please note that the Transparency, LoadTransparency and LoadAlpha fields are mutually exclusive. A brush can only have one transparency setting!

This command is also available from the preprocessor: Use @BRUSH to preload brushes!

Inputs
id
identifier for the brush or Nil for auto id selection
filename$
file to load
table
optional: transparency and crop options (see above) (V2.0)
Results
id
optional: identifier of the brush; will only be returned when you pass Nil as argument 1 (see above)
Example
LoadBrush(2, "MyBrush.png", {Transparency = #RED})
This loads "MyBrush.png" as brush 2 with the color red being transparent.

Show TOC