path: root/Documentation/ifflib.guide

@database "ifflib"
@master "DH1:Programming/IFF-Library/Documentation/ifflib.doc"

@Node Main "ifflib.doc"
    @{" IFFL_CloseIFF() " Link "IFFL_CloseIFF()"}
    @{" IFFL_CompressBlock() " Link "IFFL_CompressBlock()"}
    @{" IFFL_DecodePic() " Link "IFFL_DecodePic()"}
    @{" IFFL_DecompressBlock() " Link "IFFL_DecompressBlock()"}
    @{" IFFL_FindChunk() " Link "IFFL_FindChunk()"}
    @{" IFFL_GetBMHD() " Link "IFFL_GetBMHD()"}
    @{" IFFL_GetColorTab() " Link "IFFL_GetColorTab()"}
    @{" IFFL_GetViewModes() " Link "IFFL_GetViewModes()"}
    @{" IFFL_IFFError() " Link "IFFL_IFFError()"}
    @{" IFFL_ModifyFrame() " Link "IFFL_ModifyFrame()"}
    @{" IFFL_OpenIFF() " Link "IFFL_OpenIFF()"}
    @{" IFFL_PopChunk() " Link "IFFL_PopChunk()"}
    @{" IFFL_PushChunk() " Link "IFFL_PushChunk()"}
    @{" IFFL_SaveBitMap() " Link "IFFL_SaveBitMap()"}
    @{" IFFL_SaveClip() " Link "IFFL_SaveClip()"}
    @{" IFFL_WriteChunkBytes() " Link "IFFL_WriteChunkBytes()"}
    @{" NewOpenIFF() " Link "NewOpenIFF()"}
    @{" OpenIFF() " Link "OpenIFF()"}
@EndNode

@Node "IFFL_CloseIFF()" "iff.library/IFFL_CloseIFF"

@{b}    NAME@{ub}
	IFFL_CloseIFF -- Close an IFF file and deallocate buffers

@{b}    SYNOPSIS@{ub}
	IFFL_CloseIFF( iff )
	               A1

	void IFFL_CloseIFF( IFFL_HANDLE )

@{b}    FUNCTION@{ub}
	Returns the memory previously allocated by @{"IFFL_OpenIFF()" Link "IFFL_OpenIFF()"}.

@{b}    INPUTS@{ub}
	iff - IFF file handle, from @{"IFFL_OpenIFF()" Link "IFFL_OpenIFF()"}

@{b}    RESULTS@{ub}
	For now, always results TRUE (this may change in the future).

@{b}    SEE ALSO@{ub}
	@{"IFFL_OpenIFF()" Link "IFFL_OpenIFF()"}

@EndNode

@Node "IFFL_CompressBlock()" "iff.library/IFFL_CompressBlock"

@{b}    NAME@{ub}
	IFFL_CompressBlock -- Compress a memory block

@{b}    SYNOPSIS@{ub}
	result = IFFL_CompressBlock( source, destination, size, mode )
	                               A0      A1           D0    D1

	ULONG IFFL_CompressBlock( @{"APTR" Link "INCLUDE:exec/types.h/Main" 33}, @{"APTR" Link "INCLUDE:exec/types.h/Main" 33}, ULONG, ULONG )

@{b}    FUNCTION@{ub}
	Compress the memory block using the appropriate compression mode.
	If the compressed data would become longer than the uncompressed,
	an error is returned.

@{b}    INPUTS@{ub}
	source      - Pointer to data to compress
	destination - Target address for compression
	size        - Number of data bytes to compress
	mode        - Compression mode. Currently, the following modes
	              are supported:

	              IFFL_COMPR_NONE     - Vanilla copy
	              IFFL_COMPR_BYTERUN1 - CmpByteRun1 (ILBM BODY data)
	              IFFL_COMPR_FIBDELTA - Fibonacci Delta (8SVX BODY data)

@{b}    RESULTS@{ub}
	Length of compressed data or 0 if an error occurred.
	@{"IFFL_IFFError()" Link "IFFL_IFFError()"} returns IFFL_ERROR_BADCOMPRESSION if you ask for
	an unsupported compression mode.

@{b}   BUGS@{ub}
	In IFFL_COMPR_BYTERUN1, if the compressed data would become longer,
	the buffer will be overwritten, and no error is returned. So be
	sure to supply a destination buffer which is big enough!

@{b}    SEE ALSO@{ub}
	@{"IFFL_DecompressBlock()" Link "IFFL_DecompressBlock()"}

@EndNode

@Node "IFFL_DecodePic()" "iff.library/IFFL_DecodePic"

@{b}    NAME@{ub}
	IFFL_DecodePic -- decode the BODY of an ILBM file into a @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45}

@{b}    SYNOPSIS@{ub}
	success = IFFL_DecodePic( iff, bitmap )
	 D0                       A1   A0

	@{"BOOL" Link "INCLUDE:exec/types.h/Main" 68} IFFL_DecodePic( IFFL_HANDLE, struct @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} * )

@{b}    FUNCTION@{ub}
	Decodes and decompresses a picture into the user supplied @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45}.
	If the picture is higher than your @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45}, it will be truncated.
	If your @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} is larger than the picture, the picture will be
	drawn into the top left corner of your @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45}.
	If the picture has less planes than the @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45}, the unused planes
	are NOT touched by this routine, so you may wish to clear them
	before calling IFFL_DecodePic(). If the picture has more planes
	than your @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45}, the surplus planes of the picture are ignored.

@{b}    INPUTS@{ub}
	iff    - IFF file handle, from @{"IFFL_OpenIFF()" Link "IFFL_OpenIFF()"}
	bitmap - Pointer to a properly initialized @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} 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.

@{b}    RESULTS@{ub}
	Non-zero if successful, zero if error. Call @{"IFFL_IFFError()" Link "IFFL_IFFError()"} to
	know the reason of the failure

@{b}    BUGS@{ub}
	If the picture is wider than your @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45}, one line of innocent
	memory will be overwritten at the end of each bitplane. You can
	avoid this by allocating a few bytes more for each plane.
	Normally, you allocate your @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} after inspecting the BMHD
	chunk, so this should not be a problem.

@{b}    NOTE@{ub}
	This routine needs at least 650 bytes of stack space

@{b}    SEE ALSO@{ub}

@EndNode

@Node "IFFL_DecompressBlock()" "iff.library/IFFL_DecompressBlock"

@{b}    NAME@{ub}
	IFFL_DecompressBlock -- Decompress a memory block

@{b}    SYNOPSIS@{ub}
	result = IFFL_DecompressBlock( source, destination, size, mode )
	                               A0      A1           D0    D1

	ULONG IFFL_DecompressBlock( @{"APTR" Link "INCLUDE:exec/types.h/Main" 33}, @{"APTR" Link "INCLUDE:exec/types.h/Main" 33}, ULONG, ULONG )

@{b}    FUNCTION@{ub}
	Decompress the memory block using the appropriate Decompression mode.
	If the Decompressed data would become longer than the unDecompressed,
	an error is returned.

@{b}    INPUTS@{ub}
	source      - Pointer to data to decompress
	destination - Target address for decompression
	size        - Number of _DECOMPRESSED_ data bytes
	mode        - Compression mode. Currently, the following modes
	              are supported:

	              IFFL_COMPR_NONE     - Vanilla copy
	              IFFL_COMPR_BYTERUN1 - CmpByteRun1 (ILBM BODY data)
	              IFFL_COMPR_FIBDELTA - Fibonacci Delta (8SVX BODY data)

@{b}    RESULTS@{ub}
	Length of uncompressed data or 0 if an error occurred.
	@{"IFFL_IFFError()" Link "IFFL_IFFError()"} returns IFFL_ERROR_BADCOMPRESSION if you ask for
	an unsupported compression mode.

@{b}    SEE ALSO@{ub}
	@{"IFFL_CompressBlock()" Link "IFFL_CompressBlock()"}

@EndNode

@Node "IFFL_FindChunk()" "iff.library/IFFL_FindChunk"

@{b}   NAME@{ub}
	IFFL_FindChunk -- find an IFF-chunk

@{b}   SYNOPSIS@{ub}
	chunk = IFFL_FindChunk( iff, chunkname )
	D0                      A1   D0

	@{"APTR" Link "INCLUDE:exec/types.h/Main" 33} IFFL_FindChunk( IFFL_HANDLE, ULONG )

@{b}   FUNCTION@{ub}
	Find a specific chunk in an IFF file

@{b}   INPUTS@{ub}
	iff       - IFF file handle, from @{"IFFL_OpenIFF()" Link "IFFL_OpenIFF()"}
	chunkname - 4 characters packed ASCII ('BODY', 'VHDR' ...)
	            if chunkname is 0, FindChunk() returns a pointer to the
	            first byte after the end of the current FORM. This can
	            be used by ANIM readers for jumping from FORM to FORM.

@{b}   RESULTS@{ub}
	Pointer to the beginning of the chunk (that means to the chunk
	name itself, followed by the chunk size); zero if chunk not found

@{b}   BUGS@{ub}
	none known

@{b}   SEE ALSO@{ub}
	@{"IFFL_GetBMHD()" Link "IFFL_GetBMHD()"}, @{"IFFL_GetColorTab()" Link "IFFL_GetColorTab()"}

@EndNode

@Node "IFFL_GetBMHD()" "iff.library/IFFL_GetBMHD"

@{b}    NAME@{ub}
	IFFL_GetBMHD -- find a @{"BitMapHeader" Link "INCLUDE:datatypes/pictureclass.h/Main" 94} of an IFF-file

@{b}    SYNOPSIS@{ub}
	header = IFFL_GetBMHD( iff )
	D0                     A1

	struct @{"BitMapHeader" Link "INCLUDE:datatypes/pictureclass.h/Main" 94} *IFFL_GetBMHD( IFFL_HANDLE )

@{b}    FUNCTION@{ub}
	Returns a pointer to a BMHD (BitMapHeader) structure as defined
	in iff.h and iff.i

@{b}    INPUTS@{ub}
	iff - IFF file handle, from @{"IFFL_OpenIFF()" Link "IFFL_OpenIFF()"}

@{b}    RESULTS@{ub}
	Pointer to the @{"BitMapHeader" Link "INCLUDE:datatypes/pictureclass.h/Main" 94}, or NULL if no BMHD chunk found

@{b}    SEE ALSO@{ub}
	@{"IFFL_FindChunk()" Link "IFFL_FindChunk()"}, @{"IFFL_GetColorTab()" Link "IFFL_GetColorTab()"}

@EndNode

@Node "IFFL_GetColorTab()" "iff.library/IFFL_GetColorTab"

@{b}    NAME@{ub}
	IFFL_GetColorTab -- find a CMAP and convert it to a ColorTable

@{b}    SYNOPSIS@{ub}
	count = IFFL_GetColorTab( iff, colortable )
	D0                        A1   A0

	@{"LONG" Link "INCLUDE:exec/types.h/Main" 35} IFFFL_GetColorTab( IFF_HANDLE, UWORD * )

@{b}    FUNCTION@{ub}
	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()" Link "graphics/LoadRGB4()"} function.

@{b}    INPUTS@{ub}
	iff        - IFF file handle, from @{"IFFL_OpenIFF()" Link "IFFL_OpenIFF()"}
	colortable - Pointer to a block of memory which must be large
	             enough to hold the colortable (2 bytes per color).
	             Must be WORD aligned.

@{b}    RESULT@{ub}
	Number of colors actually found, or zero if the file has no
	CMAP chunk

@{b}    SEE ALSO@{ub}
	@{"IFFL_FindChunk()" Link "IFFL_FindChunk()"}, @{"IFFL_GetBMHD()" Link "IFFL_GetBMHD()"}

@EndNode

@Node "IFFL_GetViewModes()" "iff.library/IFFL_GetViewModes"

@{b}    NAME@{ub}
	IFFL_GetViewModes() -- Get Amiga-specific ViewModes

@{b}    SYNOPSIS@{ub}
	viewmodes = IFFL_GetViewModes( iff )
	D0                             A1

	ULONG IFFL_GetViewModes( IFFL_HANDLE )

@{b}    FUNCTION@{ub}
	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" Link "INCLUDE:datatypes/pictureclass.h/Main" 94} structure.
	You can directly put the low WORD of the result of a call to
	IFFL_ GetViewModes() into the ns_ViewModes field of a @{"NewScreen" Link "INCLUDE:intuition/screens.h/Main" 476}
	structure, or you can use the whole ULONG for the SA_DisplayID tag
	under OS 2.x.

@{b}    INPUTS@{ub}
	iff - IFF file handle, from @{"OpenIFF()" Link "OpenIFF()"}

@{b}    RESULT@{ub}
	viewmodes - ULONG containing the view modes (HAM, LACE, HIRES ...)
	All forbidden bits are masked out, as suggested by CBM.
	Under Kickstart V1.3, only the lower WORD is used.

@{b}    BUGS@{ub}
	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. You can load such Halfbrite
	pictures into DPaint III and save them again, DPaint will generate
	the correct CAMG chunk.

@{b}    SEE ALSO@{ub}
	@{"<graphics/displayinfo.h>" Link "INCLUDE:graphics/displayinfo.h/Main" 0}

@EndNode

@Node "IFFL_IFFError()" "iff.library/IFFL_IFFError"

@{b}    NAME@{ub}
	IFFL_IFFError -- Get detailed error descrpition after an error

@{b}    SYNOPSIS@{ub}
	error = IFFL_IFFError()
	D0

	@{"LONG" Link "INCLUDE:exec/types.h/Main" 35} IFFL_IFFError( VOID )

@{b}    FUNCTION@{ub}
	If one of the iff.library functions returns zero, you can call
	IFFL_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.

@{b}    INPUTS@{ub}
	none

@{b}    RESULT@{ub}
	Error-number generated by the latest function call, or zero if
	no error.

@{b}    BUGS@{ub}
	If you don't close the IFF library at the end of your program
	(using @{"CloseLibrary()" Link "exec/CloseLibrary()"}) the error node will not be freed. The
	same task will then not be able to re-open the iff.library.
	(This is not a bug, it's a feature ;-))

@{b}    SEE ALSO@{ub}
	<iff.h>

@EndNode

@Node "IFFL_ModifyFrame()" "iff.library/IFFL_ModifyFrame"

@{b}    NAME@{ub}
	IFFL_ModifyFrame -- Modify an anim frame using a DLTA chunk

@{b}    SYNOPSIS@{ub}
	success = IFFL_ModifyFrame( modifyform, bitmap )
	D0                          A1          A0

	@{"BOOL" Link "INCLUDE:exec/types.h/Main" 68} IFFL_ModifyFrame( VOID *, struct @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} * )

@{b}    FUNCTION@{ub}
	Uses the DLTA chunk of the supplied FORM to modify the planes-data
	of the bitmap. Usually, playback of ANIMs will require two buffers,
	and double-buffering between them. So the data in the bitmap must
	be two frames back, and the DLTA chunk is used to modify the hidden
	frame to the next frame to be shown.

@{b}    INPUTS@{ub}
	modifyform - pointer to the FORM containing the actual DLTA chunk
	bitmap     - Pointer to a properly initialized @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} structure,
		     the planes must contain the image which was displayed
		     to frames back (using double-buffering)

@{b}    RESULT@{ub}
	Non-zero if OK, 0 if error; call @{"IFFL_IFFError()" Link "IFFL_IFFError()"} to know the reason
	of the failure

@{b}    RESTRICTIONS@{ub}
	Currently, only compression type 5 (Byte Vertical Delta Mode) is
	implemented. If you have animations which use modes 1 to 4, try
	loading them with DPaint III and saving them again.
	Sculpt-Animate ('J' type ANIM, Movie format) support will be
	added soon.
	I will implement some more compression types upon request.

@{b}    NOTE@{ub}
	This routine needs at least 820 bytes of stack.
	The size of the bitmap is not checked by this routine, the planes
	must have at least the size described in the BMHD of the anim
	file.

@{b}    SEE ALSO@{ub}
	@{"IFFL_IFFError()" Link "IFFL_IFFError()"}

@EndNode

@Node "IFFL_OpenIFF()" "iff.library/IFFL_OpenIFF"

@{b}   NAME@{ub}
	IFFL_OpenIFF -- Open an IFF file for reading or writing

@{b}   SYNOPSIS@{ub}
	iff = IFFL_OpenIFF( filename, mode )
	D0                  A0        D0

	IFFL_HANDLE IFFL_OpenIFF( char *, ULONG )

@{b}   FUNCTION@{ub}
	If mode == IFFL_MODE_READ:
	  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.

         New for V22:
         If xpkmaster.library is installed in your system, IFFL_OpenIFF()
         will be able to read and decompress compressed IFF files, if they
         use one of the xpk standard compression schemes.

	If mode == IFFL_MODE_WRITE:
	  Initializes an IFF file handle for writing. You may create chunks
	  with @{"IFFL_PushChunk()" Link "IFFL_PushChunk()"} and @{"IFFL_PopChunk()" Link "IFFL_PopChunk()"}, and you can write data
	  using the @{"IFFL_WriteChunkBytes()" Link "IFFL_WriteChunkBytes()"} routine.

@{b}   INPUTS@{ub}
	filename - Pointer to a null-terminated string
	mode     - IFFL_MODE_READ:  Open file for reading
	           IFFL_MODE_WRITE: Open file for writing

@{b}   RESULT@{ub}
	iff - IFF handle. Making assumptions about the internal structure
	      of this handle is unwise, and may break in the future.
	      If this function fails, NULL will be returned, and you may
	      call @{"IFFL_IFFError()" Link "IFFL_IFFError()"} to know the reason of the failure.

@{b}   SEE ALSO@{ub}
	@{"IFFL_CloseIFF()" Link "IFFL_CloseIFF()"}, @{"IFFL_PushChunk()" Link "IFFL_PushChunk()"}, @{"IFFL_PopChunk()" Link "IFFL_PopChunk()"},
	@{"IFFL_WriteChunkBytes()" Link "IFFL_WriteChunkBytes()"}, @{"IFFL_IFFError()" Link "IFFL_IFFError()"}

@{b}   BUGS@{ub}
	None known

@EndNode

@Node "IFFL_PopChunk()" "iff.library/IFFL_PopChunk"

@{b}    NAME@{ub}
	IFFL_PopChunk -- Pop top context node off context stack.

@{b}    SYNOPSIS@{ub}
	success = IFFL_PopChunk( iff )
	D0                       A0

	@{"BOOL" Link "INCLUDE:exec/types.h/Main" 68} IFFL_PopChunk( IFFL_HANDLE )

@{b}    FUNCTION@{ub}
	Pops top context chunk and updates the file accordingly.
	The function is normally called only for writing files and signals
	the end of a chunk.

@{b}    INPUTS@{ub}
	iff - IFF handle

@{b}    RESULTS@{ub}
	Non-zero  if successful or 0 if not successful (call @{"IFFL_IFFError()" Link "IFFL_IFFError()"}
	to get an IFFL_ERROR_... error code.

@{b}    SEE ALSO@{ub}
	@{"IFFL_PushChunk()" Link "IFFL_PushChunk()"}, @{"IFFL_WriteChunkBytes()" Link "IFFL_WriteChunkBytes()"}

@EndNode

@Node "IFFL_PushChunk()" "iff.library/IFFL_PushChunk"

@{b}    NAME@{ub}
	IFFL_PushChunk -- Push a new context node on the context stack.

@{b}    SYNOPSIS@{ub}
	success = IFFL_PushChunk( iff, type, id )
	D0                        A0   D0    D1

	@{"BOOL" Link "INCLUDE:exec/types.h/Main" 68} IFFL_PushChunk( IFFL_HANDLE, ULONG, ULONG )

@{b}    FUNCTION@{ub}
	Pushes a new context node on the context stack by reading it from the
	stream if this is a read file, or by creating it from the passed
	parameters if this is a write file.  Normally this function is only
	called in write mode, where the type and id codes specify the new
	chunk to create.  If this is a leaf chunk, i.e. a local chunk inside
	a FORM or PROP chunk, then the type argument is ignored.

@{b}    INPUTS@{ub}
	iff  - IFF handle
	type - chunk type specifier (ex. ILBM) (ignored for read mode or
	       leaf chunks).
	id   - chunk id specifier (ex. CMAP) (ignored for read mode).

@{b}    RESULTS@{ub}
	Non-zero if successful or 0 if not successful (call @{"IFFL_IFFError()" Link "IFFL_IFFError()"}
	to get an IFFL_ERROR_... error code.

@{b}    NOTE@{ub}
       Currently, the level of nested FORMs is restricted to 7.

@{b}    SEE ALSO@{ub}
	@{"IFFL_PopChunk()" Link "IFFL_PopChunk()"}, @{"IFFL_WriteChunkBytes()" Link "IFFL_WriteChunkBytes()"}

@EndNode

@Node "IFFL_SaveBitMap()" "iff.library/IFFL_SaveBitMap"

@{b}    NAME@{ub}
	IFFL_SaveBitMap -- save the planes of a @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} as an IFF-file

@{b}    SYNOPSIS@{ub}
	result = IFFL_SaveBitMap( filename, bitmap, colortable, flags )
	D0                        A0        A1      A2          D0

	@{"BOOL" Link "INCLUDE:exec/types.h/Main" 68} IFFL_SaveBitMap(char *, struct @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} *, UWORD *, ULONG )

@{b}    FUNCTION@{ub}
	Save the planes of a @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} 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" Link "INCLUDE:graphics/gfx.h/Main" 45} 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

@{b}   INPUTS@{ub}
	filename    - Name of the IFF file to create
	bitmap      - Pointer to the @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} 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

@{b}   RESULT@{ub}
	Non-zero if successful, 0 if an error occurred. You can then call
	@{"IFFL_IFFError()" Link "IFFL_IFFError()"} to know more about the reason of the failure.

@{b}   NOTE@{ub}
	Up to V19 this routine needs at least 650 bytes of stack space

@{b}   SEE ALSO@{ub}
	@{"IFFL_SaveClip()" Link "IFFL_SaveClip()"}

@EndNode

@Node "IFFL_SaveClip()" "iff.library/IFFL_SaveClip"

@{b}    NAME@{ub}
	IFFL_SaveClip -- save a part of a @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} as an IFF-file

@{b}    SYNOPSIS@{ub}
	result = IFFL_SaveClip
	D0       ( filename, bitmap, coltab, flags, xoff, yoff, width, height )
	           A0        A1      A2      D0     D1    D2    D3     D4

@{b}    FUNCTION@{ub}
	Save a part of a @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} as an IFF file

@{b}    INPUTS@{ub}
	filename    - Name of the IFF file to create
	bitmap      - Pointer to the @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 45} 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

@{b}    RESULTS@{ub}
	Non-zero if successful, 0 if an error occurred. You can then call
	@{"IFFL_IFFError()" Link "IFFL_IFFError()"} to know more about the reason of the failure.

@{b}    NOTE@{ub}
	Up to V19 this routine needs at least 650 bytes of stack space

@{b}    BUGS@{ub}
	The width of the rectangle will be truncated to WORD boundaries,
	because DPAINT wants it!

@{b}    SEE ALSO@{ub}
	@{"IFFL_SaveBitMap()" Link "IFFL_SaveBitMap()"}

@EndNode

@Node "IFFL_WriteChunkBytes()" "iff.library/IFFL_WriteChunkBytes"

@{b}   NAME@{ub}
	IFFL_WriteChunkBytes -- Write data into the current chunk

@{b}   SYNOPSIS@{ub}
	success = IFFL_WriteChunkBytes( iff, buf, size )
	D0                              A0   A1   D0

	@{"LONG" Link "INCLUDE:exec/types.h/Main" 35} IFFL_WriteChunkBytes( IFFL_HANDLE, @{"APTR" Link "INCLUDE:exec/types.h/Main" 33}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 35} )

@{b}   FUNCTION@{ub}
	Writes "size" bytes from the specified buffer into the current chunk.

@{b}   INPUTS@{ub}
	iff   - IFF file handle, from @{"IFFL_OpenIFF()" Link "IFFL_OpenIFF()"}.
	buf   - pointer to buffer area with bytes to be written.
	size  - number of bytes to write.

@{b}   RESULT@{ub}
	Non-NULL if the write was successful, or NULL if an error
	occurred. Call @{"IFFL_IFFError()" Link "IFFL_IFFError()"} to know what's going on.

@{b}   SEE ALSO@{ub}
	@{"IFFL_PushChunk()" Link "IFFL_PushChunk()"}, @{"IFFL_PopChunk()" Link "IFFL_PopChunk()"}, @{"IFFL_IFFError()" Link "IFFL_IFFError()"}

@EndNode

@Node "NewOpenIFF()" "iff.library/NewOpenIFF"

@{b}   NAME@{ub}
	NewOpenIFF -- allocate memory for an IFF-file and read it

@{b}   SYNOPSIS@{ub}
	ifffile = NewOpenIFF( filename, memattr )
	D0                    A0        D0

	IFFFILE OpenIFF( char * )

@{b}   FUNCTION@{ub}
	THIS FUNCTION IS OBSOLETE. USE @{"IFFL_OpenIFF()" Link "IFFL_OpenIFF()"} INSTEAD.

@{b}   INPUTS@{ub}
	filename - Pointer to a null-terminated string
	memattr  - Memory requirements as used for Exec's @{"AllocMem()" Link "exec/AllocMem()"},
	           such as MEMF_CHIP, MEMF_PUBLIC ...
	           (MEMF_CLEAR is not necessary)

@{b}   RESULT@{ub}
	ifffile - 'FileHandle', points to the beginning of the IFF file
	("FORM...."), Zero if unsuccessful. Call IFFError() to get
	the reason of the failure.

@{b}   SEE ALSO@{ub}
	@{"IFFL_OpenIFF()" Link "IFFL_OpenIFF()"}, @{"IFFL_CloseIFF()" Link "IFFL_CloseIFF()"}, @{"IFFL_IFFError()" Link "IFFL_IFFError()"}

@{b}   BUGS@{ub}
	None known

@EndNode

@Node "OpenIFF()" "iff.library/OpenIFF"

@{b}    NAME@{ub}
	OpenIFF -- allocate memory for an IFF-file and read it

@{b}    SYNOPSIS@{ub}
	ifffile = OpenIFF( filename )
	D0                 A0

	IFFFILE OpenIFF( char * )

@{b}    FUNCTION@{ub}
	THIS FUNCTION IS OBSOLETE. USE @{"IFFL_OpenIFF()" Link "IFFL_OpenIFF()"} INSTEAD.

@{b}   INPUTS@{ub}
	filename - Pointer to a null-terminated string

@{b}   RESULT@{ub}
	ifffile - 'FileHandle', points to the beginning of the IFF file
	("FORM...."), 0 if unsuccessful. Call IFFError() to get the
	reason of the failure.

@{b}   BUGS@{ub}
	None

@{b}   SEE ALSO@{ub}
	@{"IFFL_OpenIFF()" Link "IFFL_OpenIFF()"}, @{"IFFL_CloseIFF()" Link "IFFL_CloseIFF()"}, @{"IFFL_IFFError()" Link "IFFL_IFFError()"}

@EndNode