## iff

iff — IFF file helper functions

## Synopsis

    #include <g3d/iff.h>

    #define             G3D_IFF_PAD1
    #define             G3D_IFF_PAD2
    #define             G3D_IFF_PAD4
    #define             G3D_IFF_PAD8
    #define             G3D_IFF_LE
    #define             G3D_IFF_LEN16
    #define             G3D_IFF_SUBCHUNK_LEN16
    #define             G3D_IFF_MKID                        (a,b,c,d)
    gboolean            g3d_iff_check                       (G3DStream *stream,
                                                             guint32 *id,
                                                             gsize *len);
    gsize               g3d_iff_read_chunk                  (G3DStream *stream,
                                                             guint32 *id,
                                                             gsize *len,
                                                             guint32 flags);
    gpointer            g3d_iff_handle_chunk                (G3DIffGlobal *global,
                                                             G3DIffLocal *plocal,
                                                             G3DIffChunkInfo *chunks,
                                                             guint32 flags);
    gboolean            g3d_iff_chunk_matches               (guint32 id,
                                                             gchar *tid);
    gboolean            g3d_iff_read_ctnr                   (G3DIffGlobal *global,
                                                             G3DIffLocal *local,
                                                             G3DIffChunkInfo *chunks,
                                                             guint32 flags);
    gchar*              g3d_iff_id_to_text                  (guint32 id);
    FILE*               g3d_iff_open                        (const gchar *filename,
                                                             guint32 *id,
                                                             guint32 *len);
    int                 g3d_iff_readchunk                   (FILE *f,
                                                             guint32 *id,
                                                             guint32 *len,
                                                             guint32 flags);
    gboolean            (*G3DIffChunkCallback)              (G3DIffGlobal *global,
                                                             G3DIffLocal *local);
    #define             g3d_iff_chunk_callback
                        G3DIffChunkInfo;
    #define             g3d_iff_chunk_info
                        G3DIffGlobal;
    #define             g3d_iff_gdata
                        G3DIffLocal;
    #define             g3d_iff_ldata

## Description

These are helper functions to read data from the Interchange File Format (IFF).

## Details

### G3D_IFF_PAD1

    #define G3D_IFF_PAD1   0x01

No padding is done after chunks.

### G3D_IFF_PAD2

    #define G3D_IFF_PAD2   0x02

Chunks are 2-byte aligned

### G3D_IFF_PAD4

    #define G3D_IFF_PAD4   0x04

Chunks are 4-byte aligned

### G3D_IFF_PAD8

    #define G3D_IFF_PAD8   0x08

Chunks are 8-byte aligned

### G3D_IFF_LE

    #define G3D_IFF_LE               0x40 /* little endian */

The file has little-endian data.

### G3D_IFF_LEN16

    #define G3D_IFF_LEN16            0x20

All chunks have 16-bit sizes.

### G3D_IFF_SUBCHUNK_LEN16

    #define G3D_IFF_SUBCHUNK_LEN16   0x10

All chunks except the toplevel ones have 16-bit sizes.

### G3D_IFF_MKID()

    #define             G3D_IFF_MKID(a,b,c,d)

Generate an IFF chunk identifier from character representation, e.g. G3D_IFF_MKID('F','O','R','M').

`a` : | first byte
`b` : | second byte
`c` : | third byte
`d` : | fourth byte

### g3d_iff_check ()

    gboolean            g3d_iff_check                       (G3DStream *stream,
                                                             guint32 *id,
                                                             gsize *len);

Checks a stream for a valid IFF signature and reads the top level container.

`stream` : | stream containing IFF file to check
`id` : | top level ID (out)
`len` : | length of top level container (out)
Returns : | TRUE on success (valid IFF), FALSE else

### g3d_iff_read_chunk ()

    gsize               g3d_iff_read_chunk                  (G3DStream *stream,
                                                             guint32 *id,
                                                             gsize *len,
                                                             guint32 flags);

Reads one chunk header from an IFF file.

`stream` : | stream to read from
`id` : | ID of chunk (out)
`len` : | length of chunk (excluding header) (out)
`flags` : | flags
Returns : | real length of chunk including header and possible padding byte

### g3d_iff_handle_chunk ()

    gpointer            g3d_iff_handle_chunk                (G3DIffGlobal *global,
                                                             G3DIffLocal *plocal,
                                                             G3DIffChunkInfo *chunks,
                                                             guint32 flags);

Handle an IFF chunk based on chunk description.

`global` : | global data
`plocal` : | local data of parent chunk, must not be NULL
`chunks` : | chunk description list
`flags` : | IFF flags
Returns : | level object for siblings, may be NULL.

### g3d_iff_chunk_matches ()

    gboolean            g3d_iff_chunk_matches               (guint32 id,
                                                             gchar *tid);

Check whether `id` and `tid` match.

`id` : | IFF identifier
`tid` : | textual representation of identifier
Returns : | TRUE on match, FALSE else.

### g3d_iff_read_ctnr ()

    gboolean            g3d_iff_read_ctnr                   (G3DIffGlobal *global,
                                                             G3DIffLocal *local,
                                                             G3DIffChunkInfo *chunks,
                                                             guint32 flags);

Read subchunks in current chunk and handle them appropriately.

`global` : | global data
`local` : | local data of current chunk, must not be NULL
`chunks` : | chunk description list
`flags` : | IFF flags
Returns : | TRUE on success, FALSE else.

### g3d_iff_id_to_text ()

    gchar*              g3d_iff_id_to_text                  (guint32 id);

Get the text representation of an IFF chunk identifier.

`id` : | an IFF identifier
Returns : | a newly allocated string containing the text identifier.

### g3d_iff_open ()

    FILE*               g3d_iff_open                        (const gchar *filename,
                                                             guint32 *id,
                                                             guint32 *len);

Opens an IFF file, checks it and reads its top level container.

`filename` : | file name of IFF file
`id` : | top level ID (out)
`len` : | length of top level container (out)
Returns : | the file pointer of open file or NULL in case of an error

### g3d_iff_readchunk ()

    int                 g3d_iff_readchunk                   (FILE *f,
                                                             guint32 *id,
                                                             guint32 *len,
                                                             guint32 flags);

Reads one chunk header from an IFF file.

`f` : | the open IFF file pointer
`id` : | ID of chunk (out)
`len` : | length of chunk (excluding header) (out)
`flags` : | flags
Returns : | real length of chunk including header and possible padding byte

### G3DIffChunkCallback ()

    gboolean            (*G3DIffChunkCallback)              (G3DIffGlobal *global,
                                                             G3DIffLocal *local);

IFF callback function prototype.

`global` : | the global data
`local` : | the local data
Returns : | TRUE on success, FALSE else.

### g3d_iff_chunk_callback

    #define g3d_iff_chunk_callback G3DIffChunkCallback

IFF chunk callback (deprecated).

### G3DIffChunkInfo

    typedef struct {
    	gchar *id;
    	gchar *description;
    	gboolean container;
    	G3DIffChunkCallback callback;
    } G3DIffChunkInfo;

A chunk type description.

gchar *`id`; | identifier of chunk
gchar *`description`; | human-readable description of chunk type
gboolean `container`; | TRUE if this chunk contains sub-chunks
G3DIffChunkCallback `callback`; | function to be called if such a chunk is found

### g3d_iff_chunk_info

    #define g3d_iff_chunk_info G3DIffChunkInfo

IFF chunk description (deprecated).

### G3DIffGlobal

    typedef struct {
    	G3DContext *context;
    	G3DModel *model;
    	G3DStream *stream;
    	guint32 flags;
    	gpointer user_data;
    	FILE *f;
    	long int max_fpos;
    } G3DIffGlobal;

The plugin-global data to be given to IFF callback functions.

G3DContext *`context`; | a valid context
G3DModel *`model`; | a model
G3DStream *`stream`; | the stream to read model from
guint32 `flags`; | IFF flags
gpointer `user_data`; | to be used by plugin
FILE *`f`; | file to read model from (DEPRECATED)
long int `max_fpos`; | maximum file position (DEPRECATED)

### g3d_iff_gdata

    #define g3d_iff_gdata G3DIffGlobal

IFF global data (deprecated).

### G3DIffLocal

    typedef struct {
    	guint32 id;
    	guint32 parent_id;
    	gpointer object;
    	gint32 level;
    	gpointer level_object;
    	gint32 nb;
    	gboolean finalize;
    } G3DIffLocal;

The function-local data for IFF callback functions.

guint32 `id`; | chunk identifier
guint32 `parent_id`; | parent chunk identifier
gpointer `object`; | an object set by parent callbacks, may be NULL
gint32 `level`; | level of chunk
gpointer `level_object`; | object shared by callbacks on the same level, may be NULL
gint32 `nb`; | number of bytes remaining in chunk, has to be decremented after correctly after reading from stream
gboolean `finalize`; | for container chunks the callback function is called before and after processing possible sub-chunks, the second time `finalize` is set to TRUE

### g3d_iff_ldata

    #define g3d_iff_ldata G3DIffLocal

IFF local data (deprecated).