MashModel

## MashModel MashModel — An actor that can be used to render a PLY model. |

## Synopsis

                        MashModel;
    struct              MashModelClass;
    ClutterActor *      mash_model_new                      (void);
    ClutterActor *      mash_model_new_from_file            (MashDataFlags flags,
                                                             const gchar *filename,
                                                             GError **error);
    CoglHandle          mash_model_get_material             (MashModel *self);
    void                mash_model_set_material             (MashModel *self,
                                                             CoglHandle material);
    MashData *          mash_model_get_data                 (MashModel *self);
    void                mash_model_set_data                 (MashModel *self,
                                                             MashData *data);
    gboolean            mash_model_get_fit_to_allocation    (MashModel *self);
    void                mash_model_set_fit_to_allocation    (MashModel *self,
                                                             gboolean fit_to_allocation);
    MashLightSet *      mash_model_get_light_set            (MashModel *self);
    void                mash_model_set_light_set            (MashModel *self,
                                                             MashLightSet *light_set);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----MashModel

## Implemented Interfaces

MashModel implements ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## Properties

      "data"                     MashData*             : Read / Write
      "fit-to-allocation"        gboolean              : Read / Write
      "light-set"                MashLightSet*         : Read / Write
      "material"                 CoglHandle*           : Read / Write

## Description

MashModel is an actor subclass that can be used to render a 3D model. The model is a normal ClutterActor that can be animated and positioned with the methods of ClutterActor.

By default the model will be scaled to best fit within the size of the actor. Therefore it is possible to take a small model that may have positions ranging between -1 and 1 and draw it at a larger size just by setting the size on the actor. This behaviour can be disabled with `mash_model_set_fit_to_allocation()`.

The actual data for the model is stored in a separate object called MashData. This can be used to share the data for a model between multiple actors without having to duplicate resources of the data. Alternatively `mash_model_new_from_file()` can be used as a convenience wrapper to easily make an actor out of a PLY without having to worry about MashData. To share the data with another actor, call `mash_model_get_data()` on an existing actor then call `mash_model_set_data()` with the return value on a new actor.

The model can be rendered with any Cogl material. By default the model will use a solid white material. The material color is blended with the model's vertex colors so the white material will cause the vertex colors to be used directly. MashData is able to load texture coordinates from the PLY file so it is possible to render a textured model by setting a texture layer on the material, like so:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    /* Create an actor out of a PLY model file */
    ClutterActor *model
      = mash_model_new_from_file ("some-model.ply", NULL);
    /* Get a handle to the default material for the actor */
    CoglHandle material
      = mash_model_get_material (MASH_MODEL (model));
    /* Load a texture image from a file */
    CoglHandle texture
      = cogl_texture_new_from_file ("some-image.png", COGL_TEXTURE_NONE,
                                    COGL_PIXEL_FORMAT_ANY, NULL);
    /* Set a texture layer on the material */
    cogl_material_set_layer (material, 0, texture);
    /* The texture is now referenced by the material so we can
      drop the reference we have */
    cogl_handle_unref (texture);

## Details

### MashModel

    typedef struct _MashModel MashModel;

The MashModel structure contains only private data.

### struct MashModelClass

    struct MashModelClass {
    };

The MashModelClass structure contains only private data.

### mash_model_new ()

    ClutterActor *      mash_model_new                      (void);

Constructs a new MashModel. Nothing will be rendered by the model until a MashData is attached using `mash_model_set_data()`.

Returns : | a new MashModel.

### mash_model_new_from_file ()

    ClutterActor *      mash_model_new_from_file            (MashDataFlags flags,
                                                             const gchar *filename,
                                                             GError **error);

This is a convenience function that creates a new MashData and immediately loads the data in `filename`. If the load succeeds a new MashModel will be created for the data. The model has a default white material so that if vertices of the model have any color attributes they will be used directly. The material does not have textures by default so if you want the model to be textured you will need to modify the material.

`flags` : | Flags for loading the data.
`filename` : | The name of a PLY file to load.
`error` : | Return location for a GError or `NULL`.
Returns : | a new MashModel or `NULL` if the load failed.

### mash_model_get_material ()

    CoglHandle          mash_model_get_material             (MashModel *self);

Gets the material that will be used to render the model. The material can be modified to affect the appearence of the model. By default the material will be solid white.

`self` : | A MashModel instance
Returns : | a handle to the Cogl material used by the model.

### mash_model_set_material ()

    void                mash_model_set_material             (MashModel *self,
                                                             CoglHandle material);

Replaces the material that will be used to render the model with the given one. By default a MashModel will use a solid white material. However the color of the material is still blended with the vertex colors so the white material will cause the vertex colors to be used directly. If you want the model to be textured you will need to create a material that has a texture layer and set it with this function.

If a MashLightSet is used with the model then the material given here will be modified to use the program generated by that light set. If multiple models are expected to use the same material with different light sets, it would be better to use a different copy of the same material for each set of models so that they don't repeatedly change the program on the material during paint.

`self` : | A MashModel instance
`material` : | A handle to a Cogl material

### mash_model_get_data ()

    MashData *          mash_model_get_data                 (MashModel *self);

Gets the model data that will be used to render the actor.

`self` : | A MashModel instance
Returns : | A pointer to a MashData instance or `NULL` if no data has been set yet.

### mash_model_set_data ()

    void                mash_model_set_data                 (MashModel *self,
                                                             MashData *data);

Replaces the data used by the actor with `data`. A reference is taken on `data` so if you no longer need it you should unref it with `g_object_unref()`.

`self` : | A MashModel instance
`data` : | The new MashData

### mash_model_get_fit_to_allocation ()

    gboolean            mash_model_get_fit_to_allocation    (MashModel *self);

`self` : | A MashModel instance
Returns : | whether the actor will try to scale the model to fit within the allocation.

### mash_model_set_fit_to_allocation ()

    void                mash_model_set_fit_to_allocation    (MashModel *self,
                                                             gboolean fit_to_allocation);

This sets whether the actor should scale the model to fit the actor's allocation. If it's `TRUE` then all of the axes of the model will be scaled by the same amount to fill the allocation as much as possible without distorting the aspect ratio. The model is also translated so that it is at the center of the allocation and centered at 0 along the z axis. The size along the z axis is not considered when calculating a scale so if the model is largest along that axis then the actor may appear too large. The transformations are applied in addition to the actor's transformations so it is still possible scale the actor further using the scale-x and scale-y properties. The preferred size of the actor will be the width and height of the model. If width-for-height or height-for-width allocation is being used then MashModel will return whatever width or height will exactly preserve the aspect ratio.

If the value is `FALSE` then the actor is not transformed so the origin of the model will be the top left corner of the actor. The preferred size of the actor will be maximum extents of the model although the allocation is not considered during paint so if the model extends past the allocated size then it will draw outside the allocation.

The default value is `TRUE`.

`self` : | A MashModel instance
`fit_to_allocation` : | New value

### mash_model_get_light_set ()

    MashLightSet *      mash_model_get_light_set            (MashModel *self);

`self` : | A MashModel instance
Returns : | the MashLightSet previously set with `mash_model_set_light_set()`.

Since 0.2

### mash_model_set_light_set ()

    void                mash_model_set_light_set            (MashModel *self,
                                                             MashLightSet *light_set);

This sets the MashLightSet that will be used to render the model. Alternatively `NULL` can be passed to disable lighting for this model. The light set represents a collection of MashLights that will affect the appearance of the model.

`self` : | A MashModel instance
`light_set` : | A new MashLightSet

Since 0.2

## Property Details

### The `"data"` property

      "data"                     MashData*             : Read / Write

The MashData to render.

### The `"fit-to-allocation"` property

      "fit-to-allocation"        gboolean              : Read / Write

Whether to transform the model so that it fills the actor's allocation while preserving the aspect ratio.

Default value: TRUE

### The `"light-set"` property

      "light-set"                MashLightSet*         : Read / Write

The MashLightSet to use for the lighting model.

### The `"material"` property

      "material"                 CoglHandle*           : Read / Write

The Cogl material to render with.