## model

model — Model manipulation functions

## Synopsis

    #include <g3d/g3d.h>

    #define             G3D_MODEL_CENTER
    #define             G3D_MODEL_NOCHECK
    #define             G3D_MODEL_OPTIMIZE
    #define             G3D_MODEL_SCALE
                        G3DModel;
    G3DModel *          g3d_model_new                       (void);
    G3DModel *          g3d_model_load                      (G3DContext *context,
                                                             const gchar *filename);
    G3DModel *          g3d_model_load_full                 (G3DContext *context,
                                                             const gchar *filename,
                                                             guint32 flags);
    gboolean            g3d_model_check                     (G3DModel *model);
    gboolean            g3d_model_center                    (G3DModel *model);
    gboolean            g3d_model_transform                 (G3DModel *model,
                                                             G3DMatrix *matrix);
    void                g3d_model_clear                     (G3DModel *model);
    void                g3d_model_free                      (G3DModel *model);
    G3DObject *         g3d_model_get_object_by_name        (G3DModel *model,
                                                             const gchar *name);

## Description

A model is a group of objects. All information loaded from a file by libg3d is found in this model.

## Details

### G3D_MODEL_CENTER

    #define G3D_MODEL_CENTER          (1 << 1)

The model should be centered around the (0,0,0).

### G3D_MODEL_NOCHECK

    #define G3D_MODEL_NOCHECK         (1 << 3)

The common checks should be disabled. The checks include:

- faces have at least 3 indices
- face indices are <= number of vertices
- material of faces is not NULL

### G3D_MODEL_OPTIMIZE

    #define G3D_MODEL_OPTIMIZE        (1 << 2)

The model material/object/face lists should be serialized to some private arrays (deprecated).

### G3D_MODEL_SCALE

    #define G3D_MODEL_SCALE           (1 << 0)

The model should be scaled to a maximum extension of +/- 10.0.

### G3DModel

    typedef struct {
    	gchar *filename;
    	GSList *materials;
    	GSList *objects;
    } G3DModel;

A 3D model.

gchar *`filename`; | file name or URI of loaded model, may be set by application
GSList *`materials`; | list of materials (G3DMaterial)
GSList *`objects`; | list of objects (G3DObject)

### g3d_model_new ()

    G3DModel *          g3d_model_new                       (void);

This functions allocates and initializes a new G3DModel.

Returns : | a newly allocated G3DModel

### g3d_model_load ()

    G3DModel *          g3d_model_load                      (G3DContext *context,
                                                             const gchar *filename);

Loads a model from a file. The model is checked, centered, resized, optimized.

`context` : | a valid context
`filename` : | the file name of the model to load
Returns : | the loaded model or NULL in case of an error

### g3d_model_load_full ()

    G3DModel *          g3d_model_load_full                 (G3DContext *context,
                                                             const gchar *filename,
                                                             guint32 flags);

Loads a model from a file. Depending on `flags` the model is checked, centered, resized, optimized.

`context` : | a valid context
`filename` : | the file name of the model to load
`flags` : | object manipulation flags
Returns : | the loaded model or NULL in case of an error.

### g3d_model_check ()

    gboolean            g3d_model_check                     (G3DModel *model);

Checks whether a model returned by plugin is valid.

`model` : | the model to check
Returns : | TRUE on success, FALSE on error

### g3d_model_center ()

    gboolean            g3d_model_center                    (G3DModel *model);

Translates all object coordinates that the object center is at (0, 0, 0)

`model` : | the model to center
Returns : | TRUE on success, FALSE on error

### g3d_model_transform ()

    gboolean            g3d_model_transform                 (G3DModel *model,
                                                             G3DMatrix *matrix);

Transform all toplevel objects in model with matrix.

`model` : | the model
`matrix` : | transformation matrix
Returns : | TRUE on success, FALSE else

### g3d_model_clear ()

    void                g3d_model_clear                     (G3DModel *model);

Removes all objects from a model.

`model` : | the model to clear

### g3d_model_free ()

    void                g3d_model_free                      (G3DModel *model);

Frees all memory allocated for the model including all objects, materials and textures.

`model` : | the model to free

### g3d_model_get_object_by_name ()

    G3DObject *         g3d_model_get_object_by_name        (G3DModel *model,
                                                             const gchar *name);

Searches the object tree for an object with the given name.

`model` : | the model containing all objects
`name` : | the name of the requested object
Returns : | the requested object or NULL if non was found