[id] = LoadAnim(id, filename$[, table])

Note that by default, this command will load all anim frames into memory which may take a while and significant amounts of memory. If you want to create an animation that dynamically loads frames as needed and only keeps the current frame in memory, use the OpenAnim() command instead or set the FromDisk tag to True (see below). See OpenAnim for details.

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. On Windows, LoadAnim() can also load anim formats supported by the Windows Imaging Component.

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

LoadPalette:

If this tag is set to True, Hollywood will load the anim as a palette anim. This means that you can get and modify the anim'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 animations 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 anim file (if the anim 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. An animation cannot have a mask and an alpha channel!

Starting with Hollywood 9.0, this function can also load vector anim formats if you have an appropriate plugin installed. Keep in mind, though, that if you load vector anim formats using LoadAnim(), the anim may not support all features of normal anims. See Vector animations for more information on vector anims.

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

id

identifier for the animation or Nil for auto id selection

filename$

file to load

table

optional: further options (see above) (V2.5)

id

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

LoadAnim(2, "MyAnim.gif", {Transparency = #RED})