home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 351.lha / iff.library_v1.6 / iff.doc.pp / iff.doc
Text File  |  1990-03-09  |  18KB  |  453 lines
  1.            Documentation for iff.library V1.6
  2.  
  3.     Copyright (C) 1989 by Robert W. Albrecht, All Rights Reserved.
  4.  
  5.           Software written and distributed by:
  6.  
  7.             Robert W. Albrecht Jr.
  8.             1457 Zion Way
  9.             Ventura, CA 93003
  10.  
  11.  
  12.       iff.library Version 1.6 (Shareware Version)
  13.  
  14.    This is shareware. Iff.library 1.6 will load iff pictures but it will
  15.    not save them. If you wish to distribute iff.library with your
  16.    application please send twenty bucks to the above address and you will
  17.    get a fully functional iff.library and a license to distribute
  18.    iff.library with your commercial applications. There are no royalties.
  19.    The documentation for the PutIFF functions is included to show you
  20.    what you will get for the $20.00 license fee, they are not included
  21.    in this release.
  22.  
  23.  
  24.            Contents of this release
  25.  
  26.    iff.doc         -    This documantation
  27.    readme         -    Listing of contents
  28.    shoimg         -    Load and display an Intuition Image
  29.    shoimg.c         -    Source to above
  30.    shopict         -    Load a picture directly into the screen's bitmap
  31.    shopict.c         -    Source to above
  32.    shopict.man         -    Manual for ShoPict
  33.    printer.c         -    Source to printer device handler
  34.    putproject.c      -    Source for icon saving routine
  35.    faces.c         -    ShoPict icon images
  36.    makefile         -    Aztec 5.0A makefile for example programs and iff.o
  37.    ifflib.h         -    Header file for application programs
  38.    iff.asm         -    68000 assembly source for connection routines
  39.    iff.o         -    Aztec 5.0A compatable object from iff.asm
  40.    iff.library         -    V1.6 library to put in the libs: directory
  41.  
  42.         Two Example Programs Included (with source)
  43.  
  44.    The ShoImg program has this syntax...
  45.  
  46.    ShoImg <IFF file name>
  47.  
  48.    It allocates and loads an Image structure from an IFF file and
  49.    displays it on the screen. Iff.library does the memory managment.
  50.  
  51.    ShoPict displays almost any IFF image on a custom screen by loading the
  52.    IFF image directly into the BitMap of the custom screen. ShoPict will
  53.    now print the currently loaded picture if you press the 'P' key.
  54.    ShoPict was modified to handle over scan pictures. ShoPict will now
  55.    save an IFF image to the file "ram:temp.pic" if you press the 'S' key.
  56.    It will also write an icon if you press the 'I' key.  For more
  57.    information see the ShoPict.man file.
  58.  
  59.    ----------------------------------------------------------------------
  60.  
  61.           Setting up to use iff.library
  62.  
  63.       Iff.library is accessed through a set of assembly language connection
  64.    routines. The assembly source to these routines is provided in the
  65.    file "iff.asm". You will need to assemble iff.asm unless you have
  66.    Aztec C 5.0A (or compatable) for which there is a ".o" file. Once
  67.    iff.asm is assembled you will have to link it with your program. You
  68.    will also have to copy iff.library to the libs: directory on your system
  69.    disk. There is now an Amiga.lib compatable iff.o called iff.ami.
  70.  
  71.    The version number for iff.library version 1.6 is 1, and is defined in
  72.    ifflib.h as IFFVERSION. The crippled version of iff.library (version
  73.    1.6) does not contain the functions: PutIFF, PutIFF_screen, and
  74.    PutIFF_window. If you specify a number less than 2 in the OpenLibrary
  75.    version number you should not expect to use these functions. If the
  76.    user has a version of iff.library that is less than version 2.0 and you
  77.    try to call one of the version 2.0 or above functions, very bad things
  78.    will happen (they will probably see the guru.)
  79.  
  80.    In your program you will have to:
  81.  
  82.    1) Include the proper header file.
  83.  
  84.    #include "ifflib.h"
  85.  
  86.    2) Declare a global library base pointer;
  87.  
  88.    void *IFFBase;
  89.  
  90.    3) Open iff.library.
  91.  
  92.    if( !(IFFBase = OpenLibrary(IFFNAME,IFFVERSION)) )
  93.       /* abort */
  94.  
  95.    Now you are ready to call the functions in iff.library.
  96.  
  97.  
  98.              Description of Functions
  99.  
  100.    ------------------------------------------------------------------
  101.    name:       IFFalloc
  102.  
  103.    synopsis:   void *IFFalloc(size,type)
  104.            long size;
  105.            unsigned short type;
  106.  
  107.    function:   Allocates and clears a block of memory using the Amiga
  108.            AllocMem function. The size of the block is saved so your
  109.            program doesn't have to remember it.
  110.  
  111.    arguments:  size - The requested size of the block of memory, four
  112.            extra bytes will be added to store the size of the block.
  113.            type - The type of Amiga memory you want to allocate;
  114.               CHIP for "CHIP" memory, FAST for "FAST" memory, and
  115.               DONTCARE if you don't care what type you allocate.
  116.               Note: Graphic images need to be in CHIP memory.
  117.  
  118.    return:     NULL (0L) is returned if the block can't be allocated,
  119.            otherwise a pointer to the allocated block is returned.
  120.  
  121.    see also:   IFFfree
  122.  
  123.    ---------------------------------------------------------------------
  124.    name:       IFFfree
  125.  
  126.    synopsis:   void IFFfree(ptr)
  127.  
  128.    function:   Frees memory allocated by IFFalloc.
  129.  
  130.    argument:   ptr - a pointer to a block of memory obtained from IFFalloc.
  131.  
  132.    return:     None
  133.  
  134.    note:       IFFfree is used to free the colors obtained from GetIFF_image
  135.            or GetIFF_bitmap.
  136.  
  137.    see also:   IFFalloc
  138.  
  139.    ---------------------------------------------------------------------
  140.    name:       GetIFF_bitmap
  141.  
  142.  
  143.    synopsis:   short GetIFF_bitmap(name,bmap,colors,ncolors,allocate)
  144.            char *name;
  145.            struct BitMap **bmap;
  146.            unsigned short **colors;
  147.            unsigned short *ncolors;
  148.            unsigned short allocate;
  149.  
  150.    function:   To load and optionally allocate a BitMap and colors from
  151.            an IFF file.
  152.  
  153.    arguments:  name - A null terminated string containing the name of the
  154.            iff IFF file to load.
  155.            bmap - A pointer to a pointer to a BitMap structure. If
  156.               you decide let this function allocate the structure the
  157.               pointer will be set to the newly allocated BitMap.
  158.            colors - A pointer to an array of color values, one for each
  159.               color. The colors are organized in the native Amiga
  160.               format (RGB 4 bits per gun right justified). If you
  161.               decide to let this function allocate the colors
  162.               the pointer will be set to the newly allocated block.
  163.            ncolors - A pointer to a variable that will be set to the
  164.               number of colors in the IFF file.
  165.            allocate - Set to ALLOC if you want the colors and BitMap
  166.               allocated by this function. Otherwise set to NOALLOC.
  167.  
  168.    return:     Zero is returned if the operation was successful, otherwise
  169.            one of the error codes in ifflib.h is returned.
  170.  
  171.    see also:   RlsBitMap IFFfree
  172.  
  173.    note:       The BitMap structure is defined in graphics/gfx.h
  174.  
  175.    ---------------------------------------------------------------------
  176.    name:       GetIFF_image
  177.  
  178.  
  179.    synopsis:   short GetIFF_image(name,image,colors,ncolors,allocate)
  180.            char *name;
  181.            struct Image **image;
  182.            unsigned short **colors;
  183.            unsigned short *ncolors;
  184.            unsigned short allocate;
  185.  
  186.    function:   To load and optionally allocate a Image and colors from
  187.            an IFF file.
  188.  
  189.    arguments:  name - A null terminated string containing the name of the
  190.            iff IFF file to load.
  191.            image - A pointer to a pointer to an Image structure. If
  192.               you decide let this function allocate the structure the
  193.               pointer will be set to the newly allocated Image.
  194.            colors - A pointer to an array of color values, one for each
  195.               color. The colors are organized in the native Amiga
  196.               format (RGB 4 bits per gun right justified). If you
  197.               decide to let this function allocate the colors
  198.               the pointer will be set to the newly allocated block.
  199.            ncolors - A pointer to a variable that will be set to the
  200.               number of colors in the IFF file.
  201.            allocate - Set to ALLOC if you want the colors and Image
  202.               allocated by this function. Otherwise set to NOALLOC.
  203.  
  204.    return:     Zero is returned if the operation was successful, otherwise
  205.            one of the error codes in ifflib.h is returned.
  206.  
  207.    see also:   RlsImage IFFfree
  208.  
  209.    note:       The Image structure is defined in intuition/intuition.h
  210.  
  211.    ---------------------------------------------------------------------
  212.    name:       PutIFF
  213.  
  214.    synopsis:   short PutIFF(name,bm,vp,cm)
  215.            char *name;
  216.            struct BitMap *bm;
  217.            struct ViewPort *vp;
  218.            struct ColorMap *cm;
  219.  
  220.    function:   To save a graphics image to an IFF picture file. The image
  221.            data is compressed while it is being saved to the file.
  222.  
  223.    arguments:  name - A null terminated string containing the name of the
  224.            file to save the IFF picture to.
  225.            bm - A pointer the the BitMap structure where the image data
  226.            for this file is located.
  227.            vp - A pointer to the ViewPort structure for this display.
  228.            The view port structure is used because the "view modes"
  229.            (LACE,HAM,HIRES etc.) are stored there, and this function
  230.            will save that information in an IFF CAMG chunk.
  231.            cm - A pointer to a ColorMap structure where the colors
  232.            for this image are stored. The colors for each picture are
  233.            stored in the file.
  234.  
  235.    return:     Zero is returned if the operation was successful, otherwise
  236.            one of the error codes in ifflib.h is returned.
  237.  
  238.    note:       The BitMap structure is defined in "graphics/gfx.h".
  239.            The ViewPort and ColorMap structures are defined in
  240.            "graphics/view.h"
  241.  
  242.    --------------------------------------------------------------------
  243.  
  244.    name:       PutIFF_screen
  245.  
  246.    synopsis:   short PutIFF_screen(name,screen)
  247.            char *name;
  248.            struct Screen *screen;
  249.  
  250.    function:   Saves the image from an Intuition Screen to the named file.
  251.            This function is simply for convienence, since all it does is
  252.            call PutIFF with the correct arguments for a Screen.
  253.  
  254.    argument:   screen - a pointer to an Intuition Screen structure.
  255.  
  256.    return:     Zero is returned if the operation was successful, otherwise
  257.            one of the error codes in ifflib.h is returned.
  258.  
  259.    note:       The Screen structure is defined in "intuition/intuition.h".
  260.  
  261.    ---------------------------------------------------------------------
  262.  
  263.    name:       PutIFF_window
  264.  
  265.    synopsis:   short PutIFF_window(name,window)
  266.            char *name;
  267.            struct Window *window;
  268.  
  269.    function:   Saves the image from an Intuition Window to the named file.
  270.            This function is simply for convienence, since all it does is
  271.            call PutIFF with the correct arguments for a Window.
  272.  
  273.    return:     Zero is returned if the operation was successful, otherwise
  274.            one of the error codes in ifflib.h is returned.
  275.  
  276.    note:       The Window structure is defined in "intuition/intuition.h".
  277.  
  278.    ---------------------------------------------------------------------
  279.    name:       QueryIFF
  280.  
  281.    synopsis:   short QueryIFF(name,bmHdr)
  282.            char *name;
  283.            BitMapHeader *bmHdr;
  284.  
  285.    function:   To retrieve information about a image in a IFF file.
  286.  
  287.    arguments:  name - A null terminated string containing the name of
  288.            an IFF file.
  289.            bmHdr - A pointer to a BitMapHeader structure. When this
  290.            function returns the BitMapHeader will be filled with the
  291.            information about the image in the IFF file. In order to
  292.            get the original screen ViewModes from the IFF file, if
  293.            this information is there in the form of a CAMG chunk,
  294.            you must set the bmHdr.viewmodes = GETVIEWMODES. If
  295.            bmHdr.viewmodes field is changed after the call then
  296.            the ViewModes were obtained from the IFF file. You should
  297.            never assume that the ViewModes can be obtained from the
  298.            file because this feature was not supported prior to V1.3
  299.            of IFF.library. Also most IFF files don't contain this
  300.            information.
  301.  
  302.    return:     Zero is returned if the operation was successful, otherwise
  303.            one of the error codes in ifflib.h is returned.
  304.  
  305.    note:       The BitMapHeader structure is defined in ifflib.h
  306.  
  307.    ---------------------------------------------------------------------
  308.    name:       RlsBitMap
  309.  
  310.    synopsis:   void RlsBitMap(bmap)
  311.            struct BitMap *bmap;
  312.  
  313.    function:   Frees the memory allocated for a BitMap structure by
  314.            GetIFF_bitmap. The BitMap structure is allocated in two
  315.            parts, one for the structure itself and one for the bit-
  316.            planes.
  317.  
  318.    argument:   bmap - A pointer to a BitMap structure obtained from
  319.            GetIFF_bitmap.
  320.  
  321.    return:     None
  322.  
  323.    see also:   GetIFF_bitmap
  324.  
  325.    ---------------------------------------------------------------------
  326.    name:       RlsImage
  327.  
  328.    synopsis:   void RlsImage(image)
  329.            struct Image *image;
  330.  
  331.    function:   Frees the memory allocated for a Image structure by
  332.            GetIFF_image. The Image structure is allocated in two
  333.            parts, one for the structure itself and one for the bit-
  334.            planes.
  335.  
  336.    argument:   image - A pointer to a Image structure obtained from
  337.            GetIFF_image.
  338.  
  339.    return:     None
  340.  
  341.    see also:   GetIFF_image
  342.  
  343.    ----------------------------------------------------------------------
  344.  
  345.    Revision history:
  346.  
  347.         2/89
  348.    1.0        Initial Revision
  349.  
  350.         5/89
  351.    1.1        Fixed bug in library Expunge routine and added the
  352.         picture printing program. Added a object module that
  353.         is compatable with Alink.
  354.  
  355.         5/89
  356.    1.2        Made de-compression routine much faster by coding it
  357.         in assembly language.
  358.  
  359.         6/89
  360.    1.3        Modified iff.library such that the original screen ViewModes
  361.         will be saved into the BitMapHeader structure if they are
  362.         present in the form of a CAMG chunk. Eliminated the PrntPict
  363.         program and allowed the picture to be printed from ShoPict
  364.         if the 'P' key is pressed. Added support for over scan pictures
  365.         in ShoPict.
  366.  
  367.         8/89
  368.    1.4        Added a picture save feature to the ShoPict program that saves
  369.         the picture when the 'S' key is pressed, and made the mouse
  370.         pointer change when a picture is being saved or printed. When
  371.         the 'S' key is pressed the picture will be saved to the file
  372.         ram:temp.pic. Cleaned up the iff.asm file such that is uses a
  373.         macro.
  374.  
  375.         10/89
  376.    1.5        Added a feature to ShoPict where you can press the 'I' key and
  377.         an icon for the picture will be saved. Also added wild-card
  378.         and workbench support. Got it working with CClib.library,
  379.         saving much in memory.
  380.  
  381.         2/90
  382.    1.6        Adapted to Aztec C 5.0. Changed ifflib.h header file to include
  383.         function prototypes and re-compiled library. Still 100%
  384.         compatable with iff.library 2.5 and below, but it's 200
  385.         bytes bigger.
  386.  
  387.    ---------------------------------------------------------------------
  388.  
  389.                 LICENSE
  390.  
  391.       Robert W. Albrecht is the exclusive owner of the enclosed Software
  392.       and Documentation. You are granted non-exclusive license to use the
  393.       Software and Documentation, but you are not the owner of them.
  394.      Your right to use the Software and Documentation under this
  395.       agreement is the "License". "You" means the individual or legal
  396.       entity whose agent receives this software and accepts this Agreement.
  397.       "Software" means the computer program recorded on the floppy-disk or
  398.       other media, any update to them Robert W. Albrecht may later provide
  399.       you, and any back-up copies made. "Documentation" means the user
  400.       manual and other materials packaged with this Software.
  401.  
  402.                 Transfer
  403.  
  404.       You may may transfer the license for the use of the Software or
  405.       Documentation to another person.
  406.  
  407.               Backup Copies
  408.  
  409.          Make as many copies as you want.
  410.  
  411.                   Term
  412.  
  413.       The license is effective for twenty (20) years from the time you
  414.       receive the software. You may terminate the license at any time by
  415.       returning all software and documentation.
  416.  
  417.             Robert W. Albrecht's rights.
  418.  
  419.       The iff.library Software and Documentation is protected by copyright,
  420.       trade secret and trademark laws. You may not disclose the Software or
  421.       Documentation to others, except as allowed in this license agreement,
  422.       or remove or alter ownership, trademark and copyright notices on
  423.       Documentation or Software. YOU MUST MAKE A GOOD FAITH EFFORT TO
  424.       PREVENT ANY UNAUTHORIZED USE, COPYING, OR DISCLOSURE OF THE SOFTWARE
  425.       OR DOCUMENTATION. THESE OBLIGATIONS WILL SURVIVE ANY TERMINATION OF
  426.       THE LICENSE AGREEMENT.
  427.  
  428.  
  429.          Disclaimer of other Warranties, and Liabilities.
  430.  
  431.       THERE ARE NO WARRANTIES, EITHER EXPRESSED OR IMPLIED, FOR THE
  432.       SOFTWARE OR DOCUMENTATION, WHICH ARE BOTH LICENSED TO YOU "AS IS".
  433.       ROBERT W. ALBRECHT EXPRESSLY DISCLAIMS ANY WARRANTY AS TO THE
  434.       PERFORMANCE OF THE SOFTWARE, OR DOCUMENTATION. HE ALSO DISCLAIMS ALL
  435.       OTHER WARRANTIES, INCLUDING (WITHOUT LIMITATION) IMPLIED WARRANTIES
  436.       OF MERCANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
  437.       SHALL ANYONE INVOLVED IN THE CREATION, PRODUCTION, OR DISTRIBUTION,
  438.       OF THE SOFTWARE OR DOCUMENTATION BE LIABLE FOR ANY INDIRECT, SPECIAL,
  439.       INCEDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OF THE
  440.       SOFTWARE OR DOCUMENTATION OR ARISING FROM ANY BREACH OF ANY WARRANTY.
  441.       Some states do not allow the exclusion or limitation of implied
  442.       warranties or liability for incedental or consequential damages so
  443.       the above exclusion and limitation may not apply to you. IN ADDITON
  444.       TO THE ABOVE LIMITATION, OUR LIABILITY TO YOU OR TO ANYONE ELSE FOR
  445.       DAMAGES SHALL NOT EXCEED THE LICENSE FEE PAID BY YOU FOR THE SOFTWARE
  446.       AND DOCUMENTATION.
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.