Name
LoadBGPic -- load a background picture
Synopsis
[id] = LoadBGPic(id, filename$[, table])
Function
This function loads the picture specified by filename$ into memory and assigns the identifier id to it. If you pass Nil in id, LoadBGPic() 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. Using a vector image as a BGPic has the advantage that when the size of the display changes (e.g. because the user is resizing the window), the BGPic can be adapted to the new size without any losses in quality because vector BGPics can be infinitely scaled without any sacrifices in quality. See Vector BGPics for more information on vector BGPics.

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 appear transparent in the BGPic.

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 tag defaults to False. (V4.5)

FillStyle:
This tag allows you to define a background fill style for this BGPic. This fill style is only used when the BGPic has transparent areas, i.e. when you use either the Transparency or the LoadAlpha tags, or when loading an image in a format that always contains an alpha channel. FillStyle is useful especially in the latter case because some formats always return an alpha channel but most of the time you will not want to use this alpha channel when loading such an image into a background picture. See SetFillStyle for information on all available fill styles. (V5.0)

FillColor:
If the FillStyle tag was set to #FILLCOLOR, you can use this tag to define the RGB color that shall be used for backfilling. (V5.0)

TextureBrush:
If the FillStyle tag was set to #FILLTEXTURE, you can use this tag to specify the identifier of the brush that shall be used for texturing. (V5.0)

TextureX, TextureY:
These tags control the start offset inside the texture brush and are only supported if FillStyle was set to #FILLTEXTURE. See SetFillStyle for details. (V5.0)

GradientStyle:
If the FillStyle tag was set to #FILLGRADIENT, you can use this tag to specify the gradient type to use. This can be #LINEAR, #RADIAL, or #CONICAL. (V5.0)

GradientAngle:
Specifies the orientation of the gradient if filling style is set to #FILLGRADIENT. The angle is expressed in degrees. Only possible for #LINEAR and #CONICAL gradients. (V5.0)

GradientStartColor, GradientEndColor:
Use these two to configure the colors of the gradient if filling style is set to #FILLGRADIENT. (V5.0)

GradientCenterX, GradientCenterX:
Sets the center point for gradients of type #RADIAL or #CONICAL. Must be a floating point value between 0.0 and 1.0. See CreateGradientBGPic for details. (V5.0)

GradientBalance:
This tag controls the balance point for gradients of type #CONICAL. Must be a floating point value between 0.0 and 1.0. See CreateGradientBGPic for details. (V5.0)

GradientBorder:
This tag controls the border size for gradients of type #RADIAL. Must be a floating point value between 0.0 and and 1.0. See CreateGradientBGPic for details. (V5.0)

GradientColors:
This tag can be used to create a gradient between more than two colors. This has to be set to a table that contains sequences of alternating color and stop values. See CreateGradientBGPic for details. If this tag is used, the GradientStartColor and GradientEndColor tags are ignored. (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)

Loader:
This tag allows you to specify one or more format loaders that should be asked to load this BGPic. 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)

If you use Transparency, LoadTransparency or LoadAlpha your display will automatically adopt the transparency settings of the BGPic when it is shown. In other words, if you want to have a display with transparency simply load a transparent BGPic and display it.

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

This command is also available from the preprocessor: Use @BGPIC to preload background pictures!

Inputs
id
identifier for the background picture or Nil for auto id select
filename$
file to load
table
optional: further configuration options for loading operation
Results
id
optional: identifier of the background picture; will only be returned when you pass Nil as argument 1 (see above)
Example
LoadBGPic(2, "MyBG.iff", {Transparency = $00FF00})
This loads "MyBG.iff" as background picture 2 with the color green as transparency mask.

Show TOC