THE UNIVERSAL IFF LIBRARY FOR THE AMIGA BY CHRISTIAN A. WEBER, ZURICH/SWITZERLAND THIS PROGRAM IS IN THE PUBLIC DOMAIN. IT MAY BE FREELY DISTRUBUTED, COPIED AND USED FOR COMMERCIAL OR NON-COMMERCIAL PURPOSES. IT MAY BE DISTRIBUTED WITH OR WITHOUT THIS DOCUMENTATION FILE. TO MAINTAIN COMPATIBILITY, YOU SHOULD NOT MAKE ANY CHANGES ON THE LIBRARY ITSELF. UPDATES WILL BE RELEASED BY THE AUTHOR. OVERVIEW OF THE LIBRARY FUNCTIONS (Version 15.3) ------------------------------------------------ Name Offset Description OpenIFF -30 Allocate memory for an IFF-file and load it CloseIFF -36 Finish access to an IFF-file and deallocate memory FindChunk -42 Find a specific chunk in an IFF file GetBMHD -48 Find the BitMapHeader of an ILBM file GetColorTab -54 Find CMAP chunk, convert it to an Amiga ColorTable DecodePic -60 Decode the BODY of an ILBM file into a BitMap SaveBitMap -66 Save the contents of a BitMap as an IFF-file SaveClip -72 Save a part of a BitMap as an IFF-file IffError -78 Get detailed error descrpition if a routine fails GetViewModes -84 Get the Amiga-specific ViewModes-Word (to be continued) DETAILED DESCRIPTION OF THE LIBRARY FUNCTIONS --------------------------------------------- (This documentation was translated from German to English in half an hour, so please be tolerant!) IFF/OpenIFF IFF/OpenIFF NAME OpenIFF -- allocate memory for an IFF-file and read it SYNOPSIS ifffile = OpenIFF(filename) D0 A0 OFFSET -30 FUNCTION This function opens a file on a disk and looks whether it's an IFF file or not. If it is an IFF file, memory is allocated and the file is read into memory. If the file is of the type '8SVX', it will be loaded into CHIP memory. If an error occurs, 0 is returned, and you can call IffError() to get the error number. INPUTS filename - Pointer to a null-terminated string RESULT ifffile - 'FileHandle', points to the beginning of the IFF file ("FORM...."), 0 if unsuccessful. SEE ALSO CloseIFF BUGS None IFF/CloseIFF IFF/CloseIFF NAME CloseIFF -- finish access to an IFF-file and deallocate memory SYNOPSIS CloseIFF(ifffile) A1 OFFSET -36 FUNCTION Returns the memory previously allocated by OpenIFF(). INPUTS ifffile - IFF file pointer, from OpenIFF() RESULT none SEE ALSO OpenIFF BUGS If A1 contains garbage, an 81000005 Guru will visit you... IFF/FindChunk IFF/FindChunk NAME FindChunk -- find an IFF-chunk SYNOPSIS chunk = FindChunk(ifffile,chunkname) D0 A1 D0 OFFSET -42 FUNCTION Find a specific chunk in an IFF file INPUTS ifffile - IFF file pointer, returned by OpenIFF() chunkname - 4 characters packed ASCII ('BODY', 'VHDR' ...) RESULT Pointer to the beginning of the chunk (that means to the chunk name itself, followed by the chunk size), zero if chunk not found SEE ALSO GetBMHD, GetColorTab BUGS none IFF/GetBMHD IFF/GetBMHD NAME GetBMHD -- find a BitMapHeader of an IFF-file SYNOPSIS header = GetBMHD(ifffile) D0 A1 OFFSET -48 FUNCTION Returns a pointer to a 'BitMapHeader' structure as defined in iff.h and iff.i INPUTS ifffile - IFF file pointer, returned by OpenIFF() RESULT Pointer to the BitMapHeader, or 0 if no BMHD chunk found SEE ALSO FindChunk, GetColorTab BUGS none IFF/GetColorTab IFF/GetColorTab NAME GetColorTab -- find a CMAP chunk and convert it to a ColorTable SYNOPSIS count = GetColorTab(ifffile,colortable) D0 A1 A0 OFFSET -54 FUNCTION Searches the CMAP chunk of an IFF file and converts it, if it's there, to an Amiga color table structure. This colortable can directly be used as a parameter for the LoadRGB4() function. INPUTS ifffile - IFF file pointer, returned by OpenIFF() colortable - Pointer to a block of memory which must be large enough to hold the colortable (2 bytes per color) RESULT Number of colors actually found, or zero if the file has no CMAP chunk SEE ALSO FindChunk, GetBMHD BUGS the colortable must be WORD aligned (this isn't really a bug) IFF/DecodePic IFF/DecodePic NAME DecodePic -- decode an IFF-BODY into a BitMap SYNOPSIS bitmap = DecodePic(ifffile,bitmap) D0 A1 A0 OFFSET -60 FUNCTION Decodes and decrunches a picture into the BitMap you supplied. If the picture is larger than your BitMap's planes, it will be truncated. If your BitMap is larger than the picture, the picture will be drawn into the top left corner of your BitMap. If the picture has more planes (colors) than your BitMap, the operation will fail and 0 will be returned. INPUTS ifffile - IFF file pointer, from OpenIFF() bitmap - Pointer to a properly initialized BitMap structure: bm_Planes[] must point to valid BitPlanes, bm_Depth contains the number of planes. bm_Width and bm_Height must be set according to the size of your bit planes. RESULT Non-zero if OK, 0 if error, Call IffError() to know the reason of the failure BUGS The width of the IFF picture (in pixels) must be a multiple of 8 (I've never seen a picture which didn't obey this rule!) IFF/SaveBitMap IFF/SaveBitMap NAME SaveBitMap -- save the planes of a BitMap as an IFF-file SYNOPSIS result = SaveBitMap(filename,bitmap,colortable,flags) D0 A0 A1 A2 D0 OFFSET -66 FUNCTION Save the planes of a BitMap as an IFF-file, optionally with a colortable. The IFF file will contain the following chunks: FORM - The IFF header, with the type ILBM BMHD - The BitMap Header structre CMAP - The color map, this chunk is omitted if colortable is zero CAMG - The Amiga ViewModes word, contains the special ViewModes information (HAM, LACE, HIRES ...) BODY - The (crunched or uncompressed) picture INPUTS filename - Name of the IFF file to create bitmap - Pointer to the BitMap holding your picture colortable - Pointer to an Amiga ColorTable structure or zero (if colortable = 0, no CMAP chunk will be generated). flags - Bit 0: 1 = Use the "CmpByteRun1" compression algorythm, 0 = Save the file uncompressed Bit 7: 1 = This is a HAM (Hold and modify) picture 0 = This is a normal or Extra-Halfbrite picture RESULT Non-zero if successful, 0 if error, Call IffError() to know the reason of the failure SEE ALSO SaveClip IFF/SaveClip IFF/SaveClip NAME SaveClip -- save a part of a BitMap as an IFF-file SYNOPSIS result = SaveClip(filename,bitmap,coltab,flags,xoff,yoff,width,height) D0 A0 A1 A2 D0 D1 D2 D3 D4 OFFSET -72 FUNCTION Save a part of a BitMap as an IFF file INPUTS filename - Name of the IFF file to create bitmap - Pointer to the BitMap holding your picture colortable - Pointer to an Amiga ColorTable structure or zero (if colortable = 0, no CMAP chunk will be generated). flags - Bit 0: 1 = Use the "CmpByteRun1" compression algorythm, 0 = Save the file uncompressed Bit 7: 1 = This is a HAM (Hold and modify) picture 0 = This is a normal or Extra-Halfbrite picture xoff - X offset of the clip to be saved (bytes from the left) yoff - Y offset of the clip to be saved (lines from the top) width - width in bytes of the rectangle height - height in lines of the rectangle RESULT Non-zero if successful, 0 if error, Call IffError() to know the reason of the failure SEE ALSO SaveBitMap BUGS The width of the rectangle will be rounded to WORD boundaries, because DPAINT® wants it! IFF/IffError IFF/IffError NAME IffError -- Get detailed error descrpition SYNOPSIS error = IffError() D0 OFFSET -78 FUNCTION If one of the above functions returns zero, you can call IffError() to know the reason for the failure. An error code is returned, please refer to the files 'iff.h' or 'iff.i' for the complete list of errors! INPUTS none RESULT Error-number generated by the latest function call, or zero if no error Cuurently the following numbers are used: Nr. Symbol Function Description 16 IFF_CANTOPENFILE OpenIFF() File not found 17 IFF_READERROR OpenIFF() Read() returned an error 18 IFF_NOMEM OpenIFF() Not enough memory for the file 19 IFF_NOTIFF OpenIFF() File is not IFF 20 IFF_WRITEERROR SaveBitMap() Cannot write the file 24 IFF_NOILBM DecodePic() IFF file is not an ILBM file 25 IFF_NOBMHD DecodePic() BMHD chunk not found 26 IFF_NOBODY DecodePic() BODY chunk not found 27 IFF_TOOMANYPLANES DecodePic() Picture has more planes than your BitMap 28 IFF_UNKNOWNCOMPRESSION " Unknown compression type -1 IFF_BADTASK A task which did not open the IFF library tried to call IffError(). Since the IFF library is capable of multi-tasking, the error-values are stored for each task separately. SEE ALSO BUGS If you don't close the IFF library at the end of your program (using CloseLibrary()) the error node will not be freed. The same task will then not be able to re-open the iff.library!!! IFF/GetViewModes IFF/GetViewModes NAME GetViewModes -- Get Amiga-specific ViewModes-Word SYNOPSIS viewmodes = GetViewModes(ifffile) D0 A1 OFFSET -84 FUNCTION Searches the IFF file for a 'CAMG' chunk which holds the view modes information. If there is no CAMG chunk, the view modes are calcu- lated using the information in the BitMapHeader structure. You can set the result of GetViewModes() directly into the ns_ViewModes field of a NewScreen structure! INPUTS ifffile - IFF file pointer, returned from OpenIFF() RESULT viewmodes - WORD containing the view modes (HAM, LACE, HIRES ...) SEE ALSO BUGS If the IFF file has no CAMG chunk and 6 bitplanes, the HAM bit will be set. This is not always correct since the picture could be in the Extra Halfbrite mode The file 'ShowIff.c' shows you how to use the IFF library from C.