Name
BeginAnimStream -- begin sequential anim creation (V4.5)
Synopsis
[id] = BeginAnimStream(id, file$, width, height[, format, table])
Function
This function allows you to create an empty animation object on disk that you can then subsequently append frames to using WriteAnimFrame(). The advantage of BeginAnimStream() over SaveAnim() is that SaveAnim() requires you to provide an animation object as the source. If you use BeginAnimStream(), you can append frames to your animation from individual brush objects. This gives you the utmost flexibility. Because of its sequential design, BeginAnimStream() can be used to create new animations of virtually unlimited size and length. You could easily create a 2 hour AVI video with this function.

The first argument to BeginAnimStream() must be an id for the new write animation object. Alternatively, you can specify Nil and BeginAnimStream() will return a handle to the object to you. The second argument specifies a path to a file that shall be created for this anim. Arguments three and four specify the desired dimensions of the animation. The fifth argument specifies the format of the animation. This can either be one of the following animation types 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. When calling WriteAnimFrame() you can use the Colors and Dither tags to specify the number of palette entries to allocate for the frame and whether or not dithering shall be applied. When using #ANMFMT_GIF with a palette frame, no quantizing will be done. #ANMFMT_GIF also supports palette anims with a transparent pen. #ANMFMT_GIF is the default format used by BeginAnimStream().

#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. When calling WriteAnimFrame() you can use the Colors and Dither tags to specify the number of palette entries to allocate for the frame and whether or not dithering shall be applied. When using #ANMFMT_IFF with a palette frame, 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:

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.

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:

When you have successfully obtained a handle to a new animation object, you can then sequentially append frames to it using WriteAnimFrame(). When you are done adding frames, you have to call FinishAnimStream() to finalize the animation file on disk and make it ready for use.

Inputs
id
id for the animation object or Nil for auto id selection
file$
destination file
width
desired width for the animation
height
desired height for the animation
format
optional: which anim format to use (defaults to #ANMFMT_GIF)
table
optional: further arguments for save operation; see above
Results
id
optional: identifier of the animation; will only be returned when you pass Nil as argument 1 (see above)
Example
CreateBrush(1, 320, 240)
SelectBrush(1)
SetFillStyle(#FILLCOLOR)
BeginAnimStream(1, "test.gif", 320, 240)
For Local k = 1 To 100
   Circle(#CENTER, #CENTER, k * 2, #RED)
   WriteAnimFrame(1, 1)
Next
FinishAnimStream(1)
EndSelect
The code above creates a new GIF animation with 100 frames. The animation will show a red circle zooming into the screen.
Show TOC