Documentation for iff.library V1.6 Copyright (C) 1989 by Robert W. Albrecht, All Rights Reserved. Software written and distributed by: Robert W. Albrecht Jr. 1457 Zion Way Ventura, CA 93003 iff.library Version 1.6 (Shareware Version) This is shareware. Iff.library 1.6 will load iff pictures but it will not save them. If you wish to distribute iff.library with your application please send twenty bucks to the above address and you will get a fully functional iff.library and a license to distribute iff.library with your commercial applications. There are no royalties. The documentation for the PutIFF functions is included to show you what you will get for the $20.00 license fee, they are not included in this release. Contents of this release iff.doc - This documantation readme - Listing of contents shoimg - Load and display an Intuition Image shoimg.c - Source to above shopict - Load a picture directly into the screen's bitmap shopict.c - Source to above shopict.man - Manual for ShoPict printer.c - Source to printer device handler putproject.c - Source for icon saving routine faces.c - ShoPict icon images makefile - Aztec 5.0A makefile for example programs and iff.o ifflib.h - Header file for application programs iff.asm - 68000 assembly source for connection routines iff.o - Aztec 5.0A compatable object from iff.asm iff.library - V1.6 library to put in the libs: directory Two Example Programs Included (with source) The ShoImg program has this syntax... ShoImg It allocates and loads an Image structure from an IFF file and displays it on the screen. Iff.library does the memory managment. ShoPict displays almost any IFF image on a custom screen by loading the IFF image directly into the BitMap of the custom screen. ShoPict will now print the currently loaded picture if you press the 'P' key. ShoPict was modified to handle over scan pictures. ShoPict will now save an IFF image to the file "ram:temp.pic" if you press the 'S' key. It will also write an icon if you press the 'I' key. For more information see the ShoPict.man file. ---------------------------------------------------------------------- Setting up to use iff.library Iff.library is accessed through a set of assembly language connection routines. The assembly source to these routines is provided in the file "iff.asm". You will need to assemble iff.asm unless you have Aztec C 5.0A (or compatable) for which there is a ".o" file. Once iff.asm is assembled you will have to link it with your program. You will also have to copy iff.library to the libs: directory on your system disk. There is now an Amiga.lib compatable iff.o called iff.ami. The version number for iff.library version 1.6 is 1, and is defined in ifflib.h as IFFVERSION. The crippled version of iff.library (version 1.6) does not contain the functions: PutIFF, PutIFF_screen, and PutIFF_window. If you specify a number less than 2 in the OpenLibrary version number you should not expect to use these functions. If the user has a version of iff.library that is less than version 2.0 and you try to call one of the version 2.0 or above functions, very bad things will happen (they will probably see the guru.) In your program you will have to: 1) Include the proper header file. #include "ifflib.h" 2) Declare a global library base pointer; void *IFFBase; 3) Open iff.library. if( !(IFFBase = OpenLibrary(IFFNAME,IFFVERSION)) ) /* abort */ Now you are ready to call the functions in iff.library. Description of Functions ------------------------------------------------------------------ name: IFFalloc synopsis: void *IFFalloc(size,type) long size; unsigned short type; function: Allocates and clears a block of memory using the Amiga AllocMem function. The size of the block is saved so your program doesn't have to remember it. arguments: size - The requested size of the block of memory, four extra bytes will be added to store the size of the block. type - The type of Amiga memory you want to allocate; CHIP for "CHIP" memory, FAST for "FAST" memory, and DONTCARE if you don't care what type you allocate. Note: Graphic images need to be in CHIP memory. return: NULL (0L) is returned if the block can't be allocated, otherwise a pointer to the allocated block is returned. see also: IFFfree --------------------------------------------------------------------- name: IFFfree synopsis: void IFFfree(ptr) function: Frees memory allocated by IFFalloc. argument: ptr - a pointer to a block of memory obtained from IFFalloc. return: None note: IFFfree is used to free the colors obtained from GetIFF_image or GetIFF_bitmap. see also: IFFalloc --------------------------------------------------------------------- name: GetIFF_bitmap synopsis: short GetIFF_bitmap(name,bmap,colors,ncolors,allocate) char *name; struct BitMap **bmap; unsigned short **colors; unsigned short *ncolors; unsigned short allocate; function: To load and optionally allocate a BitMap and colors from an IFF file. arguments: name - A null terminated string containing the name of the iff IFF file to load. bmap - A pointer to a pointer to a BitMap structure. If you decide let this function allocate the structure the pointer will be set to the newly allocated BitMap. colors - A pointer to an array of color values, one for each color. The colors are organized in the native Amiga format (RGB 4 bits per gun right justified). If you decide to let this function allocate the colors the pointer will be set to the newly allocated block. ncolors - A pointer to a variable that will be set to the number of colors in the IFF file. allocate - Set to ALLOC if you want the colors and BitMap allocated by this function. Otherwise set to NOALLOC. return: Zero is returned if the operation was successful, otherwise one of the error codes in ifflib.h is returned. see also: RlsBitMap IFFfree note: The BitMap structure is defined in graphics/gfx.h --------------------------------------------------------------------- name: GetIFF_image synopsis: short GetIFF_image(name,image,colors,ncolors,allocate) char *name; struct Image **image; unsigned short **colors; unsigned short *ncolors; unsigned short allocate; function: To load and optionally allocate a Image and colors from an IFF file. arguments: name - A null terminated string containing the name of the iff IFF file to load. image - A pointer to a pointer to an Image structure. If you decide let this function allocate the structure the pointer will be set to the newly allocated Image. colors - A pointer to an array of color values, one for each color. The colors are organized in the native Amiga format (RGB 4 bits per gun right justified). If you decide to let this function allocate the colors the pointer will be set to the newly allocated block. ncolors - A pointer to a variable that will be set to the number of colors in the IFF file. allocate - Set to ALLOC if you want the colors and Image allocated by this function. Otherwise set to NOALLOC. return: Zero is returned if the operation was successful, otherwise one of the error codes in ifflib.h is returned. see also: RlsImage IFFfree note: The Image structure is defined in intuition/intuition.h --------------------------------------------------------------------- name: PutIFF synopsis: short PutIFF(name,bm,vp,cm) char *name; struct BitMap *bm; struct ViewPort *vp; struct ColorMap *cm; function: To save a graphics image to an IFF picture file. The image data is compressed while it is being saved to the file. arguments: name - A null terminated string containing the name of the file to save the IFF picture to. bm - A pointer the the BitMap structure where the image data for this file is located. vp - A pointer to the ViewPort structure for this display. The view port structure is used because the "view modes" (LACE,HAM,HIRES etc.) are stored there, and this function will save that information in an IFF CAMG chunk. cm - A pointer to a ColorMap structure where the colors for this image are stored. The colors for each picture are stored in the file. return: Zero is returned if the operation was successful, otherwise one of the error codes in ifflib.h is returned. note: The BitMap structure is defined in "graphics/gfx.h". The ViewPort and ColorMap structures are defined in "graphics/view.h" -------------------------------------------------------------------- name: PutIFF_screen synopsis: short PutIFF_screen(name,screen) char *name; struct Screen *screen; function: Saves the image from an Intuition Screen to the named file. This function is simply for convienence, since all it does is call PutIFF with the correct arguments for a Screen. argument: screen - a pointer to an Intuition Screen structure. return: Zero is returned if the operation was successful, otherwise one of the error codes in ifflib.h is returned. note: The Screen structure is defined in "intuition/intuition.h". --------------------------------------------------------------------- name: PutIFF_window synopsis: short PutIFF_window(name,window) char *name; struct Window *window; function: Saves the image from an Intuition Window to the named file. This function is simply for convienence, since all it does is call PutIFF with the correct arguments for a Window. return: Zero is returned if the operation was successful, otherwise one of the error codes in ifflib.h is returned. note: The Window structure is defined in "intuition/intuition.h". --------------------------------------------------------------------- name: QueryIFF synopsis: short QueryIFF(name,bmHdr) char *name; BitMapHeader *bmHdr; function: To retrieve information about a image in a IFF file. arguments: name - A null terminated string containing the name of an IFF file. bmHdr - A pointer to a BitMapHeader structure. When this function returns the BitMapHeader will be filled with the information about the image in the IFF file. In order to get the original screen ViewModes from the IFF file, if this information is there in the form of a CAMG chunk, you must set the bmHdr.viewmodes = GETVIEWMODES. If bmHdr.viewmodes field is changed after the call then the ViewModes were obtained from the IFF file. You should never assume that the ViewModes can be obtained from the file because this feature was not supported prior to V1.3 of IFF.library. Also most IFF files don't contain this information. return: Zero is returned if the operation was successful, otherwise one of the error codes in ifflib.h is returned. note: The BitMapHeader structure is defined in ifflib.h --------------------------------------------------------------------- name: RlsBitMap synopsis: void RlsBitMap(bmap) struct BitMap *bmap; function: Frees the memory allocated for a BitMap structure by GetIFF_bitmap. The BitMap structure is allocated in two parts, one for the structure itself and one for the bit- planes. argument: bmap - A pointer to a BitMap structure obtained from GetIFF_bitmap. return: None see also: GetIFF_bitmap --------------------------------------------------------------------- name: RlsImage synopsis: void RlsImage(image) struct Image *image; function: Frees the memory allocated for a Image structure by GetIFF_image. The Image structure is allocated in two parts, one for the structure itself and one for the bit- planes. argument: image - A pointer to a Image structure obtained from GetIFF_image. return: None see also: GetIFF_image ---------------------------------------------------------------------- Revision history: 2/89 1.0 Initial Revision 5/89 1.1 Fixed bug in library Expunge routine and added the picture printing program. Added a object module that is compatable with Alink. 5/89 1.2 Made de-compression routine much faster by coding it in assembly language. 6/89 1.3 Modified iff.library such that the original screen ViewModes will be saved into the BitMapHeader structure if they are present in the form of a CAMG chunk. Eliminated the PrntPict program and allowed the picture to be printed from ShoPict if the 'P' key is pressed. Added support for over scan pictures in ShoPict. 8/89 1.4 Added a picture save feature to the ShoPict program that saves the picture when the 'S' key is pressed, and made the mouse pointer change when a picture is being saved or printed. When the 'S' key is pressed the picture will be saved to the file ram:temp.pic. Cleaned up the iff.asm file such that is uses a macro. 10/89 1.5 Added a feature to ShoPict where you can press the 'I' key and an icon for the picture will be saved. Also added wild-card and workbench support. Got it working with CClib.library, saving much in memory. 2/90 1.6 Adapted to Aztec C 5.0. Changed ifflib.h header file to include function prototypes and re-compiled library. Still 100% compatable with iff.library 2.5 and below, but it's 200 bytes bigger. --------------------------------------------------------------------- LICENSE Robert W. Albrecht is the exclusive owner of the enclosed Software and Documentation. You are granted non-exclusive license to use the Software and Documentation, but you are not the owner of them. Your right to use the Software and Documentation under this agreement is the "License". "You" means the individual or legal entity whose agent receives this software and accepts this Agreement. "Software" means the computer program recorded on the floppy-disk or other media, any update to them Robert W. Albrecht may later provide you, and any back-up copies made. "Documentation" means the user manual and other materials packaged with this Software. Transfer You may may transfer the license for the use of the Software or Documentation to another person. Backup Copies Make as many copies as you want. Term The license is effective for twenty (20) years from the time you receive the software. You may terminate the license at any time by returning all software and documentation. Robert W. Albrecht's rights. The iff.library Software and Documentation is protected by copyright, trade secret and trademark laws. You may not disclose the Software or Documentation to others, except as allowed in this license agreement, or remove or alter ownership, trademark and copyright notices on Documentation or Software. YOU MUST MAKE A GOOD FAITH EFFORT TO PREVENT ANY UNAUTHORIZED USE, COPYING, OR DISCLOSURE OF THE SOFTWARE OR DOCUMENTATION. THESE OBLIGATIONS WILL SURVIVE ANY TERMINATION OF THE LICENSE AGREEMENT. Disclaimer of other Warranties, and Liabilities. THERE ARE NO WARRANTIES, EITHER EXPRESSED OR IMPLIED, FOR THE SOFTWARE OR DOCUMENTATION, WHICH ARE BOTH LICENSED TO YOU "AS IS". ROBERT W. ALBRECHT EXPRESSLY DISCLAIMS ANY WARRANTY AS TO THE PERFORMANCE OF THE SOFTWARE, OR DOCUMENTATION. HE ALSO DISCLAIMS ALL OTHER WARRANTIES, INCLUDING (WITHOUT LIMITATION) IMPLIED WARRANTIES OF MERCANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL ANYONE INVOLVED IN THE CREATION, PRODUCTION, OR DISTRIBUTION, OF THE SOFTWARE OR DOCUMENTATION BE LIABLE FOR ANY INDIRECT, SPECIAL, INCEDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OF THE SOFTWARE OR DOCUMENTATION OR ARISING FROM ANY BREACH OF ANY WARRANTY. Some states do not allow the exclusion or limitation of implied warranties or liability for incedental or consequential damages so the above exclusion and limitation may not apply to you. IN ADDITON TO THE ABOVE LIMITATION, OUR LIABILITY TO YOU OR TO ANYONE ELSE FOR DAMAGES SHALL NOT EXCEED THE LICENSE FEE PAID BY YOU FOR THE SOFTWARE AND DOCUMENTATION.