APTR handle = OpenAnim(STRPTR filename, struct LoadAnimCtrl *ctrl);

This function also has to provide certain information about the animation it has just loaded. This information has to be written to the struct LoadAnimCtrl that is passed in the second parameter. This structure looks like this:

struct LoadAnimCtrl { int Width; // [out] int Height; // [out] int LineWidth; // [out] int NumFrames; // [out] int AlphaChannel; // [out] int ForceAlphaChannel; // [out] STRPTR Adapter; // [in] -- V6.0 ULONG Flags; // [in] -- V6.0 ULONG *Palette; // [unused] -- V9.0 ULONG TransPen; // [unused] -- V9.0 int Depth; // [unused] -- V9.0 int Type; // [out] -- V9.0 struct hwUserTagList *UserTags; // [in] -- V10.0 };

Be careful when accessing above structure members: LoadAnimCtrl has seen several revisions in Hollywood's history. Before accessing members that haven't been there in all Hollywood versions you must make sure that your plugin has been opened by a Hollywood version that has those members or you will access unallocated memory!

The following information has to be written to the struct LoadAnimCtrl pointer by OpenAnim():

NumFrames:

Must be set to the number of frames in this animation.

Width:

Must be set to the animation width in pixels. Note that Hollywood only supports animations which use the same width for every frame.

Height:

Must be set to the animation height in pixels. Note that Hollywood only supports animations which use the same height for every frame.

AlphaChannel:

Must be set to True or False, depending on whether or not this animation uses frames that have an alpha channel.

ForceAlphaChannel:

If this is set to True, Hollywood will automatically create an alpha channel for all objects that load this animation. For example, if the user calls OpenAnim() on your animation but does not set the LoadAlpha tag to True, the animation will still get an alpha channel if you set ForceAlphaChannel to True. Note that this functionality was broken before Hollywood 6.0.

Adapter:

Starting with Hollywood 6.0 users can specify the file adapter that should be used to open certain files. If this member is non-NULL, Hollywood wants your plugin to use the file adapter specified in Adapter to open the animation. This means that you have to use hw_FOpenExt() instead of hw_FOpen() to open the animation. Make sure to check for Hollywood 6.0 before trying to access this member because it isn't there in previous versions. See hw_FOpenExt for details. (V6.0)

Flags:

The following flags may be set by Hollywood:

HWANMFLAGS_TRANSPARENCY:

This flag will be set whenever the user sets the LoadTransparency tag to True. You may then choose to write a frame's transparency information to its alpha channel and set the ForceAlphaChannel member to True. See above for more information. (V6.0)

HWANMFLAGS_LOADPALETTE:

This flag will be set whenever the user sets the LoadPalette tag to True. If this flag is set, your implementation of OpenAnim() should fail in case the anim does not have a palette. If it has a palette, you have to return that palette when Hollywood calls your LoadFrame() implementation. Note that palette anims must always use HWANIMTYPE_RASTER. They may not register as vector anims. (V9.0)

Make sure to check for Hollywood 6.0 before trying to access this member because it isn't there in previous versions. (V6.0)

Type:

If the HWEXT_ANIM_VECTOR extension bit has been set, Type must be set to the anim type. This may be either HWANIMTYPE_RASTER or HWANIMTYPE_VECTOR. If you set this to HWANIMTYPE_VECTOR, Hollywood will call your TransformFrame() function whenever it needs to transform a frame. This allows you to do lossless transformation of the vector frame. For anim frames of type HWANIMTYPE_RASTER, TransformFrame() will never be called. Instead, Hollywood does all transformations itself. (V9.0)

UserTags:

This member will be set to a list of user tags in case they were specified in the Hollywood script. User tags are a way of passing additional information from Hollywood scripts to plugin functions. Note that even if your plugin doesn't support any user tags, you should still look for this tag and pass the user tags to hw_FOpenExt because the user tags passed in UserTags could also be intended for another plugin, namely the file adapter plugin passed in Adapter. See User tags for details. Make sure to check for Hollywood 10.0 before trying to access this member because it isn't there in previous versions. (V10.0)

Please note that you should not use ANSI C functions like fopen() to open the file that is passed to this function because the filename that is passed to this function can also be a specially formatted filename specification that Hollywood uses to load files that have been linked to applets or executables. In order to be able to load these files correctly, you have to use special IO functions provided by Hollywood. See File IO information for details.

filename

filename to open

ctrl

pointer to a struct LoadAnimCtrl for storing information about the animation

handle

a handle that identifies this animation or NULL if plugin doesn't want to handle this animation