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

Anim formats that are supported on all platforms are IFF ANIM, GIF ANIM, AVI (uncompressed or using Motion JPEG compression), and formats you have a plugin for. Depending on the platform Hollywood is running on, more anim formats might be supported. For example, on Amiga compatible systems Hollywood will be able to open all anim formats you have datatypes for as well.

Starting with Hollywood 4.5, LoadAnim() can also automatically create animations from an image file. If you want to load an image file with LoadAnim(), you need to specify the optional Frames argument. See below for more information.

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 animation.

FromDisk:
If you set this field to True, Hollywood will not load the whole animation into memory but it will load the single frames directly from disk when needed. This is slower but requires much less memory. For the functions of the anim library it does not matter whether the animation is completely in memory or loaded dynamically from disk. You can use all anim functions like ScaleAnim() also with anims that are loaded from disk. Anim layers are also correctly handled with disk anims.

LoadAlpha:
Set this field to True if the alpha channel of the anim shall be loaded, too. Please note that most anim formats do not support alpha channels. Thus, it is advised that you create the anim manually from a PNG picture using CreateAnim() if you need to have an alpha channel in your animation. This field defaults to False. (V4.5)

X, Y, Width, Height, Frames, FPR:
This group of fields is only used when you specify an image file source. In that case, you have to use these arguments to tell LoadAnim() how it shall create the animation from the image. Width and Height define the dimensions for the animation and Frames specifies how many frames LoadAnim() 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 (abbreviation for frames per row) to tell LoadAnim() how many frames there are in each row. Finally, you can tell LoadAnim() where in the image it should start scanning by specifying the fields X and Y (they both default to 0). LoadAnim() 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. (V4.5)

SkipLoopFrames:
If you set this to True, Hollywood will automatically skip the last two frames of the anim. This is only required for IFF ANIMs that have two loop frames at the end of the anim. Auto detection of loop frames is not possible because it would require Hollywood to decode the whole anim first. That is why you have to tell Hollywood manually whether the anim has loop frames or not. (V5.3)

Deinterlace:
This tag allows you to specify how Hollywood should deinterlace interlaced anims. This can be set to either #DEINTERLACE_DEFAULT or #DEINTERLACE_DOUBLE. If set to #DEINTERLACE_DEFAULT (which is as the name implies also the default), Hollywood will combine two half-frames into one full frame. This mostly results in the best quality but can lead to visual artefacts when there is a lot of movement in the anim. If you use #DEINTERLACE_DOUBLE instead, Hollywood will double the lines of a half-frame to get a full frame. This leads to some quality loss but can make the anim look more smooth. The best deinterlace mode to use always depends on the anim. Note that mostly you should not have to care about this tag at all because deinterlacing is actually only required for some obscure IFF ANIM formats which store interlaced frames like ANIM16i and ANIM32i. (V5.3)

Loader:
This tag allows you to specify one or more format loaders that should be asked to load this anim. 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 anim will be loaded. Please note that this tag is specifically designed for monochrome transparency channels, i.e. a transparent pen in a palette-based anim. If you want to load the alphachannel of an anim, 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. An animation cannot have a mask and an alpha channel!

This command is also available from the preprocessor: Use @ANIM to preload animations!

Inputs
id
identifier for the animation or Nil for auto id selection
filename$
file to load
table
optional: further options (see above) (V2.5)
Results
id
optional: identifier of the animation; will only be returned when you pass Nil as argument 1 (see above)
Example
LoadAnim(2, "MyAnim.gif", {Transparency = #RED})
This loads "MyAnim.gif" as anim 2 with the color red being transparent.

Show TOC