[id] = LoadSprite(id, filename$[, args])

Supported image formats are PNG, JPEG, BMP, IFF ILBM, and some more depending on the platform Hollywood is running on. Starting with Hollywood 4.5, LoadSprite() can also open animation formats (IFF ANIM, GIF ANIM, uncompressed AVIs or AVIs using Motion JPEG compression) and convert these animations into a sprite directly.

The optional argument args accepts a table which can contain further options for the loading operation. The following fields can be set in the args table:

Transparency:

Here you can specify a color that shall appear transparent in the sprite. The color you specify here will be masked out then.

LoadAlpha:

Set this field to True if the image contains an alpha channel that shall be loaded.

X, Y, Width, Height, Frames, FPR:

This lot of fields can be used to fine-tune the loading operation. You can use these fields to make LoadSprite() create a sprite with multiple frames from a single picture. Width and Height define the dimensions for the sprite and Frames specifies how many frames LoadSprite() shall read from the source image. If the frames are aligned in multiple rows in the source image, you will also have to pass the argument FPR (stands for frames per row) to tell LoadSprite() how many frames there are in each row. Finally, you can tell LoadSprite() where in the image it should start scanning by specifying the fields X and Y (they both default to 0). LoadSprite() will then start off at position X and Y and read Frames number of images with the dimensions of Width by Height from the picture specified by filename$. After it has read FPR number of images, it will advance to the next row. All of these fields can only be used if you specify an image file in filename$. If you specify an anim file, they are ignored.

Loader:

This tag allows you to specify one or more format loaders that should be asked to load this sprite. 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 sprite will be loaded. Please note that this tag is specifically designed for monochrome transparency channels, i.e. a transparent pen in a palette-based sprite. If you want to load the alphachannel of a sprite, 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 sprite as a palette sprite. This means that you can get and modify the sprite'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 sprites 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 file (if the file 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 sprite cannot have a mask and an alpha channel!

This command is also available from the preprocessor: Use @SPRITE to preload sprites!

id

identifier for the sprite or Nil for auto id selection

filename$

file to load

args

optional: table that specifies further options for the loading operation

id

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

LoadSprite(1, "MySprite.png", {Transparency = #RED})

LoadSprite(1, "PlayerSprites.png", {Width = 32, Height = 32,
     Frames = 16, FPR = 8, Transparency = #BLACK})