
    FLILIB 1.0.3 - by Victor Mena.

    It's a library to handle loading/saving of FLI files.
    The original FLI's had only 256 colors in a resolution of 320 x 200 pixels.
    Nowadays the bpp (bits per pixel) can range from 1 to 32 and the
    sizes can range from 1 to 32767 pixels.

    This library can't handle 32 bits bpp (yet).
    The information regarding FLI files i've got is not very good.
    Some details are obscure and I would have implemented 32bits bpp and 4bits
    if i knew how to.

    FLI's with bpp 8 or lower have palettes.
    Before using the library the user needs to init the function to use a FLI.

    The example program 'main.c' uses allegro for graphic displaying.
    The library itself is not bound to allegro or any other hardware.

    The file 'fli.h' is the only needed by the user.
    The other headers are used by the library.
    EGI extensions are not used.

    ---------------------------------------------------------------------
    Graphic formats and the BPP's:

    bpp 1:
        The image pixels are each bit of each byte. There will be eight bits
        on/off for each byte.

    bpp 4:
        Does this bpp exist? or is it defined anywhere? - nope!

    bpp 8:
        One byte is one pixel. Pixels are indexes into a palette.

    bpp 15:
        Two bytes per pixel.
        Storage format:  5 bits for Red, 5 bits for Green, 5 bits for Blue
            Pixels ordered like this: "0rrrrrgg gggbbbbb" (two bytes)
          (RGB, 555)

    bpp 16:
        Two bytes per pixel.
        Storage format:  5 bits for Red, 6 bits for Green, 5 bits for Blue
            Pixels ordered like this: "rrrrrggg gggbbbbb" (two bytes)
          (RGB, 565)


    bpp 24:
                    Three bytes per pixel.
        Storage format: 8 bits for Red, 8 bits for Green, 8 bits for Blue
          (BGR, 888)
          Blue byte, Green Byte, Red byte, and then repeated again.


    bpp 32:
        Four bytes per pixel.
        Storage format:   ??? BGRA or RGBA ?


    ---------------------------------------------------------------------
    Some important FLI structure info:

    Palette changes are only valid when reading frames.
    When writing frames, if the user changes the palette between writes
    then the changes will be written to the file (not implemented very well yet...).
    palette = pointer to palette.

    if    update_palette  is 1 then the palette needs to be read by
    the user, since a change in the palette was read from the file.
    palentry   is the amount of palette entries that changed since last read.
    upd_pal_begin = begin entry in palette to change
    upd_pal_end   = end   entry in palette to change

    image     = pointer to image
    img_begin = vertical offset where the image change begin
    img_end   = vertical offset where the image change ends
    width     = width of image
    height    = height of image
    depth     = bpp of image

    images_to_go = This variable is decreased with each read of a frame.
                   If it is 0 then the user needs to rewind or close the
                   fli structures (no more frames to read).
                   This variable is used only when reading frames.

    read_write =    (0=opened for reading, 1=opened for writing)

    stride     =    bytes per line, calculated for the current bitdepth.
                    This thingy is calculated by the library at the
                    init section.

    errnumber   =   If everything is ok, FERR_OK is returned, else a
                    errornumber is generated. Use the function
                    fli_return_errstring() to convert this number into a string.

    ---------------------------------------------------------------------
    The library don't use any static data, so the user can have multiple
    FLI's open at any time, for reading and writing.

    FUNCTIONS:



    FLI *fli_open_file_read( char *filename, char colormetric,
                int verbose_flag )

    This function allocates a FLI structure as defined in fli.h
    The file is opened for reading frames. The FLI structure is allocated and
    initialized. The code reads in the header (128 bytes).
    After the function returns the user can find out the bpp of the fli file.
    Buffer for image will be allocated.
    Buffer for palette will be allocated if bpp is 8 or less.
    About colormetric: The library will convert the readed or written palettes
    to the selected range, even if the color chunks read is of other range.
    If the FLI structure returned is NULL then a memory allocation error ocurred.
    The errornumber is in the 'errnumber' member of the FLI structure.


    filename:        A name to a fli file
    colormetric is:  0 = paletted rgb range 0-63  (VGA)
                     1 = paletted rgb range 0-255
    verbose_flag:    0 = no textual output
                     1 = output will be written to standard output
    Returns: Pointer to Allocated FLI structure
             Returns NULL on error





    FLI *fli_read_frame( FLI *fli )

    Read a frame.
    The user must read the FLI structure to use the image and palette.
    The returned structure is the same as input. Returns NULL on error.
    After each read the user must copy the image from the pointer
    given in the FLI structure, the same with the palette.
    The errornumber is in the 'errnumber' member of the FLI structure.



    FLI *fli_rewind( FLI *f )

    Rewind to first frame. Does not read any frame.
    Only used when reading frames.
    The returned structure is the same as input. Returns NULL on error.



    FLI *fli_open_file_write( char *filename, char bpp, int sx, int sy,
                              char colormetric ,int verbose_flag )

    open a new FLI for writing, creating a new file and writing a FLx header.
    After the function returns, a header will be written.
    About colormetric: The library will convert the readed or written palettes
    to the selected range, even if the color chunks read is of other range.
    If the FLI structure returned is NULL then a memory allocation error ocurred.
    The errornumber is in the 'errnumber' member of the FLI structure.

    Input:
        Filename = name of output file
             bpp = bit per plane (1/4/8/15/16/24/32) - not yet 32 bits.
                   bpp 4 is not valid? (don't think it exist)
              sx = size x (not more than 32767)
              sy = size y (not more than 32767)
           image = unsigned char array to image, no padding used
         palette = optional palette, valid for bpp equal or less than 8
    colormetric  = ( 0 = rgb range 0-63 (VGA), 1 = rgb range 0-255 )
    verbose_flag = ( 0=quiet, 1=verbose )

    Output: Pointer to Allocated FLI structure
            Buffer for image will be allocated.
            Buffer for palette will be allocated if bpp is 8 or less.
            Returns NULL on error;
            Initially the offset to first and second images are equal.




    FLI *fli_write_frame( FLI *f )

    Write a frame.
    The user must read the FLI structure to use the image and palette.
    After each write the user must copy his own image to the pointer
    given in the FLI structure, the same with the palette.
    The returned structure is the same as input.
    The errornumber is in the 'errnumber' member of the FLI structure.


    void fli_close( FLI *f )

    Close and deallocate FLI structure.
    Free image buffer.
    Free palette if pointer is not NULL.



    char *fli_return_errstring( FLI *f )

    makes a error number into a string.
    The errornumber is in the 'errnumber' member of the FLI structure.
    This number should be checked to see if is not FERR_OK, then some
    error ocurred.

    ---------------------------------------------------------------------

