home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 262.lha / IffLibrary_v1.3 / iff.doc < prev    next >
Text File  |  1989-07-04  |  9KB  |  267 lines
  1.           Documentation for iff.library
  2.  
  3.           Software written and distributed by:
  4.  
  5.             Robert W. Albrecht Jr.
  6.             1457 Zion Way
  7.             Ventura, CA 93003
  8.  
  9.          iff.library Version 1.3 (public domain)
  10.  
  11.       This is crippled version of "iff.library" that can be used by your
  12.    C program to load IFF images. If you want the full featured version of
  13.    iff.library send $20 to the above address with your name and address.
  14.    This software is in the public domain and may not be sold or distributed
  15.    with commercial software. Version 2 of iff.library may be distributed with
  16.    commercial software with no royalties for the $20 license fee.
  17.  
  18.  
  19.           Two Example Programs Included
  20.  
  21.    Both of the programs have the same command syntax and they must
  22.    be executed from the CLI:
  23.  
  24.    ??? <IFF file name>
  25.  
  26.    ShoPict displays almost any IFF image on a custom screen by loading the
  27.    IFF image directly into the BitMap of the custom screen. ShoPict will
  28.    now print the currently loaded picture if you press the 'P' key.
  29.    ShoPict was modified to handle over scan pictures.
  30.  
  31.    ShoImg allocates and loads an Image structure from an IFF file and
  32.    displays it on the screen. Iff.library does the memory managment.
  33.  
  34.  
  35.           Setting up to use iff.library
  36.  
  37.       Iff.library is accessed through a set of assembly language connection
  38.    routines. The assembly source to these routines is provided in the
  39.    file "iff.asm". You will need to assemble iff.asm unless you have
  40.    Aztec C 3.6A (or compatable) for which there is a ".o" file. Once
  41.    iff.asm is assembled you will have to link it with your program. You
  42.    will also have to copy iff.library to the libs: directory on your system
  43.    disk. There is now an Amiga.lib compatable iff.o called iff.ami.
  44.  
  45.    In your program you will have to:
  46.  
  47.    1) Include the proper header file.
  48.  
  49.    #include "ifflib.h"
  50.  
  51.    2) Declare a global library base pointer;
  52.  
  53.    void *IFFBase;
  54.  
  55.    3) Open iff.library.
  56.  
  57.    if( !(IFFBase = OpenLibrary(IFFNAME,1L)) )
  58.       /* abort */
  59.  
  60.    Now you are ready to call the functions in iff.library.
  61.  
  62.  
  63.              Description of Functions
  64.  
  65.    ------------------------------------------------------------------
  66.    name:       IFFalloc
  67.  
  68.    synopsis:   void *IFFalloc(size,type)
  69.            long size;
  70.            unsigned short type;
  71.  
  72.    function:   Allocates and clears a block of memory using the Amiga
  73.            AllocMem function. The size of the block is saved so your
  74.            program doesn't have to remember it.
  75.  
  76.    arguments:  size - The requested size of the block of memory, four
  77.            extra bytes will be added to store the size of the block.
  78.            type - The type of Amiga memory you want to allocate;
  79.               CHIP for "CHIP" memory, FAST for "FAST" memory, and
  80.               DONTCARE if you don't care what type you allocate.
  81.               Note: Graphic images need to be in CHIP memory.
  82.  
  83.    return:     NULL (0L) is returned if the block can't be allocated,
  84.            otherwise a pointer to the allocated block is returned.
  85.  
  86.    see also:   IFFfree
  87.  
  88.    ---------------------------------------------------------------------
  89.    name:       IFFfree
  90.  
  91.    synopsis:   void IFFfree(ptr)
  92.  
  93.    function:   Frees memory allocated by IFFalloc.
  94.  
  95.    argument:   ptr - a pointer to a block of memory obtained from IFFalloc.
  96.  
  97.    return:     None
  98.  
  99.    note:       IFFfree is used to free the colors obtained from GetIFF_image
  100.            or GetIFF_bitmap.
  101.  
  102.    see also:   IFFalloc
  103.  
  104.    ---------------------------------------------------------------------
  105.    name:       GetIFF_bitmap
  106.  
  107.  
  108.    synopsis:   short GetIFF_bitmap(name,bmap,colors,ncolors,allocate)
  109.            char *name;
  110.            struct BitMap **bmap;
  111.            unsigned short **colors;
  112.            unsigned short *ncolors;
  113.            unsigned short allocate;
  114.  
  115.    function:   To load and optionally allocate a BitMap and colors from
  116.            an IFF file.
  117.  
  118.    arguments:  name - A null terminated string containing the name of the
  119.            iff IFF file to load.
  120.            bmap - A pointer to a pointer to a BitMap structure. If
  121.               you decide let this function allocate the structure the
  122.               pointer will be set to the newly allocated BitMap.
  123.            colors - A pointer to an array of color values, one for each
  124.               color. The colors are organized in the native Amiga
  125.               format (RGB 4 bits per gun right justified). If you
  126.               decide to let this function allocate the colors
  127.               the pointer will be set to the newly allocated block.
  128.            ncolors - A pointer to a variable that will be set to the
  129.               number of colors in the IFF file.
  130.            allocate - Set to ALLOC if you want the colors and BitMap
  131.               allocated by this function. Otherwise set to NOALLOC.
  132.  
  133.    return:     Zero is returned if the operation was successful, otherwise
  134.            one of the error codes in ifflib.h is returned.
  135.  
  136.    see also:   RlsBitMap IFFfree
  137.  
  138.    note:       The BitMap structure is defined in graphics/gfx.h
  139.  
  140.    ---------------------------------------------------------------------
  141.    name:       GetIFF_image
  142.  
  143.  
  144.    synopsis:   short GetIFF_image(name,image,colors,ncolors,allocate)
  145.            char *name;
  146.            struct Image **image;
  147.            unsigned short **colors;
  148.            unsigned short *ncolors;
  149.            unsigned short allocate;
  150.  
  151.    function:   To load and optionally allocate a Image and colors from
  152.            an IFF file.
  153.  
  154.    arguments:  name - A null terminated string containing the name of the
  155.            iff IFF file to load.
  156.            image - A pointer to a pointer to an Image structure. If
  157.               you decide let this function allocate the structure the
  158.               pointer will be set to the newly allocated Image.
  159.            colors - A pointer to an array of color values, one for each
  160.               color. The colors are organized in the native Amiga
  161.               format (RGB 4 bits per gun right justified). If you
  162.               decide to let this function allocate the colors
  163.               the pointer will be set to the newly allocated block.
  164.            ncolors - A pointer to a variable that will be set to the
  165.               number of colors in the IFF file.
  166.            allocate - Set to ALLOC if you want the colors and Image
  167.               allocated by this function. Otherwise set to NOALLOC.
  168.  
  169.    return:     Zero is returned if the operation was successful, otherwise
  170.            one of the error codes in ifflib.h is returned.
  171.  
  172.    see also:   RlsImage IFFfree
  173.  
  174.    note:       The Image structure is defined in intuition/intuition.h
  175.  
  176.    ---------------------------------------------------------------------
  177.    name:       QueryIFF
  178.  
  179.    synopsis:   short QueryIFF(name,bmHdr)
  180.            char *name;
  181.            BitMapHeader *bmHdr;
  182.  
  183.    function:   To retrieve information about a image in a IFF file.
  184.  
  185.    arguments:  name - A null terminated string containing the name of
  186.            an IFF file.
  187.            bmHdr - A pointer to a BitMapHeader structure. When this
  188.            function returns the BitMapHeader will be filled with the
  189.            information about the image in the IFF file. In order to
  190.            get the original screen ViewModes from the IFF file, if
  191.            this information is there in the form of a CAMG chunk,
  192.            you must set the bmHdr.viewmodes = GETVIEWMODES. If
  193.            bmHdr.viewmodes field is changed after the call then
  194.            the ViewModes were obtained from the IFF file. You should
  195.            never assume that the ViewModes can be obtained from the
  196.            file because this feature was not supported prior to V1.3
  197.            of IFF.library. Also most IFF files don't contain this
  198.            information.
  199.  
  200.    return:     Zero is returned if the operation was successful, otherwise
  201.            one of the error codes in ifflib.h is returned.
  202.  
  203.    note:       The BitMapHeader structure is defined in ifflib.h
  204.  
  205.    ---------------------------------------------------------------------
  206.    name:       RlsBitMap
  207.  
  208.    synopsis:   void RlsBitMap(bmap)
  209.            struct BitMap *bmap;
  210.  
  211.    function:   Frees the memory allocated for a BitMap structure by
  212.            GetIFF_bitmap. The BitMap structure is allocated in two
  213.            parts, one for the structure itself and one for the bit-
  214.            planes.
  215.  
  216.    argument:   bmap - A pointer to a BitMap structure obtained from
  217.            GetIFF_bitmap.
  218.  
  219.    return:     None
  220.  
  221.    see also:   GetIFF_bitmap
  222.  
  223.    ---------------------------------------------------------------------
  224.    name:       RlsImage
  225.  
  226.    synopsis:   void RlsImage(image)
  227.            struct Image *image;
  228.  
  229.    function:   Frees the memory allocated for a Image structure by
  230.            GetIFF_image. The Image structure is allocated in two
  231.            parts, one for the structure itself and one for the bit-
  232.            planes.
  233.  
  234.    argument:   image - A pointer to a Image structure obtained from
  235.            GetIFF_image.
  236.  
  237.    return:     None
  238.  
  239.    see also:   GetIFF_image
  240.  
  241.    ----------------------------------------------------------------------
  242.  
  243.  
  244.    Revision history:
  245.  
  246.         2/89
  247.    1.0        Initial Revision
  248.  
  249.         5/89
  250.    1.1        Fixed bug in library Expunge routine and added the
  251.         picture printing program. Added a object module that
  252.         is compatable with Alink.
  253.  
  254.         5/89
  255.    1.2        Made de-compression routine much faster by coding it
  256.         in assembly language. Also reduced size. (4044 to 3776)
  257.  
  258.         6/89
  259.    1.3        Modified iff.library such that the original screen ViewModes
  260.         will be saved into the BitMapHeader structure if they are
  261.         present in the form of a CAMG chunk. Eliminated the PrntPict
  262.         program and allowed the picture to be printed from ShoPict
  263.         if the 'P' key is pressed. Added support for over scan pictures
  264.         in ShoPict.
  265.  
  266.  
  267.