## iff

iff — IFF file helper functions

## Functions

#define | G3D_IFF_MKID()
gboolean | g3d_iff_check ()
gsize | g3d_iff_read_chunk ()
gpointer | g3d_iff_handle_chunk ()
gboolean | g3d_iff_chunk_matches ()
gboolean | g3d_iff_read_ctnr ()
gchar * | g3d_iff_id_to_text ()
FILE * | g3d_iff_open ()
int | g3d_iff_readchunk ()
gboolean | (*G3DIffChunkCallback) ()

## Types and Values

#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_chunk_callback
| G3DIffChunkInfo
#define | g3d_iff_chunk_info
| G3DIffGlobal
#define | g3d_iff_gdata
| G3DIffLocal
#define | g3d_iff_ldata

## Includes

    #include <g3d/iff.h>

## Description

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

## Functions

### 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').

#### Parameters

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

#### Returns

unsigned integer identifier.

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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);

`g3d_iff_id_to_text` is deprecated and should not be used in newly-written code.

Get the text representation of an IFF chunk identifier.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

global | the global data |
local | the local data |

#### Returns

TRUE on success, FALSE else.

## Types and Values

### 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_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.

#### Members

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.

#### Members

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.

#### Members

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).