Name
BeginAnimStreamExt -- create a new animation stream (V10.0)
Synopsis
APTR handle = BeginAnimStreamExt(STRPTR filename, int width, int height,
                int format, int quality, int fps, struct hwTagList *tags);
Function
When targetting Hollywood 10.0 or better, this function should be used instead of BeginAnimStream() because it offers more flexibility. To make Hollywood use this function instead of BeginAnimStream(), set the HWEXT_SAVEANIM_BEGINANIMSTREAM extension bit. See Extension plugins to learn how to use plugin extension bits.

This function must create a new animation stream and save it as the specified file. After Hollywood has called this function, it will then call WriteAnimFrame() to add a number of frames to your animation stream. Once all frames have been added, Hollywood will call FinishAnimStream() on the stream handle.

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.

The tags argument will be set to a tag list that can contain the following tags:

HWBASTAG_FORMAT:
The iData member of this tag contains the identifier of the animation format that should be used. You only need to look at this tag if your plugin supports more than one output format. (V10.0)

HWBASTAG_ADAPTER:
Starting with Hollywood 10.0, users can specify the file adapter that should be used to save an anim. If this tag is set, Hollywood wants your plugin to use the file adapter specified in the pData member of the tag to save the anim. This means that you have to use hw_FOpenExt() instead of hw_FOpen() to save the anim. See hw_FOpenExt for details. (V10.0)

HWBASTAG_USERTAGS:
If this is set, pData will point to a struct hwUserTagList containing a list of user tags passed by 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. (V10.0)

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

Inputs
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
tags
tag list containing further parameters
Results
handle
animation handle or NULL in case of an error

Show TOC