[id] = LoadBGPic(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, LoadBGPic() 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. 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 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 BGPic as a palette BGPic. This means that you can get and modify the BGPic'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 BGPics 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. Note that if you set the LoadPalette tag to True, your display will become a palette display as soon as the BGPic is shown. Palette displays behave differently than normal true colour displays and there are some things to be considered when using them. See Palette displays for details. This tag defaults to False. (V9.0)

FillPen:

If the LoadPalette tag has been set to True (see above) and there is a transparent pen in the image, you can use the FillPen tag to specify the filling color for all transparent areas in the image. This is the palette equivalent to the FillColor tag which is only used for non-palette images. (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)

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!

id

identifier for the background picture or Nil for auto id select

filename$

file to load

table

optional: further configuration options for loading operation

id

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

LoadBGPic(2, "MyBG.iff", {Transparency = $00FF00})