Name
SaveAnim -- save animation to disk (V4.5)
Synopsis
SaveAnim(id, file$[, format, table])
Function
This function saves the animation specified by id to the file specified by file$ in animation format specified by format. This can either be one of the following constants or an anim saver provided by a plugin:

#ANMFMT_GIF:
GIF format. Because GIF anims are always palette-based, RGB graphics have to be quantized before they can be exported as GIF. You can use the Colors and Dither tags (see below) to specify the number of palette entries to allocate for the anim and whether or not dithering shall be applied. When using #ANMFMT_GIF with a palette anim, no quantizing will be done. #ANMFMT_GIF also supports palette anims with a transparent pen. #ANMFMT_GIF is the default format used by SaveAnim().

#ANMFMT_MJPEG:
AVI with Motion JPEG compression. This is a lossy anim format so you can set the Quality tag (see below) to control the level of compression that should be used.

#ANMFMT_IFF:
IFF anim. Hollywood will use mode 5 compression (the most common compression mode) for IFF anims. Because IFF anims are always palette-based, RGB graphics have to be quantized before they can be exported as IFF. You can use the Colors and Dither tags (see below) to specify the number of palette entries to allocate for the anim and whether or not dithering shall be applied. When using #ANMFMT_IFF with a palette anim, no quantizing will be done. #ANMFMT_IFF also supports palette anims with a transparent pen. (V9.0)

The optional table argument allows you to configure further parameters:

Dither:
Set to True to enable dithering. This field is only handled when the destination format is palette-based and the source data is RGB. GIF anims and IFF anims always use a color palette. Defaults to False which means no dithering.

Depth:
Specifies the desired anim depth. This is only handled when the format is palette-based and the source data is in RGB format. Valid values are between 1 (= 2 colors) and 8 (= 256 colors). Defaults to 8. (V9.0)

Colors:
This is an alternative to the Depth tag. Instead of a bit depth, you can pass how many colors the anim shall use here. Again, this is only handled when the format is palette-based and the source data is in RGB format. Valid values are between 1 and 256. Defaults to 256.

Optimize:
Specifies whether or not Hollywood shall try to optimize the animation. Optimized saving is slower but usually leads to smaller animations. Defaults to True.

Quality:
Here you can specify a value between 0 and 100 indicating the compression quality for lossy compression formats. A value of 100 means best quality, 0 means worst quality. This is only available for anim formats that support lossy compression. Defaults to 90 which means pretty good quality.

FPS:
Video formats like AVI do not support an individual delay value for each frame but require a global value indicating how many frames per second shall be displayed. This field allows you to set the FPS. This is only handled for video file formats. Defaults to 25 frames per second.

FillColor:
When saving an RGB anim that has transparent pixels, you can specify an RGB color that should be written to all those transparent pixels here. This is probably of not much practical use. Defaults to #NOCOLOR which means that transparent pixels will be left as they are. (V9.0)

Adapter:
This tag allows you to specify one or more file adapters that should be asked if they want to save the specified file. If you use this tag, you must set it 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. (V10.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)

Here is a table that shows an overview which table elements can be used with the different animation formats:

SaveAnim() can be used both with animations buffered completely in memory or with disk-based animations.

If you want to save an animation from individual frames (e.g. a series of brushes), you can do so by using BeginAnimStream(), WriteAnimFrame() and FinishAnimStream().

Inputs
id
animation which shall be saved
file$
destination file
format
optional: which anim format to use (defaults to #ANMFMT_GIF)
table
optional: further arguments for save operation; see above
Example
SaveAnim(1, "my_anim.gif", #ANMFMT_GIF, {Colors = 64, Dither = True})
The code above saves anim 1 as "my_anim.gif" in 64 colors with dithering enabled.

Show TOC