VRg SuperVGA Pascal Programmer's library
Autodesk Animator flick files playback
==============================================================================
Revision 4
------------------------------------------------------------------------------

This document covers FLI, FLI32 and FLICK units.

        [1.] FLI and FLI32 units

FLI and FLI32 units will play Autodesk Animator FLI files in standard VGA
320x200 mode 13h. FLI unit is for Borland Pascal (DOS and DPMI target) and
FLI32 unit is for TMT Pascal (32-bit DPMI target).

        [1.1] Procedures and functions in FLI32 unit

FLI32 unit has two procedures:

 procedure fliPlayFromMemory(var Flick);
 procedure fliPlayFromFile(FileName:string;FileOffset:dword);

fliPlayFromMemory will play back preloaded FLI file. Flick is variable, which
defines flick data location in memory.
fliPlayFromFile will play back animation from FLI file on disk. FileName is
FLI file path/name, FileOffset is an offset of flick data within somewhat
large data library. If playing from plain FLI file, set FileOffset to 0.

Playback process is controlled with global variables settings.

You must put your screen to 320x200x256 VGA videomode before calling either
of fliPlay* procedures.

If delay between frames is less then 56 milliseconds (flick speed is less
then 4) it is treated as zero. Such flicks are unusual case, though.

Only older (FLI) files will be processed. Newer Animator Pro (FLC) files
can not be played.

        [1.2] FLI32 global variables

Following global variables and constants are defined:

        [Constants]

       Version='1.21';

Contains text string with current unit version.

       fliInfiniteLoop:boolean=false;

If true, flick file will be wrapped back to first frame at the end.

       fliCheckKeyPress:boolean=true;

If true, <esc> keypress is checked during playback. If <esc> is pressed,
playback will stop.


       fliLoopTimes:word=1;

How many times repeat flick playback. Ignored if fliInfiniteLoop is set to
true.
       
       fliUserPreFrame:procedure=nil;

This is a procedure without parameters, which will be called before decoded
frame is put on the screen. 

       fliUserPostFrame:procedure=nil;

This is a procedure without parameters, which will be called after decoded
frame is put on the screen.

Use fliUserPreFrame and fliUserPostFrame to put your own graphics over
flick animation.

        [Variables]

 var fliVFB:pointer;

This variable contains address of Virtual Frame Buffer, where last decoded
frame is stored.


        [1.3] Procedures and functions in FLI unit

FLI unit is mostly similar to FLI32, with following differences:
        - There is no fliPlayFromMemory procedure;
        - There is no fliVFB variable;
        - There are two additional procedures:

function  fliAllocateVFB:pointer;
procedure fliFreeVFB;

        First one allocate Virtual Frame Buffer and returns its address.
You must call this function before call fliPlayFromFile. Second will free
previously allocated Virtual Frame Buffer.


        [2.] FLICK unit

FLICK is a TMT Pascal compiler unit.

Unlike FLI and FLI32, FLICK is not player, but frame decoder. It provides
methods to decode animation frame by frame. It is your own responsibility
to put these frames on screen with required speed.

FLICK will decode both older (FLI) and newer (FLC) Autodesk Animator files.

FLICK has object oriented design. It contains prototype class TFlick and its
descendants TFlickFile and TFlickBuffer. TFlick is a pure prototype class, so
objects of this class cannot be created. You have to create either TFlickFile
or TFlickBuffer object instances. TFlickFile and TFlickBuffer inherit all
public methods from TFlick, and are different only in constructor part. Of
course DecodeFrame method is also overridden.

Constructors for TFlickFile and TFlickBuffer are:

  constructor TFlickFile.Init(FileName:string;FileOffset:dword);

FileName is a flick file path/name. FileOffset is an offset of flick data in
somewhat large data library. If opening plain FLI/FLC file, set FileOffset to
zero.

  constructor TFlickBuffer.Init(Buffer:pointer);

Buffer is an address of preloaded flick data.

Destructor in both classes is named Done and has no input parameters.

        [2.1] TFlick public methods

TFlick class contains following public methods:

  function GetInfo:TFlickHeader;virtual;

Returns flick file header. TFlickHeader is a record with following fields:

type TFlickHeader=packed record
 Size:longint;                   (* Size of entire flick data  *)
 Signature:word;                 (* $AF11 or $AF12             *)
 Frames:word;                    (* Number of frames           *)
 Width:word;                     (* Frame width in pixels      *)
 Height:word;                    (* Frame height in pixels     *)
 BPPC:word;                      (* Color depth (always 8)     *)
 Flags:word;                     (* Must be zero               *)
 Speed:longint;                  (* Delay between frames in ms *) 
 Dummy:array[1..108] of byte;    (* Reserved                   *)
end;

Note: delay between frames is always returned in milliseconds, independently
of flick type (Signature value).

  function GetVFB:pointer;virtual;

Returns Virtual Frame Buffer address. VFB is allocated at object instance
creation time. Decoded frames will be put to this buffer.

  function GetPalette:TPalette;virtual;

Returns current palette. TPalette type is defined in LFB256 unit.

  function PaletteChanged:boolean;virtual;

Returns true if palette was changed during last frame decoding, false
otherwise.

  procedure DecodeFrame;virtual;

Decodes flick frame and moves frame pointer to next frame. If last frame
has been decode, frame pointer is moved back to first frame.

  function GetCurrentFrameNumber:word;virtual;

Returns number of last decoded frame. 0 means no frames yet decoded, or
last frame in sequence has been decoded.

==============================================================================

                                        Written by Asp //VRg
                                        July 1999

