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);
};

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.

mash_light_get_ambient ()

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

Retrieves the ‘ambient’ color emitted by the light.

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.

mash_light_get_diffuse ()

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

Retrieves the ‘diffuse’ color emitted by the light.

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.

mash_light_get_specular ()

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

Retrieves the ‘specular’ color emitted by the light.

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.

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().

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’.

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().

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.

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.

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.