MashLight

## MashLight MashLight — An object for the common state of all light types |

## Synopsis

                        MashLight;
    struct              MashLightClass;
    void                mash_light_set_ambient              (MashLight *light,
                                                             const ClutterColor *ambient);
    void                mash_light_get_ambient              (MashLight *light,
                                                             ClutterColor *ambient);
    void                mash_light_set_diffuse              (MashLight *light,
                                                             const ClutterColor *diffuse);
    void                mash_light_get_diffuse              (MashLight *light,
                                                             ClutterColor *diffuse);
    void                mash_light_set_specular             (MashLight *light,
                                                             const ClutterColor *specular);
    void                mash_light_get_specular             (MashLight *light,
                                                             ClutterColor *specular);

    void                mash_light_generate_shader          (MashLight *light,
                                                             GString *uniform_source,
                                                             GString *main_source);
    void                mash_light_update_uniforms          (MashLight *light,
                                                             CoglHandle program);
    void                mash_light_append_shader            (MashLight *light,
                                                             GString *shader_source,
                                                             const char *snippet);
    int                 mash_light_get_uniform_location     (MashLight *light,
                                                             CoglHandle program,
                                                             const char *uniform_name);
    void                mash_light_set_direction_uniform    (MashLight *light,
                                                             CoglHandle program,
                                                             int uniform_location,
                                                             const float *direction_in);
    void                mash_light_get_modelview_matrix     (MashLight *light,
                                                             CoglMatrix *matrix);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----MashLight
                         +----MashDirectionalLight
                         +----MashPointLight

## Implemented Interfaces

MashLight implements ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## Properties

      "ambient"                  ClutterColor*         : Read / Write
      "diffuse"                  ClutterColor*         : Read / Write
      "specular"                 ClutterColor*         : Read / Write

## Description

MashLight is the abstract base class of all lights in Mash. It can not be instantiated directly. Instead one of its subclasses should be used such as MashPointLight, MashSpotLight or MashDirectionalLight.

MashLights must be added to a MashLightSet and a parent container before they will have any effect.

MashLight contains three light colors that are common to all three light types that Mash supports. These are ambient, diffuse and specular. The colors are of the lights are combined with the corresponding colors of the CoglMaterial to give a final fragment color. The material colors can be changed for a MashModel by extracting the CoglMaterial with `mash_model_get_material()` and then calling functions such as `cogl_material_set_diffuse()`.

MashLight can be subclassed in an application to provide custom lighting algorithms.

## Details

### MashLight

    typedef struct _MashLight MashLight;

The MashLight structure contains only private data.

### struct MashLightClass

    struct MashLightClass {
      void (* generate_shader) (MashLight *light,
                                GString *uniform_source,
                                GString *main_source);
      void (* update_uniforms) (MashLight *light,
                                CoglHandle program);
    };

`generate_shader` () | Virtual used for creating custom light types
`update_uniforms` () | Virtual used for creating custom light types

### mash_light_set_ambient ()

    void                mash_light_set_ambient              (MashLight *light,
                                                             const ClutterColor *ambient);

Sets the ‘ambient’ color emitted by the light. If the light reaches a vertex at all then the ambient color affects the vertex regardless of its orientation or distance from the light. In real-world lighting, even if an object isn't in a direct line of sight to a light it can still be partially lit due to the fact that light can bounce off other objects to reach it. The Mash lighting model doesn't simulate this bouncing so the ambient color is often used to give an approximation of the effect.

`light` : | The MashLight to modify
`ambient` : | The new color value

### mash_light_get_ambient ()

    void                mash_light_get_ambient              (MashLight *light,
                                                             ClutterColor *ambient);

Retrieves the ‘ambient’ color emitted by the light.

`light` : | The MashLight to query
`ambient` : | A return location for the color

### mash_light_set_diffuse ()

    void                mash_light_set_diffuse              (MashLight *light,
                                                             const ClutterColor *diffuse);

Sets the ‘diffuse’ color emitted by the light. The diffuse color is only visible on an object if is facing the light. The orientation of the object is determined per-vertex using the vertex's normal. The diffuse color will be darkened depending on how directly the object faces the light.

`light` : | The MashLight to modify
`diffuse` : | The new color value

### mash_light_get_diffuse ()

    void                mash_light_get_diffuse              (MashLight *light,
                                                             ClutterColor *diffuse);

Retrieves the ‘diffuse’ color emitted by the light.

`light` : | The MashLight to query
`diffuse` : | A return location for the color

### mash_light_set_specular ()

    void                mash_light_set_specular             (MashLight *light,
                                                             const ClutterColor *specular);

Sets the ‘specular’ color emitted by the light. The specular color is used to add highlights to an object wherever the angle to the light is close to the angle that the object is being viewed from. For example, if you were modelling a snooker ball with a bright light above it, this property will allow you add a bright part where the light can directly reflect off the ball into the eye. It is common to set this to a bright white value.

`light` : | The MashLight to modify
`specular` : | The new color value

### mash_light_get_specular ()

    void                mash_light_get_specular             (MashLight *light,
                                                             ClutterColor *specular);

Retrieves the ‘specular’ color emitted by the light.

`light` : | The MashLight to query
`specular` : | A return location for the color

### mash_light_generate_shader ()

    void                mash_light_generate_shader          (MashLight *light,
                                                             GString *uniform_source,
                                                             GString *main_source);

This function is used to generate the shader code required to implement a paraticular. It would not usually need to be called from an application. Instead it is called automatically by MashLightSet.

This function can be overriden in subclasses of MashLight to implement custom lighting algorithms. The function will be called before the first actor that is using the light set is painted whenever it deems that the shader needs to be regenerated. It currently will do this whenever a light is added or removed from the box. The implementation should append any GLSL code to `uniform_source` and `main_source` needed to implement the algorithm.

The implementation should use `mash_light_append_shader()` to append code to either of the shader strings so that it can declare variables that are unique to the individual actor.

The code in `uniform_source` is inserted at the global level of a vertex shader. It is expected that the light will add uniform declarations here. For example, if the light depends on the light's position it could define a uniform for the position like so:

    1
    2
    mash_light_append_shader (light, uniform_source,
                              "uniform vec3 position$;\n");

The code in `main_source` is inserted with the main function of a vertex shader. The snippet added by a light is expected to modify the cogl_color_out attribute according to its algorithm. The snippet can also use the following variables which will be initialized before the snippet is run:

normal: This will be a vec3 which is initialized to the transformed and normalized vertex normal.

eye_coord: This will be a vec3 containing the vertex coordinates in eye-space.

ambient_light: A vec3 uniform containing the ambient light color.

diffuse_light: A vec3 uniform containing the diffuse light color.

specular_light: A vec3 uniform containing the specular light color.

mash_material.ambient: A vec4 containing the current material's ambient color.

mash_material.diffuse: A vec4 containing the current material's diffuse color.

mash_material.specular: A vec4 containing the current material's specular color.

mash_material.emission: A vec4 containing the current material's emission color.

mash_material.shininess: A float containing the current material's shininess value.

mash_normal_matrix: A version of the modelview matrix used to transform normals.

In addition to these variables the shader can use all of the built-in Cogl uniforms. Please see a future version of the Cogl documentation for a description of these.

The implementation should always chain up to the MashLight implementation so that it can declare the built-in uniforms.

`light` : | A MashLight
`uniform_source` : | A location to append uniforms declarations to
`main_source` : | A location to append lighting algorithm snippets to

### mash_light_update_uniforms ()

    void                mash_light_update_uniforms          (MashLight *light,
                                                             CoglHandle program);

This function is used by MashLightSet to implement the lights. It should not need to be called by an application directly.

This function is virtual and can be overriden by subclasses to implement custom lighting algorithms. The function is called during the paint sequence of MashLightSet on every light before any other actors are painted. This gives the light implementation a chance to update any uniforms it may have declared in the override of `mash_light_generate_shader()`.

The program is always made current with `cogl_program_use()` before this method is called so it is safe to directly call `cogl_program_uniform_1f()` and friends to update the uniforms. The `program` handle is passed in so that the program can also be queried to the locations of named uniforms. `mash_light_get_uniform_location()` can be used to make this easier when a uniform is named uniquely using the ‘$’ symbol in `mash_light_append_shader()`.

`light` : | The MashLight that needs updating
`program` : | A CoglProgram containing the uniforms

### mash_light_append_shader ()

    void                mash_light_append_shader            (MashLight *light,
                                                             GString *shader_source,
                                                             const char *snippet);

This is a convenience intended to be used within `mash_light_generate_shader()` to generate shader snippets with actor-specific variable names. It should not generally need to be called by an application unless it is implementing its own lighting algorithms.

The code in `snippet` is appended to `shader_source` but all occurences of the ‘$’ symbol are replaced with a string that is unique to `light` object. This is useful when multiple lights of the same type are added to a single light box. For example, if a light needs to have a position uniform it could make a call like the following:

    1
    2
    mash_light_append_shader (light, uniform_source,
                              "uniform vec3 position$;\n");

The ‘position’ will get translated to something like ‘positiong00000002’.

`light` : | The MashLight which is generating the shader
`shader_source` : | The string to append to
`snippet` : | A snippet of GLSL

### mash_light_get_uniform_location ()

    int                 mash_light_get_uniform_location     (MashLight *light,
                                                             CoglHandle program,
                                                             const char *uniform_name);

This is a convenience intended to be used within `mash_light_update_uniforms()` to help query uniform locations. It should not generally need to be called by an application unless it is implementing its own lighting algorithms.

This is a wrapper around `cogl_program_get_uniform_location()` which appends an actor specific string to the uniform name. This is useful when uniforms have been declared like ‘position$’ within `mash_light_append_shader()`.

`light` : | The MashLight which is generating the shader
`program` : | The program passed in from `mash_light_update_uniforms()`.
`uniform_name` : | The name of a uniform

### mash_light_set_direction_uniform ()

    void                mash_light_set_direction_uniform    (MashLight *light,
                                                             CoglHandle program,
                                                             int uniform_location,
                                                             const float *direction_in);

This is a convenience intended to be used within `mash_light_update_uniforms()` to help set uniforms. It should not generally need to be called by an application unless it is implementing its own lighting algorithms.

This is intended to help when setting a direction uniform. `direction_in` should be an untransformed array of 3 floats representing a vector. The vector will be transformed into eye space according to the inverse transposed matrix of `light` so that it won't change direction for non-uniform scaling transformations.

`light` : | The MashLight which is generating the shader
`uniform_location` : | The location of the uniform
`direction_in` : | The untransformed direction uniform

### mash_light_get_modelview_matrix ()

    void                mash_light_get_modelview_matrix     (MashLight *light,
                                                             CoglMatrix *matrix);

Gets the modelview matrix for the light including all of the transformations for its parent actors. This should be used for updating uniforms that depend on the actor's transformation or position.

`light` : | A MashLight
`matrix` : | The return location for the matrix

## Property Details

### The `"ambient"` property

      "ambient"                  ClutterColor*         : Read / Write

The ambient color emitted by the light.

### The `"diffuse"` property

      "diffuse"                  ClutterColor*         : Read / Write

The diffuse color emitted by the light.

### The `"specular"` property

      "specular"                 ClutterColor*         : Read / Write

The specular color emitted by the light.