[id] = LoadBrush(id, filename$[, table])

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. On Windows, LoadBrush() can also load image formats supported by the Windows Imaging Component.

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 the loader set using SetDefaultLoader(). 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 the adapter set using SetDefaultAdapter(). 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)

LoadPalette:

If this tag is set to True, Hollywood will load the brush as a palette brush. This means that you can get and modify the brush's palette which is useful for certain effects like color cycling. You can also make pens transparent using the TransparentPen tag (see below) or the LoadTransparency tag (see above). Palette brushes also have the advantage of requiring less memory because 1 pixel just needs 1 byte of memory instead of 4 bytes for 32-bit images. This tag defaults to False. (V9.0)

TransparentPen:

If the LoadPalette tag has been set to True (see above), the TransparentPen tag can be used to define a pen that should be made transparent. Pens are counted from 0. Alternatively, you can also set the LoadTransparency tag to True to force Hollywood to use the transparent pen that is stored in the image file (if the image format supports the storage of transparent pens). This tag defaults to #NOPEN. (V9.0)

UserTags:

This tag can be used to specify additional data that should be passed to loaders and adapters. If you use this tag, you must set it to a table of key-value pairs that contain the additional data that should be passed to plugins. See User tags for details. (V10.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!

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)

id

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

LoadBrush(2, "MyBrush.png", {Transparency = #RED})