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

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 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 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)

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!

Inputs
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
Results
id
optional: identifier of the sprite; will only be returned when you pass Nil as argument 1 (see above)
Example
LoadSprite(1, "MySprite.png", {Transparency = #RED})
This loads "MySprite.png" as sprite 1 with the color red being transparent.


LoadSprite(1, "PlayerSprites.png", {Width = 32, Height = 32,
     Frames = 16, FPR = 8, Transparency = #BLACK})
The code above creates sprite 1 from the file "PlayerSprites.png". Sprite 1 will be of the dimensions 32x32 and will contain 16 different frames. The single frames are aligned with 8 frames per row in the image "PlayerSprites.png". Thus, LoadSprite() needs to scan two rows to read the full 16 frames.

Show TOC