APTR handle = BeginAnimStream(STRPTR filename, int width, int height,
                  int format, int quality, int fps);

The format parameter specifies the pixel format of the source frame data that will be passed by WriteAnimFrame() later. This can be one of the following constants:

HWSAVEANMFMT_ARGB:

Data is delivered as a 32-bit array consisting of ARGB pixels.

HWSAVEANMFMT_CLUT:

Data is delivered as 8-bit indices into a color look-up table.

You will only have to handle those formats that you have explicitly declared as supported when Hollywood called your RegisterAnimSaver() function.

The quality parameter contains a value between 0 and 100 indicating the desired quality for the output file. Animation formats that use lossy compression can use this member to determine compression settings for the animation. Animation formats that don't use any compression or offer lossless compression can ignore this parameter.

The fps parameter contains the desired playback rate for the animation in frames per second. This is not supported by all animation formats so you can ignore it if you want. Some animation formats also support a frame-based delay value that Hollywood will pass to you in its WriteAnimFrame() calls.

Please note that in case your plugin supports multiple output animation formats, you'll have to wait until the first call to WriteAnimFrame() on that stream until you can tell which format the user has chosen for the stream. This inconvenience is due to a design flaw in Hollywood: Support for multiple output animation formats wasn't available before Hollywood 5.3 but the API was designed for Hollywood 5.0. So there's just no room for another parameter in the BeginAnimStream() prototype declaration because it doesn't accept a tag list or any other parameter that could by dynamically extended as Hollywood functionality increases. Thus, you'll have to wait until WriteAnimFrame() which gives you the information in the FormatID structure member.

This function has to return a handle to the stream if the animation has been successfully created or NULL if there was an error.

Note that since Hollywood 10.0 it's recommended to use BeginAnimStreamExt() instead of this function because it also supports user tags and you don't have to wait until the first call to WriteAnimFrame() to learn about the output format. BeginAnimStream() is broken by design because it can't be extended so if you target Hollywood 10.0 or higher, you should use the more flexible BeginAnimStreamExt() instead. See BeginAnimStreamExt for details. Note if you use BeginAnimStreamExt(), you also need to set the HWEXT_SAVEANIM_BEGINANIMSTREAM extension bit. See Extension plugins to learn how to use plugin extension bits.

filename

desired location for the animation file on disk

width

animation width in pixels

height

animation height in pixels

format

format for the animation (see above)

quality

quality for the animation (see above)

fps

frames per second for the animation

handle

animation handle or NULL in case of an error