MashLightSet

## MashLightSet MashLightSet — A group of MashLights which can be used to affect the appearance of a MashModel. |

## Synopsis

                        MashLightSet;
    struct              MashLightSetClass;
    MashLightSet *      mash_light_set_new                  (void);
    void                mash_light_set_add_light            (MashLightSet *light_set,
                                                             MashLight *light);
    void                mash_light_set_remove_light         (MashLightSet *light_set,
                                                             MashLight *light);
    CoglHandle          mash_light_set_begin_paint          (MashLightSet *light_set,
                                                             CoglHandle material);

## Object Hierarchy

      GObject
       +----MashLightSet

## Description

MashLightSet is a toplevel object that contains a list of MashLights. The set which a light belongs to is separate from its parent actor. For a light to be useful it needs to be added to both a light set and a parent container.

The MashLightSet can only be used with actors that are specifically designed to support it. MashModel is one such actor. It can be told to use a light set with `mash_model_set_light_set()`.

The light set implements the Blinn-Phong lighting model which is the standard model used in fixed function version of OpenGL and Direct3D. The lighting calculations are performed per-vertex and then interpolated across the surface of the primitives.

Lights are positioned as normal actors by adding MashLights them to a container and moving them. The lights do not have to be in any particular position relative to the models in the hierarchy of actors, although it wouldn't make much sense if they were on different stages. The lights are subclasses of ClutterActor so they can be positioned and animated using the usual Clutter animation framework.

The lighting implementation requires GLSL support from Clutter. If the application can still work without lighting it would be worth checking for shader support by passing `COGL_FEATURE_SHADERS_GLSL` to `cogl_features_available()`.

It should be possible to extend the lighting model and implement application-specific lighting algorithms by subclassing MashLight and adding shader snippets by overriding `mash_light_generate_shader()`.

## Details

### MashLightSet

    typedef struct _MashLightSet MashLightSet;

The MashLightSet structure contains only private data.

### struct MashLightSetClass

    struct MashLightSetClass {
    };

The MashLightSetClass structure contains only private data.

### mash_light_set_new ()

    MashLightSet *      mash_light_set_new                  (void);

Constructs a new MashLightSet.

Returns : | a new MashLightSet.

### mash_light_set_add_light ()

    void                mash_light_set_add_light            (MashLightSet *light_set,
                                                             MashLight *light);

This adds a light to the set. Lights need to be added to the light set as well as to a container somewhere in the Clutter actor hierarchy in order to be useful.

`light_set` : | A MashLightSet instance
`light` : | A MashLight

### mash_light_set_remove_light ()

    void                mash_light_set_remove_light         (MashLightSet *light_set,
                                                             MashLight *light);

Removes a light from the set.

`light_set` : | A MashLightSet instance
`light` : | A MashLight

### mash_light_set_begin_paint ()

    CoglHandle          mash_light_set_begin_paint          (MashLightSet *light_set,
                                                             CoglHandle material);

This function should only be needed by custom actors that wish to use the lighting model of Mash. The function should be called every time the actor is painted. The `material` parameter is used to specify the lighting material properties. The material is not otherwise read or modified. The material properties that are used are: the emission color, the ambient color, the diffuse color, the specular color and the shininess.

The return value is a CoglProgram that should be used to paint the actor. The actor should attach this to its material using `cogl_material_set_user_program()`.

MashModels are already designed to use this function when a light set is passed to `mash_model_set_light_set()`.

`light_set` : | A MashLightSet instance
`material` : | The material that will be used to paint
Returns : | a CoglProgram to use for rendering.

Since 0.2