## light

light — Controls the use of lights in the rendering window.

## Synopsis

    enum                Material;
    typedef             Light;
    Light*              light_newDefault                    ();

    struct              lightEnvironnement_struct;
    typedef             LightEnvironnement;
    LightEnvironnement* lightEnvironnement_new              ();
    void                lightEnvironnementFree              (LightEnvironnement *env);
    gboolean            lightEnvironnementAdd_light         (LightEnvironnement *env,
                                                             Light *light);
    gboolean            lightEnvironnementDelete_light      (LightEnvironnement *env,
                                                             Light *light);
    gboolean            lightEnvironnementEmpty_lightList   (LightEnvironnement *env);
    GList*              lightEnvironnementGet_lightList     (LightEnvironnement *env);
    gboolean            lightEnvironnementApply             (LightEnvironnement *env);

## Description

One can defines several lights in OpenGL. The LightEnvironnement is an object that stores several of them and that can be applied to the current OpenGL context using `lightEnvironnementApply()`. The lights that are created with `light_newDefault()` are ambiant light with a white colour. The multiplier coefficient is use to soften lights when several are used together. It is used as a factor for all light parameters (ambient, diffuse...) ecept the specular one.

## Details

### enum Material

    typedef enum
      {
        material_amb,
        material_dif,
        material_shi,
        material_spe,
        material_emi,
        nb_material
      } Material;

This enum is used to address the OpenGL parameters for light rendering.

`material_amb` | the ambient identifier ;
`material_dif` | the diffuse identifier ;
`material_shi` | the shiningness identifier ;
`material_spe` | the specular identifier ;
`material_emi` | the emissivity identifier ;
`nb_material` | number of used material identifiers.

### Light

    typedef struct light_struct Light;

A short name for light_struct objects.

### light_newDefault ()

    Light*              light_newDefault                    ();

Create a new light with default value (white color and position in the front, right, top position of the screen).

Returns : | the newly created Light. Use `g_free()` to deallocate this light.

### struct lightEnvironnement_struct

    struct lightEnvironnement_struct;

An opaque structure to allow an OpenGL context to manage and use several lights.

### LightEnvironnement

    typedef struct lightEnvironnement_struct LightEnvironnement;

A short way to access lightEnvironnement_struct objects.

### lightEnvironnement_new ()

    LightEnvironnement* lightEnvironnement_new              ();

Create a new LightEnvironnement object. It contains no light when created. Use `lightEnvironnementAdd_light()` to add new lights and `lightEnvironnementDelete_light()` to remove others.

Returns : | a newly created LightEnvironnement. Use `lightEnvironnementFree()` to free such an object.

### lightEnvironnementFree ()

    void                lightEnvironnementFree              (LightEnvironnement *env);

Free memory occupied by the given environnement.

`env` : | a LightEnvironnement object.

### lightEnvironnementAdd_light ()

    gboolean            lightEnvironnementAdd_light         (LightEnvironnement *env,
                                                             Light *light);

This method adds the given `light` to the list of known lights declared in the given environnement. The light is not copied and should not be freed when stored in the environnement.

`env` : | a LightEnvironnement object ;
`light` : | a Light object.
Returns : | TRUE if `lightEnvironnementApply()` should be called.

### lightEnvironnementDelete_light ()

    gboolean            lightEnvironnementDelete_light      (LightEnvironnement *env,
                                                             Light *light);

This method removes the given `light` from the list of known lights declared in the given environnement. The `light` argument is first removed and then freed by a call to `g_free()`.

`env` : | a LightEnvironnement object ;
`light` : | a Light object.
Returns : | TRUE if `lightEnvironnementApply()` should be called.

### lightEnvironnementEmpty_lightList ()

    gboolean            lightEnvironnementEmpty_lightList   (LightEnvironnement *env);

Empty the list of stored lights. All stored lights objects are freed.

`env` : | a LightEnvironnement object.
Returns : | TRUE if the `lightEnvironnementApply()` should be called.

### lightEnvironnementGet_lightList ()

    GList*              lightEnvironnementGet_lightList     (LightEnvironnement *env);

Retrieve the list of known Light used by the given environnement.

`env` : | a LightEnvironnement object.
Returns : | a list of Light objects. Should not be freed.

### lightEnvironnementApply ()

    gboolean            lightEnvironnementApply             (LightEnvironnement *env);

Apply all stored informations about lights to the current OpenGL context.

`env` : | a LightEnvironnement object.
Returns : | TRUE if the "OpenGLAskForReDraw" signal should be emitted after a call to this method.