ULONG *raw = LoadFrame(APTR handle, int frame, struct LoadAnimCtrl *ctrl);

For raster anims, i.e. HWANIMTYPE_RASTER, LoadFrame() must return the raw pixel data of the frame but note that the ULONG* return type is just for compatibility reasons. The actual format of the pixel data that LoadFrame() needs to return depends on whether the HWANMFLAGS_LOADPALETTE flag was set when OpenAnim() was called. If it was set, LoadFrame() needs to return 8-bit pen values (even if the bit depth of the image is less than 8-bit!). If HWANMFLAGS_LOADPALETTE wasn't set, LoadFrame() needs to return 32-bit ARGB values. The returned pixel array must use the exact dimensions returned by OpenAnim(), i.e. it must contain exactly width * height * bpp bytes. A line width different from the animation width is currently not supported.

For vector anims, i.e. HWANIMTYPE_VECTOR, LoadFrame() must return an opaque handle that only your plugin knows how to interpret. This handle will then be passed to GetFrame() and TransformFrame() to get or transform the pixel data. Thus, for vector anims, LoadFrame() must never return any actual pixel data but just a handle that GetFrame() and TransformFrame() can use later to get or transform the pixel data. Furthermore, you also don't have to write to any member of the struct LoadAnimCtrl passed in the ctrl parameter.

Also note that for raster anims, Hollywood will call FreeFrame() to free the frame returned by LoadFrame() whereas for vector anims Hollywood will call FreeVectorFrame() to free the frame returned by LoadFrame().

In case the anim is a raster anim, this function also has to provide certain information about the frame it has just loaded. This information has to be written to the struct LoadAnimCtrl that is passed in the third 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; // [unused] -- V10.0 };

In contrast to OpenAnim(), LoadFrame() only uses some members from the struct LoadAnimCtrl structure pointer. The following members are used by LoadFrame():

AlphaChannel:

This will be set to True whenever the LoadAlpha tag has been set to True.

ForceAlphaChannel:

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

Flags:

This member can be set to a combination of the following flags:

HWANMFLAGS_TRANSPARENCY:

This flag will be set whenever the user sets the LoadTransparency tag to True. If HWANMFLAGS_LOADPALETTE is set as well, you must return the pen that is to be made transparent in the TransPen structure member (see below). If HWANMFLAGS_LOADPALETTE is not set, you have to write the 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 LoadFrame() must return an array of 8-bit pixel data and a palette in the Palette structure member (see below). (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)

Depth:

Must be set to the frame's bit depth. Set this only for raster anims. (V9.0)

Palette:

If HWANMFLAGS_LOADPALETTE is set in the Flags member and the anim is a raster anim, you need to set this member to a pointer to a palette, stored as a ULONG array of 256 RGB colors. Note that the ULONG array must always have 256 entries, even if the bit depth is less than 8. Initialize unused palette entries to 0. (V9.0)

TransPen:

If HWANMFLAGS_LOADPALETTE and HWANMFLAGS_TRANSPARENCY are set and the frame has a transparent pen and the anim is a raster anim, set TransPen to the index of that transparent pen. Otherwise set this member to HWPEN_NONE. (V9.0)

handle

handle returned by OpenAnim()

frame

index of frame to load (starts from 0)

ctrl

pointer to a struct LoadAnimCtrl

raw

an array of raw pixel data