Liren Large Software Subsidy 7

home *** CD-ROM | disk | FTP | other *** search

/ Liren Large Software Subsidy 7 / 07.iso / c / c010 / 1.ddi / FLILIB3.ZIP / FLIDOC.TXT < prev next >

Wrap

Text File | 1990-07-18 | 44.4 KB | 1,334 lines

Turbo C FLI Library Documentation For FLI Files Created by Autodesk Animator November 20, 1989 Copyright 1989-1990 Dancing Flame, San Francisco Program Code and Library by Jim Kent Documentation by Jim Kent and Heidi Brumbaugh Turbo C FLI Library Table of Contents 1. Introduction to the Turbo C FLI library. . . . . . . . . . 1 2. Sample FLI programs. . . . . . . . . . . . . . . . . . . . 1 2.1 PLAY.C . . . . . . . . . . . . . . . . . . . . . . . 1 2.2 ALLFLIS.C. . . . . . . . . . . . . . . . . . . . . . 2 2.3 SLICEFLI.C . . . . . . . . . . . . . . . . . . . . . 3 3. Usage of FLI routines. . . . . . . . . . . . . . . . . . . 5 3.1 Playback Routines. . . . . . . . . . . . . . . . . . 5 3.2 Save Routines. . . . . . . . . . . . . . . . . . . . 6 4. VGA Graphics Support . . . . . . . . . . . . . . . . . . . 7 5. MS-DOS Support . . . . . . . . . . . . . . . . . . . . . . 8 6. The FLILIB header files. . . . . . . . . . . . . . . . . . 10 6.1 AAFLISAV.H . . . . . . . . . . . . . . . . . . . . . 10 6.2 AAFLI.H. . . . . . . . . . . . . . . . . . . . . . . 11 6.3 AATYPES.H . . . . . . . . . . . . . . . . . . . . . 13 6.4 AADOS.H. . . . . . . . . . . . . . . . . . . . . . . 14 6.5 AAERR.H. . . . . . . . . . . . . . . . . . . . . . . 16 6.6 AASCREEN.H . . . . . . . . . . . . . . . . . . . . . 16 8. Autodesk Animator files. . . . . . . . . . . . . . . . . . 18 8.1 Flic Files (.FLI). . . . . . . . . . . . . . . . . . 18 8.2 Picture Files (.GIF) . . . . . . . . . . . . . . . . 21 8.3 Cel Files (.CEL and .PIC). . . . . . . . . . . . . . 21 8.4 Palette Files (.COL) . . . . . . . . . . . . . . . . 22 8.5 Mask Files (.MSK). . . . . . . . . . . . . . . . . . 22 8.6 Text Files (.TXT). . . . . . . . . . . . . . . . . . 22 8.7 Font Files (.FNT). . . . . . . . . . . . . . . . . . 22 8.8 Polygon and Path files (.PLY). . . . . . . . . . . . 24 8.9 Optics Files (.OPT). . . . . . . . . . . . . . . . . 24 8.10 Record Files (.REC) . . . . . . . . . . . . . . . . 24 1. Introduction to the Turbo C FLI library FLI.LIB is a Turbo C large model library for manipulating Autodesk Animator FLI files. It also contains some general- purpose MS-DOS functions and a few VGA graphics primitives. The main Turbo C library is contained in the file FLI.LIB. Additionally, you will need to include the header file AAFLI.H to read a FLI file and AAFLISAV.H to save a FLI file. AAFLI.H will include the additional files AATYPES.H, AADOS.H, AAERR.H and AASCREEN.H if they are not already included. AAFLISAV.H will include AAFLI.H if it is not already included. The 58 source file routines to load or save a FLI are in the folder LIBSOURC; however, these modules are not necessary as they are already included in FLI.LIB. Your disk also includes three sample C files to load and play a FLI file. The sample batch file which compiles these files in Turbo C is: tcc -ml play.c fli.lib tcc -ml allflis.c fli.lib tcc -ml slicefli.c fli.lib In sum, the files you will need to use the Turbo C FLI library are: AATYPES.H AADOS.H AAERR.H AASCREEN.H AAFLI.H AAFLISAV.H FLI.LIB 2. Sample FLI programs Once the header files are included in your code and your make file is set up to properly link your program with the library, calling the high-level FLI routines is very straightforward. In fact, the sample programs show that you can write a program to play back a FLI in about twenty-five lines -- and most of that code is to verify that a VGA is connected! 2.1 PLAY.C This program will play a FLI file until a key is pressed. #include "aafli.h" main(int argc, char *argv[]) { int ivmode; Errval err; if (argc != 2) /* If command line looks wrong give a little help */ { puts("Play will play a FLI file until a key is hit"); puts("Example usage: play pretty.fli"); } else { ivmode = dos_get_vmode(); /* Get video mode to restore at exit */ dos_set_vmode(0x13); /* Go into 320x200 256 color mode */ if (dos_get_vmode() == 0x13) { err = fli_play(argv[1]); dos_set_vmode(ivmode); if (err < AA_SUCCESS) puts(fli_error_message(err) ); } else puts("Not a VGA/MCGA display"); } } 2.2 ALLFLIS.C This program plays all the FLI files in the current directory once and exits. #include "aafli.h" main() { Fndata *fn; int ivmode; Errval err; fn = dos_get_dta(); if (dos_first("*.FLI", DOS_ATTR_NORMAL)) { ivmode = dos_get_vmode(); dos_set_vmode(0x13); if (dos_get_vmode() == 0x13) { for (;;) { if (dos_key_is()) /* check keyboard to abort between FLI's */ { dos_key_in(); break; } err = fli_once(fn->name); if (err < AA_SUCCESS) { puts(fli_error_message(err)); } if (!dos_next()) break; } dos_set_vmode(ivmode); } else { puts("Not a VGA/MCGA display"); } } else { puts("No .FLI files"); } } 2.3 SLICEFLI.C This program cuts out every other line of a FLI file, creating a new FLI. #include "aaflisav.h" main(int argc, char *argv[]) { int i; Errval err; int ivmode; if (argc != 3) { puts("slicefli - a program to cut out every other line of a FLI."); puts(" usage: slicefli infile.fli outfile.fli"); exit(0); } ivmode = dos_get_vmode(); dos_set_vmode(0x13); /* To VGA/MCGA 320x200 256 color mode */ if (dos_get_vmode() != 0x13) { puts("Not a VGA/MCGA display, sorry"); } else { err = convert_fli(argv[1], argv[2]); if (err >= AA_SUCCESS) { fli_play(argv[2]); } dos_set_vmode(ivmode); if (err < AA_SUCCESS)puts(fli_error_message(err)); } } /* zero out every other line of a screen */ void slice_screen(Vscreen *s) { int i; Pixel *p; p = s->p; for (i=0; i<s->h; i+=2) { i86_bzero(p, s->bpr); p += 2*s->bpr; } } Errval convert_fli(char *in, char *out) { Errval err = AA_SUCCESS; /* start out optimistic! */ Vscreen *bs; Fli_head inhead, outhead; Jfile infile = 0, outfile = 0; int i; if ((bs = aa_alloc_mem_screen()) == NULL) { err = AA_ERR_NOMEM; goto EXIT; } if ((infile = fli_open(in, &inhead)) < 0) { err = infile; goto EXIT; } if ((outfile = fli_create(out, &outhead, inhead.speed)) < AA_SUCCESS) { goto EXIT; } for (i=0; i<inhead.frame_count; i++) { aa_copy_screen(&aa_screen, bs); if ((err = fli_next_frame(infile)) < AA_SUCCESS) { goto EXIT; } slice_screen(&aa_screen); if ((err = fli_write_next(outfile, &outhead, &aa_screen, bs)) < AA_SUCCESS) { goto EXIT; } } if ((err = fli_end(outfile, &outhead, &aa_screen, bs)) < AA_SUCCESS) { goto EXIT; } EXIT: if (infile != 0) dos_close (infile); if (outfile != 0) dos_close (outfile); aa_free_mem_screen(bs); if (err < AA_SUCCESS) { dos_delete (out); } return(err); } 3. Usage of FLI routines 3.1 Playback Routines These are the main routines you will need to use to play back a FLI animation. Note that you do not need to call some of the routines directly if you use only the high-level routines. See the sample programs above for details. Play a FLI on VGA screen until a key is hit. Errval fli_play(char *fliname) Play a FLI through once on VGA screen. Errval fli_once(char *fliname) Open up a FLI file, read in it's header, and check magic values to verify that it is a FLI file. Returns open file handle on success, a negative error code on failure. Jfile fli_open(char *fliname, Fli_head *fh) Read next frame of file and update VGA screen. Errval fli_next_frame(Jfile ff) Update a screen with the next frame of a FLI file. Note that fli_read_display_frame(ff, &aa_screen, TRUE) is the same thing as fli_next_frame(ff). Errval fli_read_display_frame( Jfile ff, /* File handle */ Vscreen *v, /* Screen to update */ Boolean see_colors) /* Update hardware color registers? */ This routine decompresses from memory onto a screen. Use if you want to play FLI's from RAM rather than off the disk. void fli_uncomp( Vscreen *v, /* Screen to update */ Fli_frame *frame, /* Header for this frame */ Cbuf *cbuf, /* Compressed data for this frame */ Boolean see_colors) /* Update hardware color registers? */ This plays a FLI from disk until the user-supplied function returns false. The 'until' function is called every frame at least once, and as many times as possible until it's time for the next frame. See fli_until_finished and fli_until_key. Errval fli_until( char *fliname, /* Name of FLI to play */ int speed, /* Speed to play. If negative uses speed in file */ Boolean (*until)()) /* User-supplied function. (See below.) */ This function returns (cur_frame < frame_count). It's used to implement fli_once(). Boolean fli_until_finished( int cur_frame, /* How many frames we've played */ int frame_count, /* Number of frames in this FLI */ int cur_loop) /* How many times have played FLI so far */ This function ignores all it's arguments, and returns FALSE only if a key is hit. Used to implement fli_play(). Boolean fli_until_key( int cur_frame, /* How many frames we've played */ int frame_count, /* Number of frames in this FLI */ int cur_loop) /* How many times have played FLI so far */ Return a descriptive name for the error code. char *fli_error_message(Errval err) 3.2 Save Routines The following routines are used to save a FLI file to disk. Start writing a FLI file. Open file and initialize Fli_head structure. Returns file handle if everything is ok, a negative error code if not. Jfile fli_create( char *fliname, /* Name for new FLI file */ Fli_head *fh, /* Non-initialized fli-header */ int speed) /* Speed (in 1/70th of a second) of FLI */ Write next frame to FLI file. On first frame the value in 'last' is ignored. Errval fli_write_next( Jfile ff, /* FLI file returned by fli_create */ Fli_head *fh, /* Same header used by fli_create */ Vscreen *this, /* Current frame */ Vscreen *last) /* Previous frame */ Close FLI up: calculate and write the ring frame, that is the difference between the first and last frame of a FLI. Rewrite fh at start of file with final frame and byte counts. Firstf_buf will be loaded with the first frame of the FLI as a side effect. Errval fli_end( Jfile ff, /* FLI file handle */ Fli_head *fh, /* Header as initialized by fli_create */ Vscreen *end_frame, /* The final frame in the animation */ Vscreen *firstf_buf) /* A full screen buffer for 1st frame */ Compress a frame into comp_buf and return size after compression. Types should be FLI_BRUN for first frame and FLI_LCCOMP for later frames (see AAFLI.H). If you use fli_create, fli_write_next, and fli_end to create your FLI files, you won't need to call this. long fli_comp_frame( Cbuf *comp_buf, /* Buffer--should be CBUF_SIZE or bigger */ Pixel *last_screen, /* Pixels from previous frame */ Cmap *last_cmap, /* Colors from previous frame */ Pixel *this_screen, /* Pixels from current frame */ Cmap *this_cmap, /* Colors from previous frame. */ int type); /* FLI_BRUN, FLI_LCCOMP etc. */ 4. VGA Graphics Support Most of these are lower-level routines you won't need to call directly; however, they are included in the library and supported here. Sets up a 320x200 screen in memory that is structured the same as the VGA Mode 0x13. (The Vscreen structure is in AASCREEN.H.) Vscreen *aa_alloc_mem_screen() Set all pixels in screen to zero. void aa_clear_screen(Vscreen *s) Software echo of color map associated with aa_screen, the Vscreen for the VGA. Cmap aa_colors[256*3] Copy the pixels and color maps from one screen to another. (Doesn't update VGA hardware registers. Use aa_set_colors(0, 256, dest->cmap) to do that.) void aa_copy_screen(Vscreen *source, Vscreen *dest) Does nothing but call C library free(pt). Used by all flilib functions to free aa_malloc()'d memory. If you need to manage your own memory override these two symbols with your own. void aa_free(void *pt) Frees up memory screen gotten with aa_alloc_mem_screen(). Will check 's' for NULL before calling aa_free. void aa_free_mem_screen(Vscreen *s) Returns a AACLOCK_HZ frequency clock. (AACLOCK_HZ is defined in AACLOCK.H as 4608 currently, but this may change. The clock management part of library is still unstable.) You must call aa_goclock() before calling this. long aa_getclock() Initialize clock. long aa_goclock() Does nothing but call C library malloc(size). See aa_free(). void *aa_malloc(unsigned size) A Vscreen structure refering to the VGA pixel memory. Useful as an argument to the many flilib functions that work on a Vscreen. Vscreen aa_screen Set some VGA color map entries from a memory table. Table is three bytes per color, one byte each for each red, green, blue component. The value of an rgb component should be from 0 to 63. void aa_set_colors(int start_ix, int count, Cmap *table) Return when VGA is out of vertical blank. void aa_wait_no_vblank() Return when VGA is in vertical blank. void aa_wait_vblank() 5. MS-DOS Support These are some general-purpose DOS routines. That Jfile is typedef'd as an int in AADOS.H. Close a file opened with dos_open or dos_create. void dos_close(Jfile file) Tries to delete file. Returns TRUE (1) on success, FALSE (0) on failure. Boolean dos_delete(char *file_name) Returns TRUE if file exists. Boolean dos_exists(char *file_name) Pattern is typically something of the form "*.FLI" and attribute DOS_ATTR_NORMAL as defined in AADOS.H. This will return TRUE if there is a file matching the wildcard pattern and put the name of this file in the data transfer area (see dos_get_dta below). Boolean dos_first(char *pattern, int attribute) Gets data transfer area from DOS for directory searches. See dos_first() and dos_next(). Fndata dos_get_dta(void) Returns current display mode. int dos_get_vmode() Returns a 16-bit keyboard scan code. Lower 8 bits are usually ASCII values, or zero if it's a special key such as the cursor arrows. int dos_key_in() Returns TRUE if a key is ready to be read from keyboard. Boolean dos_key_is() Returns a value with bits for the Shift/Alt/Control keys. int dos_key_shift() Tries to make a new directory. Boolean dos_make_dir(char *dir_name) Fetches next filename matching wildcard set up by dos_first() into the data transfer area. Returns FALSE if there are no more matches. Boolean dos_next() Tries to open a file from MS-DOS. Returns zero if can't open file. (Not negative as standard.) See AADOS.H for definitions of JREAD_ONLY, etc. for mode. Jfile dos_open(char *filename, int mode) Read from file into memory buffer. Note that size can be larger than 64K. long dos_read(Jfile file, void *buf, long size) Rename a file. Return success. Boolean dos_rename(char *oldname, char *newname) This is used to implement dos_read() and dos_write() macros. Should not be called directly. long dos_rw(...) Write from memory buffer into file. Note that size can be larger than 64K. long dos_write(Jfile file, void *buf, long size) See AADOS.H for definitions of JSEEK_START etc. for mode. long dos_seek(Jfile file, long offset, int mode) Set display mode. 0x13 for 256 color 320x200. void dos_set_vmode(int mode) Returns file position in bytes from beginning. long dos_tell(Jfile file) 6. The FLILIB header files Following are the constants, structures and variables used in the header files you will need to play back and save a FLI file. 6.1 AAFLISAV.H #ifndef AAFLISAV_H #define AAFLISAV_H #ifndef AAFLI_H #include "aafli.h" #endif /* AAFLI_H */ /* Compress a frame into a RAM buffer. Return size of frame. */ long fli_comp_frame(Cbuf *comp_buf, /* Buffer FLI_CBUF_SIZE or bigger */ Pixel *last_screen, Cmap *last_cmap, /*Data from previous frame*/ Pixel *this_screen, Cmap *this_cmap, /* Data for this frame */ int type); /* FLI_BRUN? FLI_LC? */ /* Open FLI file and write out first frame. Return file handle if things go well, error code otherwise. */ Jfile fli_create(char *fliname, /* file name */ Fli_head *fh, /* fli_create will initialize this */ int speed); /* Speed in 1/70th of a second */ /* Write succeeding frames of a FLI. */ Errval fli_write_next(Jfile ff, /* FLI file returned by fli_create */ Fli_head *fh, /* Same header used by fli_create */ Vscreen *this, /* Current frame */ Vscreen *last); /* Previous frame */ /* Finish up writing a FLI file. Write the 'ring frame', which is the difference between the first and last frame of a FLI. Pass in the final frame of the FLI in last_frame. firstf_buf will be loaded with the first frame of the FLI as a side effect. */ Errval fli_end(Jfile ff, Fli_head *fh, Vscreen *end_frame, Vscreen *firstf_buf); #endif /* AAFLISAV_H */ 6.2 AAFLI.H #ifndef AAFLI_H #define AAFLI_H #ifndef AATYPES_H #include "aatypes.h" #endif /* AATYPES_H */ #ifndef AADOS_H #include "aados.h" #endif /* AADOS_H */ #ifndef AAERR_H #include "aaerr.h" #endif /* AAERR_H */ #ifndef AASCREEN_H #include "aascreen.h" #endif /* AASCREEN_H */ #define FLI_MAXFRAMES (4*1000) /* Max number of frames. */ #define FLIH_MAGIC 0xaf11 /* Fileheader Magic */ #define FLIF_MAGIC 0xf1fa /* Frame Magic */ typedef struct fli_head { long size; USHORT type; /* = FLIH_MAGIC */ USHORT frame_count; USHORT width; USHORT height; USHORT bits_a_pixel; SHORT flags; SHORT speed; long next_head; long frames_in_table; SHORT file; /* Used by players. Contains 0's on disk. */ long frame1_off; /* Used by players. Contains 0's on disk. */ long strokes; /* how many paint strokes etc. made. */ long session; /* strokes since file's been loaded. */ char reserved[88]; /* all zeroes on disk */ } Fli_head; /* bit defines for flags field */ #define FLI_FINISHED 1 /* finished writing fli */ #define FLI_LOOPED 2 /* fli has a loop frame */ typedef struct fli_frame { long size; USHORT type; /* FLIF_MAGIC */ SHORT chunks; char pad[8]; } Fli_frame; typedef struct fli_chunk { long size; SHORT type; } Fli_chunk; typedef UBYTE Cbuf; /* compression buffer */ /* size of buffer big enough to hold worst case FLI frame */ #define FLI_CBUF_SIZE (64000L+3*AA_COLORS+2*sizeof(Fli_chunk)+sizeof(Fli_frame)) /* types of chunk in a fli_frame */ #define FLI_COLOR 11 #define FLI_LC 12 #define FLI_BLACK 13 #define FLI_BRUN 15 #define FLI_COPY 16 /** Higher-level FLI playing functions **/ /* Decompress a single frame that's in RAM */ void fli_uncomp(Vscreen *f, /* The screen to update */ Fli_frame *frame, /* Header for this frame */ Cbuf *cbuf, /* Compressed data for this frame */ Boolean see_colors); /* update the hardware color map? */ /* Read in FLI header, verify that it's a FLI file and return handle. See AAERR.H for negative return values if there are problems. */ Jfile fli_open(char *fliname, Fli_head *fh); /* Read in next frame and uncompress onto screen, optionally updating hardware color palette */ Errval fli_read_display_frame(Jfile ff, Vscreen *v, Boolean see_colors); /* Read and display next frame onto VGA display */ Errval fli_next_frame(Jfile ff); /* Play FLI, going on forever or until 'until' function returns FALSE. until is called with the current frame, the total frame in the FLI, and how many times have played entire FLI. */ Errval fli_until(char *fliname, /* name of FLI to play */ int speed, /* if speed negative, use speed in file */ AAivec until); /* function to call to see when to stop */ /* The 'until' function we use to construct fli_play */ Boolean fli_until_key(int cur_frame, int frame_count, int cur_loop); /* Play FLI looping forever until any key is hit */ Errval fli_play(char *fliname); /* Play FLI once */ Errval fli_once(char *fliname); #endif /* AAFLI_H */ 6.3 AATYPES.H #ifndef AATYPES_H #define AATYPES_H #ifndef NULL #define NULL ((void *)0L) #endif /* NULL */ void *aa_malloc(unsigned); /* heap allocator */ void aa_free(void *); /* heap free'er */ #ifndef UBYTE #define UBYTE unsigned char #endif /* UBYTE */ #ifndef BYTE #define BYTE signed char #endif /* BYTE */ #ifndef SHORT #define SHORT short #endif /* SHORT */ #ifndef SHORT #define SHORT short #endif /* SHORT */ #ifndef USHORT #define USHORT unsigned short #endif /* USHORT */ #ifndef LONG #define LONG long #endif /* LONG */ #ifndef ULONG #define ULONG unsigned long #endif /* ULONG */ typedef void (*AAvec)(); /* pointer to a void-valued function */ typedef int (*AAivec)(); /* pointer to an integer valued function */ typedef int Boolean; /* functions explicitly returning 0 or 1 */ #define TRUE 1 #define FALSE 0 /* useful macro to count elements in an array */ #define Array_els(arr) (sizeof(arr)/sizeof(arr[0])) #endif /* AATYPES_H */ 6.4 AADOS.H #ifndef AADOS_H #define AADOS_H #ifndef AATYPES_H #include "aatypes.h" #endif /* AATYPES_H */ typedef int Jfile; dos_key_is(void); /* return 1 if a key is ready to read, 0 if not */ dos_key_in(void); /* return next keyboard input. Wait for it. */ /* open a file that already exists.*/ Jfile dos_open(char *title, int mode); /* defines for mode parameter to dos_open */ #define DOS_READ_ONLY 0 #define DOS_WRITE_ONLY 1 #define DOS_READ_WRITE 2 Jfile dos_create(char *title); /* Create a new read/write file */ void dos_close(Jfile f); /* close file */ /* File read/write. Normally go through macros rather than use this function. */ long dos_rw(Jfile f,void *buf,long size,int ah); #define dos_read(f,b,size) dos_rw(f,b,size,0x3f) #define dos_write(f,b,size) dos_rw(f,b,size,0x40) long dos_seek (Jfile f, long offset, int mode); long dos_tell (Jfile f); /* defines for mode parameter to dos_seek */ #define DOS_SEEK_START 0 #define DOS_SEEK_RELATIVE 1 #define DOS_SEEK_END 2 /* size of a buffer long enough to hold any MS-DOS path */ #define DOS_PATH_SIZE 80 /* this is the data structure used by dos_first() and dos_next () in searching directories */ typedef struct fndata { char reserved[21]; char attribute; USHORT time, date; long size; char name[13]; char fordos[128-43]; } Fndata; Fndata *dos_get_dta (void); /* get the DTA for directory search */ Boolean dos_first(char *pattern, int attributes); /* defines for attributes parameters */ #define DOS_ATTR_DIR 16 #define DOS_ATTR_NORMAL 0 Boolean dos_next (void); /* This gets rid of the MS-DOS abort/retry/fail message. Afterwards MS-DOS acts like it was always a fail. dos_get_devlist () calls this. */ void dos_no_abort_retry_cancel (void); /* Changes device and directory. For example, name could be C:\VPAINT\FISHIES */ Boolean dos_change_dir(char *name); /* Tell DOS it's time to go to another drive number. 0 = A:, 1 = B:, etc. */ Boolean dos_change_dev(int newdev); /* Get current drive. 0 = A:, etc. */ int dos_get_dev (void); /* Get the current device and directory into path */ Boolean dos_get_dir (char path[DOS_PATH_SIZE]); /* Create a directory. (Don't include device info. If needed do a dos_change_dev(dev) first.) */ Boolean dos_make_dir(char *name); /* Figure how much free space is on a device. 0 = current device. 1 = A:, etc. */ long dos_dfree(int dev); #endif /* AADOS_H */ 6.5 AAERR.H #ifndef AAERR_H #define AAERR_H #define AA_SUCCESS 0 /* No Problem! */ #define AA_ERR_MISC -1 /* Unclassified error */ #define AA_ERR_NOMEM -2 /* Not enough memory */ #define AA_ERR_CANTFIND -3 /* File doesn't exist */ #define AA_ERR_CANTMAKE -4 /* Can't create file */ #define AA_ERR_BADTYPE -5 /* File is not the right type */ #define AA_ERR_BADDATA -6 /* File damaged internally */ #define AA_ERR_WRONGREZ -7 /* File isn't 320x200 */ #define AA_ERR_SHORTREAD -8 /* Not all of file is there */ #define AA_ERR_SHORTWRITE -9 /* Couldn't write all of file */ #define AA_ERR_SEEK -10 /* Error during file seek */ typedef int Errval; /* return something to say about error */ char *fli_error_message(Errval err); #endif /* AAERR_H */ 6.6 AASCREEN.H #ifndef AASCREEN_H #define AASCREEN_H #ifndef AATYPES_H #include "aatypes.h" #endif /* AATYPES_H */ /* Graphics types */ typedef unsigned char Cmap; typedef unsigned char Pixel; typedef unsigned char Bitplane; /* Constants pertaining to 320x200 256 color mode mostly */ #define AA_VGA_SCREEN ((Pixel *)0xa0000000) #define AA_XMAX 320 #define AA_YMAX 200 #define AA_BPR 320 #define AA_COLORS 256 /* This structure is something we can draw on. */ struct vscreen { int x, y; /* upper left corner in screen coordinates */ unsigned w, h; /* width, height */ unsigned bpr; /* bytes per row of image p */ Pixel *p; /* Starts on segment boundary */ Cmap *cmap; long psize;/* size of pixels */ Pixel *allocedp; /* for memory based screens only */ }; typedef struct vscreen Vscreen; extern Vscreen aa_screen; extern Cmap aa_colors[]; /* software echo of color map */ Boolean aa_open_vga_screen(void); /* opens 256 color screen */ void aa_close_vga_screen(void); /* Open a screen you can draw on but not see */ Vscreen *aa_alloc_mem_screen(void); void aa_free_mem_screen(Vscreen *ms); /* dispose of memory screen */ void aa_copy_screen(Vscreen *source, Vscreen *dest); void aa_clear_screen(Vscreen *vs); /* Get the current video mode */ int dos_get_vmode(void); /* Set video mode. Mode 0x13 is 320x200 256 color */ void dos_set_vmode(int mode); /* Set the VGA color map. */ void aa_set_colors(int start, int count, Cmap *cmap); /* Wait until in vertical blank */ void aa_wait_vblank(void); /* Wait until out of vertical blank */ void aa_wait_no_vblank(void); #endif /* AASCREEN_H */ 7. Reserved Routine Names What follows is a summary of low-level routines which you should not call directly as they are subject to future modification. They are listed here only to prevent you from inadvertently duplicating the names elsewhere in your own code. fii_brun fii_fccomp fii_lccomp fii_mem_fcuncomp fii_reg_fcuncomp fii_tnsame fii_tnskip fii_unbrun fii_unlccomp i86_bcompare i86_bcontrast i86_bcopy i86_bsame i86_bzero i86_enorm_ptr i86_even_copy i86_make_long i86_make_ptr i86_norm_ptr i86_ptr_offset i86_ptr_seg i86_ptr_to_long i86_sysint i86_wcompare i86_wcontrast i86_wcopy i86_wsame i86_wzero 8. Autodesk Animator files Following is a detailed description of the FLI file format, as well as the formats for Autodesk Animator's other main file types. 8.1 Flic Files (.FLI) The details of a FLI file are moderately complex, but the idea behind it is simple: don't bother storing the parts of a frame that are the same as the last frame. Not only does this save space, but it's very quick. It's faster to leave a pixel alone than to set it. A FLI file has a 128-byte header followed by a sequence of frames. The first frame is compressed using a bytewise run-length compression scheme. Subsequent frames are stored as the difference from the previous frame. (Occasionally the first frame and/or subsequent frames are uncompressed.) There is one extra frame at the end of a FLI which contains the difference between the last frame and the first frame. The FLI header: byte size name meaning offset 0 4 size Length of file, for programs that want to read the FLI all at once if possible. 4 2 magic Set to hex AF11. Please use another value here if you change format (even to a different resolution) so Autodesk Animator won't crash trying to read it. 6 2 frames Number of frames in FLI. FLI files have a maxium length of 4000 frames. 8 2 width Screen width (320). 10 2 height Screen height (200). 12 2 depth Depth of a pixel (8).142flagsMust be 0. 16 2 speed Number of video ticks between frames. 18 4 next Set to 0. 22 4 frit Set to 0. 26 102 expand All zeroes -- for future enhancement. Next are the frames, each of which has a header: byte size name meaning offset 0 4 size Bytes in this frame. Autodesk Animator demands that this be less than 64K. 4 2 magic Always hexadecimal F1FA 6 2 chunks Number of 'chunks' in frame. 8 8 expand Space for future enhancements. All zeros. After the frame header come the chunks that make up the frame. First comes a color chunk if the color map has changed from the last frame. Then comes a pixel chunk if the pixels have changed. If the frame is absolutely identical to the last frame there will be no chunks at all. A chunk itself has a header, followed by the data. The chunk header is: byte size name meaning offset 0 4 size Bytes in this chunk. 4 2 type Type of chunk (see below). There are currently five types of chunks you'll see in a FLI file. number name meaning 11 FLI_COLOR Compressed color map 12 FLI_LC Line compressed -- the most common type of compression for any but the first frame. Describes the pixel difference from the previous frame. 13 FLI_BLACK Set whole screen to color 0 (only occurs on the first frame). 15 FLI_BRUN Bytewise run-length compression -- first frame only 16 FLI_COPY Indicates uncompressed 64000 bytes soon to follow. For those times when compression just doesn't work! The compression schemes are all byte-oriented. If the compressed data ends up being an odd length a single pad byte is inserted so that the FLI_COPY's always start at an even address for faster DMA. FLI_COLOR Chunks The first word is the number of packets in this chunk. This is followed directly by the packets. The first byte of a packet says how many colors to skip. The next byte says how many colors to change. If this byte is zero it is interpreted to mean 256. Next follows 3 bytes for each color to change (one each for red, green and blue). FLI_LC Chunks This is the most common, and alas, most complex chunk. The first word (16 bits) is the number of lines starting from the top of the screen that are the same as the previous frame. (For example, if there is motion only on the bottom line of screen you'd have a 199 here.) The next word is the number of lines that do change. Next there is the data for the changing lines themselves. Each line is compressed individually; among other things this makes it much easier to play back the FLI at a reduced size. The first byte of a compressed line is the number of packets in this line. If the line is unchanged from the last frame this is zero. The format of an individual packet is: skip_count size_count data The skip count is a single byte. If more than 255 pixels are to be skipped it must be broken into 2 packets. The size count is also a byte. If it is positive, that many bytes of data follow and are to be copied to the screen. If it's negative a single byte follows, and is repeated -skip_count times. In the worst case a FLI_LC frame can be about 70K. If it comes out to be 60000 bytes or more Autodesk Animator decides compression isn't worthwhile and saves the frame as FLI_COPY. FLI_BLACK Chunks These are very simple. There is no data associated with them at all. In fact they are only generated for the first frame in Autodesk Animator after the user selects NEW under the FLIC menu. FLI_BRUN Chunks These are much like FLI_LC chunks without the skips. They start immediately with the data for the first line, and go line- by-line from there. The first byte contains the number of packets in that line. The format for a packet is: size_count data If size_count is positive the data consists of a single byte which is repeated size_count times. If size_count is negative there are -size_count bytes of data which are copied to the screen. In Autodesk Animator if the "compressed" data shows signs of exceeding 60000 bytes the frame is stored as FLI_COPY instead. FLI_COPY Chunks These are 64000 bytes of data for direct reading onto the screen. 8.2 Picture Files (.GIF) GIF (Graphics Interchange Format) is a format developed by CompuServe Information Services. GIF files are as close to computer- and resolution-independent as we're likely to see in the next few years -- there are GIF viewers available for the Amiga, the Atari ST and 8-bit line, the Tandy Color Computer, the Apple II, the MacIntosh, Sun workstations, PC compatibles and most other computers with any sort of graphics display at all. There are also programs to convert from the more "native" file formats (such as DEGAS on the ST, IFF on the Amiga, and MacPaint on the Mac) to GIF. Many of these conversion programs are available free on Compuserve. GIF files are also fairly densely compressed, using a modified Lempel-Zif-Welch "ladder" compression scheme similar to that used in the popular archive programs ARC and PKZIP. Unfortunately the nitty-gritty details of what goes into a GIF file are rather complex, and CompuServe holds the copyright to much of the documentation. The PICS forum on CompuServe (type "go pics" at any exclamation mark prompt) will provide GIF documentation and much more in the way of useful information to graphics programmers if you fill out a simple developer's registration form. Another place to look for GIF information is the Autodesk forum on CompuServe; type "go autodesk" to learn more. 8.3 Cel Files (.CEL and .PIC) A cel file has a 32-byte header followed by the uncompressed color map (768 bytes) followed by the uncompressed pixel image. The header is: Byte Offset Contents 0 Magic Number - 9119 Hexadecimal 2 Width of cel 4 Height of cel 6 Horizontal screen position of upper left corner 8 Vertical screen position 10Number of bits in a pixel (8) 11 Compression type (0 for uncompressed) 12 Size in bytes of cel image (a 4-byte long word) 16 16 bytes of zero reserved for future use. A .PIC file uses the same format, with width and height 320x200 and screen position 0x0. (.PIC files are generated in Autodesk Animator if you supply a .PIC file suffix while loading or saving a single frame. Otherwise a GIF file is made.) 8.4 Palette Files (.COL) A color file is just a binary image of the color palette. It consists of 768 bytes -- three bytes for each color. Each byte has a value from 0 to 63. The red byte comes first, then the green, then the blue. 8.5 Mask Files (.MSK) A mask file is is an 8000-byte file. It contains one bit for each pixel of the screen. It goes from left to right, top to bottom. 8.6 Text Files (.TXT) These are just ordinary ASCII files. 8.7 Font Files (.FNT) My font files are a slightly strange hybrid. They started out as the same type of file that GEM on the ST uses. Then some additions were made to make it easier to convert MacIntosh fonts to a format Autodesk Animator could use. My apologies for creating yet another font file format for the PC (this only makes about 12 I know of...), especially as I don't completely understand this one myself! A font file starts out with an 88-byte header. This is followed by up to three tables of various sizes: Byte Offset Name Meaning 0 id Identifier. Hex 9000 if Mac-converted 2 size Point size of font. Not used by Animator 4 facename 32 byte name of font. Not used by Animator 36 ADE_lo Lowest ASCII character in font. More often than not this is 20 hex (space character). 38 ADE_hi Highest character in font. 40 top_dist unknown, unused by Animator42asc_distunknown, unused by Animator 44 hlf_dist unknown, unused by Animator 46 des_dist unknown, unused by Animator 48 bot_dist unknown, unused by Animator 50 wchr_wdt widest character width 52 wcel_width widest 'cell' width (includes distance to next character) 54 lft_ofst unknown, unused by Animator 56 rgt_ofst if Mac font, is negative of Mac maxKern value. Else unknown & unused. 58 thckning How bold is bold? Unused by Animator 60 undrline How far down to underline? Unused by Animator 62 lghtng_m Lightening mask. Mask for light style. Unused by Animator 64 skewng_m Skewing mask for italics. Rotate line on a 1 bit. Unused by Animator 66 flags Will swap bytes of image if bit 2 is non-zero. (Part of DRI's attempt to make 8086/68000 work together.) 68 hz_ofst Unknown, unused in Animator 72 ch_ofst Unknown, unused in Animator 76 fnt_dta Unknown, unused in Animator 80 frm_wdt Byte width of bitmap 82 frm_hgt Pixel height of bitmap 84 nxt_fnt Unknown, unused in Animator The first table is a series of 16-bit words containing the horizontal offset into the font bitmap image of the start of each letter. The width of the letter is calculated by subtracting the offset of the next character from the offset of current character. There's one offset for each character in the font, plus an extra one to give the width of the last character. This table is always present. The second table contains the font image. This is a single bit-map for the whole font (as opposed to a series of bitmaps one for each character). This table is always present. The third table is only present in fonts we've translated from the MacIntosh (that is, if the id field in the header is hexadecimal 9000). There are two bytes for each character in the font. If both bytes are FF hexidecimal it is a 'missing character', and will not be drawn. The first byte is added to the rgt_ofst field of the header to tell how many pixels to move to the right (or left if the result is negative) before drawing this character. The second byte is how many pixels to move to the right after drawing this character. 8.8 Polygon and Path files (.PLY) A polygon file has an 8-byte header followed by 6 bytes for each point of the polygon (2 bytes each x,y,z with z always zero currently). Here is the header: Byte Offset Contents 0 16-bit point count 2 4 bytes of zero 6 1 if polygon closed, 0 otherwise 7 Magic number - hex 99 8.9 Optics Files (.OPT) An optics file has a 4-byte header followed by a series of optical moves records of 50 bytes each. Each time you click on CONTINUE MOVE in the OPTICS menu in Autodesk Animator another record is generated. The header format is: Byte Offset Contents 0 Magic Number - 1A3F Hexadecimal 2 Number of moves in this file. 16-bit count Here's the format for an individual record: Byte Offset Contents 0 4 bytes of zero (room for pointer to next record when it's loaded into memory) 4 Spin center. x/y/z location (16 bits each) 10 Spin axis. x/y/z location (16 bits each) 16 Spin turns x/y/z (16 bits each) 22 Intermediate turns. Two 16-bit words. These are values for a conjugation matrix that corresponds to spin axis. 26 Size center x/y/z location (16 bits each) 32 x multiplier -- together with x divisor determines how to stretch along x (horizontal) dimension 34 x divisor 36 y multiplier 38 y divisor 40 both multiplier - applied to both x and y dimensions 42 both divisor 44 linear move x/y/z offset (16 bits each) 8.10 Record Files (.REC) A record file has a 16-byte header followed by any number of 8-byte input records. The header format is: Byte Offset Contents 0 Magic Number - 0713 Hexadecimal2long word (4 byte) count of number of input records 6 4 bytes of 0 10 1 if real-time macro, 0 otherwise 11 5 bytes of 0 The format of a input record is: Byte Offset Contents 0 Time (in 70th of second) from last record if real-time, 0 otherwise. 1 Mouse button state. Bit 0 is left button, bit 1 is right button. (i.e. the value is 3 if both buttons down, 1 if only left button, 0 if no buttons down.) 2 16-bit keyboard code if key pressed, 0 otherwise. 4 16-bit mouse horizontal position 6 16-bit mouse vertical position