Materials

Materials — Fuctions for creating and manipulating materials

Synopsis

                    CoglMaterial;
enum                CoglMaterialFlags;
CoglHandle          cogl_material_new                   (void);
CoglHandle          cogl_material_ref                   (CoglHandle handle);
void                cogl_material_unref                 (CoglHandle handle);
void                cogl_material_set_ambient           (CoglHandle material,
                                                         const CoglColor *ambient);
void                cogl_material_get_ambient           (CoglHandle handle,
                                                         CoglColor *ambient);
void                cogl_material_set_ambient_and_diffuse
                                                        (CoglHandle material,
                                                         const CoglColor *color);
void                cogl_material_set_color             (CoglHandle material,
                                                         const CoglColor *color);
void                cogl_material_set_color4ub          (CoglHandle handle,
                                                         guint8 red,
                                                         guint8 green,
                                                         guint8 blue,
                                                         guint8 alpha);
void                cogl_material_get_color             (CoglHandle handle,
                                                         CoglColor *color);
void                cogl_material_set_diffuse           (CoglHandle material,
                                                         const CoglColor *diffuse);
void                cogl_material_get_diffuse           (CoglHandle handle,
                                                         CoglColor *diffuse);
void                cogl_material_set_emission          (CoglHandle material,
                                                         const CoglColor *emission);
void                cogl_material_get_emission          (CoglHandle handle,
                                                         CoglColor *emission);
void                cogl_material_set_specular          (CoglHandle material,
                                                         const CoglColor *specular);
void                cogl_material_get_specular          (CoglHandle handle,
                                                         CoglColor *specular);
void                cogl_material_set_shininess         (CoglHandle material,
                                                         float shininess);
float               cogl_material_get_shininess         (CoglHandle handle);
void                cogl_set_source                     (CoglHandle material);
enum                CoglMaterialAlphaFunc;
void                cogl_material_set_alpha_test_function
                                                        (CoglHandle material,
                                                         CoglMaterialAlphaFunc alpha_func,
                                                         float alpha_reference);
enum                CoglMaterialBlendFactor;
void                cogl_material_set_blend_factors     (CoglHandle material,
                                                         CoglMaterialBlendFactor src_factor,
                                                         CoglMaterialBlendFactor dst_factor);
                    CoglMaterialLayer;
void                cogl_material_set_layer             (CoglHandle material,
                                                         gint layer_index,
                                                         CoglHandle texture);
void                cogl_material_remove_layer          (CoglHandle material,
                                                         gint layer_index);
enum                CoglMaterialLayerCombineFunc;
void                cogl_material_set_layer_combine_function
                                                        (CoglHandle material,
                                                         gint layer_index,
                                                         CoglMaterialLayerCombineChannels channels,
                                                         CoglMaterialLayerCombineFunc func);
enum                CoglMaterialLayerCombineChannels;
enum                CoglMaterialLayerCombineSrc;
void                cogl_material_set_layer_combine_arg_src
                                                        (CoglHandle material,
                                                         gint layer_index,
                                                         gint argument,
                                                         CoglMaterialLayerCombineChannels channels,
                                                         CoglMaterialLayerCombineSrc src);
enum                CoglMaterialLayerCombineOp;
void                cogl_material_set_layer_combine_arg_op
                                                        (CoglHandle material,
                                                         gint layer_index,
                                                         gint argument,
                                                         CoglMaterialLayerCombineChannels channels,
                                                         CoglMaterialLayerCombineOp op);
void                cogl_material_set_layer_matrix      (CoglHandle material,
                                                         gint layer_index,
                                                         CoglMatrix *matrix);
void                cogl_material_set_layer_alpha_combine
                                                        ();
void                cogl_material_set_layer_rgb_combine ();
gulong              cogl_material_get_cogl_enable_flags (CoglHandle handle);
enum                CoglMaterialFlushOption;
void                cogl_material_flush_gl_state        (CoglHandle material,
                                                         ...);
const GList*        cogl_material_get_layers            (CoglHandle material_handle);
enum                CoglMaterialLayerType;
CoglMaterialLayerType cogl_material_layer_get_type      (CoglHandle layer_handle);
enum                CoglMaterialLayerFlags;
gulong              cogl_material_layer_get_flags       (CoglHandle layer_handle);
CoglHandle          cogl_material_layer_get_texture     (CoglHandle layer_handle);

Description

COGL allows creating and manipulating materials used to fill in geometry. Materials may simply be lighting attributes (such as an ambient and diffuse colour) or might represent one or more textures blended together.

Details

CoglMaterial

typedef struct {
  guint     ref_count;

  gulong    flags;

  /* If no lighting is enabled; this is the basic material color */
  GLfloat   unlit[4];

  /* Standard OpenGL lighting model attributes */
  GLfloat   ambient[4];
  GLfloat   diffuse[4];
  GLfloat   specular[4];
  GLfloat   emission[4];
  GLfloat   shininess;

  /* Determines what fragments are discarded based on their alpha */
  CoglMaterialAlphaFunc alpha_func;
  GLfloat		alpha_func_reference;

  /* Determines how this material is blended with other primitives */
  CoglMaterialBlendFactor blend_src_factor;
  CoglMaterialBlendFactor blend_dst_factor;

  GList	   *layers;
} CoglMaterial;


enum CoglMaterialFlags

typedef enum _CoglMaterialFlags
{
  COGL_MATERIAL_FLAG_ENABLE_BLEND	    = 1L<<0,
  COGL_MATERIAL_FLAG_SHOWN_SAMPLER_WARNING  = 1L<<1,
  COGL_MATERIAL_FLAG_DIRTY	            = 1L<<2,
  COGL_MATERIAL_FLAG_LAYERS_DIRTY	    = 1L<<3,
  COGL_MATERIAL_FLAG_DEFAULT_COLOR          = 1L<<4,
  COGL_MATERIAL_FLAG_DEFAULT_GL_MATERIAL    = 1L<<5,
  COGL_MATERIAL_FLAG_DEFAULT_ALPHA_FUNC     = 1L<<6,
  COGL_MATERIAL_FLAG_DEFAULT_BLEND_FUNC     = 1L<<7
} CoglMaterialFlags;


cogl_material_new ()

CoglHandle          cogl_material_new                   (void);

Allocates and initializes a blank white material

Returns :

a handle to the new material

cogl_material_ref ()

CoglHandle          cogl_material_ref                   (CoglHandle handle);

Increment the reference count for a cogl material.

handle :

a CoglHandle.

Returns :

the handle. Since 1.0

cogl_material_unref ()

void                cogl_material_unref                 (CoglHandle handle);

Decrement the reference count for a cogl material.

Since 1.0

handle :

a CoglHandle.

cogl_material_set_ambient ()

void                cogl_material_set_ambient           (CoglHandle material,
                                                         const CoglColor *ambient);

Exposing the standard OpenGL lighting model; this function sets the material's ambient color. The ambient color affects the overall color of the object. Since the diffuse color will be intense when the light hits the surface directly, the ambient will most aparent where the light hits at a slant.

The default value is (0.2, 0.2, 0.2, 1.0)

Since 1.0

material :

A CoglMaterial object

ambient :

The components of the desired ambient color

cogl_material_get_ambient ()

void                cogl_material_get_ambient           (CoglHandle handle,
                                                         CoglColor *ambient);

This retrieves the materials current ambient color.

Since 1.0

handle :

ambient :

The location to store the ambient color

cogl_material_set_ambient_and_diffuse ()

void                cogl_material_set_ambient_and_diffuse
                                                        (CoglHandle material,
                                                         const CoglColor *color);

This is a convenience for setting the diffuse and ambient color of the material at the same time.

The default ambient color is (0.2, 0.2, 0.2, 1.0) The default diffuse color is (0.8, 0.8, 0.8, 1.0)

Since 1.0

material :

A CoglMaterial object

color :

The components of the desired ambient and diffuse colors

cogl_material_set_color ()

void                cogl_material_set_color             (CoglHandle material,
                                                         const CoglColor *color);

This is the basic color of the material, used when no lighting is enabled.

The default value is (1.0, 1.0, 1.0, 1.0)

Since 1.0

material :

A CoglMaterial object

color :


cogl_material_set_color4ub ()

void                cogl_material_set_color4ub          (CoglHandle handle,
                                                         guint8 red,
                                                         guint8 green,
                                                         guint8 blue,
                                                         guint8 alpha);

handle :

red :

green :

blue :

alpha :


cogl_material_get_color ()

void                cogl_material_get_color             (CoglHandle handle,
                                                         CoglColor *color);

This retrieves the current material color.

Since 1.0

handle :

color :

The location to store the color

cogl_material_set_diffuse ()

void                cogl_material_set_diffuse           (CoglHandle material,
                                                         const CoglColor *diffuse);

Exposing the standard OpenGL lighting model; this function sets the material's diffuse color. The diffuse color is most intense where the light hits the surface directly; perpendicular to the surface.

The default value is (0.8, 0.8, 0.8, 1.0)

Since 1.0

material :

A CoglMaterial object

diffuse :

The components of the desired diffuse color

cogl_material_get_diffuse ()

void                cogl_material_get_diffuse           (CoglHandle handle,
                                                         CoglColor *diffuse);

This retrieves the materials current diffuse color.

Since 1.0

handle :

diffuse :

The location to store the diffuse color

cogl_material_set_emission ()

void                cogl_material_set_emission          (CoglHandle material,
                                                         const CoglColor *emission);

Exposing the standard OpenGL lighting model; this function sets the material's emissive color. It will look like the surface is a light source emitting this color.

The default value is (0.0, 0.0, 0.0, 1.0)

Since 1.0

material :

A CoglMaterial object

emission :

The components of the desired emissive color

cogl_material_get_emission ()

void                cogl_material_get_emission          (CoglHandle handle,
                                                         CoglColor *emission);

This retrieves the materials current emission color.

Since 1.0

handle :

emission :

The location to store the emission color

cogl_material_set_specular ()

void                cogl_material_set_specular          (CoglHandle material,
                                                         const CoglColor *specular);

Exposing the standard OpenGL lighting model; this function sets the material's specular color. The intensity of the specular color depends on the viewport position, and is brightest along the lines of reflection.

The default value is (0.0, 0.0, 0.0, 1.0)

Since 1.0

material :

A CoglMaterial object

specular :

The components of the desired specular color

cogl_material_get_specular ()

void                cogl_material_get_specular          (CoglHandle handle,
                                                         CoglColor *specular);

This retrieves the materials current specular color.

Since 1.0

handle :

specular :

The location to store the specular color

cogl_material_set_shininess ()

void                cogl_material_set_shininess         (CoglHandle material,
                                                         float shininess);

This function sets the materials shininess which determines how specular highlights are calculated. A higher shininess will produce smaller brigher highlights.

The default value is 0.0

Since 1.0

material :

A CoglMaterial object shininess: The desired shininess; range: [0.0, 1.0]

shininess :


cogl_material_get_shininess ()

float               cogl_material_get_shininess         (CoglHandle handle);

This retrieves the materials current emission color.

handle :

Returns :

The materials current shininess value Since 1.0

cogl_set_source ()

void                cogl_set_source                     (CoglHandle material);

This function sets the source material that will be used to fill subsequent geometry emitted via the cogl API.

Note: in the future we may add the ability to set a front facing material, and a back facing material, in which case this function will set both to the same.

Since 1.0

material :

A CoglMaterial object

enum CoglMaterialAlphaFunc

typedef enum _CoglMaterialAlphaFunc
{
  COGL_MATERIAL_ALPHA_FUNC_NEVER    = GL_NEVER,
  COGL_MATERIAL_ALPHA_FUNC_LESS	    = GL_LESS,
  COGL_MATERIAL_ALPHA_FUNC_EQUAL    = GL_EQUAL,
  COGL_MATERIAL_ALPHA_FUNC_LEQUAL   = GL_LEQUAL,
  COGL_MATERIAL_ALPHA_FUNC_GREATER  = GL_GREATER,
  COGL_MATERIAL_ALPHA_FUNC_NOTEQUAL = GL_NOTEQUAL,
  COGL_MATERIAL_ALPHA_FUNC_GEQUAL   = GL_GEQUAL,
  COGL_MATERIAL_ALPHA_FUNC_ALWAYS   = GL_ALWAYS
} CoglMaterialAlphaFunc;

Alpha testing happens before blending primitives with the framebuffer and gives an opportunity to discard fragments based on a comparison with the incoming alpha value and a reference alpha value. The CoglMaterialAlphaFunc determines how the comparison is done.

COGL_MATERIAL_ALPHA_FUNC_NEVER

Never let the fragment through.

COGL_MATERIAL_ALPHA_FUNC_LESS

Let the fragment through if the incoming alpha value is less than the reference alpha value.

COGL_MATERIAL_ALPHA_FUNC_EQUAL

Let the fragment through if the incoming alpha value equals the reference alpha value.

COGL_MATERIAL_ALPHA_FUNC_LEQUAL

Let the fragment through if the incoming alpha value is less than or equal to the reference alpha value.

COGL_MATERIAL_ALPHA_FUNC_GREATER

Let the fragment through if the incoming alpha value is greater than the reference alpha value.

COGL_MATERIAL_ALPHA_FUNC_NOTEQUAL

Let the fragment through if the incoming alpha value does not equal the reference alpha value.

COGL_MATERIAL_ALPHA_FUNC_GEQUAL

Let the fragment through if the incoming alpha value is greater than or equal to the reference alpha value.

COGL_MATERIAL_ALPHA_FUNC_ALWAYS

Always let the fragment through.

cogl_material_set_alpha_test_function ()

void                cogl_material_set_alpha_test_function
                                                        (CoglHandle material,
                                                         CoglMaterialAlphaFunc alpha_func,
                                                         float alpha_reference);

Before a primitive is blended with the framebuffer, it goes through an alpha test stage which lets you discard fragments based on the current alpha value. This function lets you change the function used to evaluate the alpha channel, and thus determine which fragments are discarded and which continue on to the blending stage.

The default is COGL_MATERIAL_ALPHA_FUNC_ALWAYS

Since 1.0

material :

A CoglMaterial object

alpha_func :

A CoglMaterialAlphaFunc constant

alpha_reference :

A reference point that the chosen alpha function uses to compare incoming fragments to.

enum CoglMaterialBlendFactor

typedef enum _CoglMaterialBlendFactor
{
  COGL_MATERIAL_BLEND_FACTOR_ZERO		  = GL_ZERO,
  COGL_MATERIAL_BLEND_FACTOR_ONE		  = GL_ONE,
  COGL_MATERIAL_BLEND_FACTOR_SRC_COLOR		  = GL_SRC_COLOR,
  COGL_MATERIAL_BLEND_FACTOR_DST_COLOR		  = GL_DST_COLOR,
  COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_SRC_COLOR  = GL_ONE_MINUS_SRC_COLOR,
  COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_DST_COLOR  = GL_ONE_MINUS_DST_COLOR,
  COGL_MATERIAL_BLEND_FACTOR_SRC_ALPHA		  = GL_SRC_ALPHA,
  COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA  = GL_ONE_MINUS_SRC_ALPHA,
  COGL_MATERIAL_BLEND_FACTOR_DST_ALPHA		  = GL_DST_ALPHA,
  COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_DST_ALPHA  = GL_ONE_MINUS_DST_ALPHA,
  COGL_MATERIAL_BLEND_FACTOR_SRC_ALPHA_SATURATE	  = GL_SRC_ALPHA_SATURATE,
} CoglMaterialBlendFactor;

Blending occurs after the alpha test function, and combines fragments with the framebuffer.

A fixed function is used to determine the blended color, which is based on the incoming source color of your fragment (Rs, Gs, Bs, As), a source factor (Sr, Sg, Sb, Sa), a destination color (Rd, Rg, Rb, Ra) and a destination factor (Dr, Dg, Db, Da), and is given by these equations:

R = Rs*Sr + Rd*Dr
G = Gs*Sg + Gd*Dg
B = Bs*Sb + Bd*Db
A = As*Sa + Ad*Da

All factors have a range [0, 1]

The factors are selected with the following constants:

COGL_MATERIAL_BLEND_FACTOR_ZERO

(0, 0, 0, 0)

COGL_MATERIAL_BLEND_FACTOR_ONE

(1, 1, 1, 1)

COGL_MATERIAL_BLEND_FACTOR_SRC_COLOR

(Rs, Gs, Bs, As)

COGL_MATERIAL_BLEND_FACTOR_DST_COLOR

(Rd, Gd, Bd, Ad)

COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_SRC_COLOR

(1-Rs, 1-Gs, 1-Bs, 1-As)

COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_DST_COLOR

(1-Rd, 1-Gd, 1-Bd, 1-Ad)

COGL_MATERIAL_BLEND_FACTOR_SRC_ALPHA

(As, As, As, As)

COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA

(1-As, 1-As, 1-As, 1-As)

COGL_MATERIAL_BLEND_FACTOR_DST_ALPHA

(Ad, Ad, Ad, Ad)

COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_DST_ALPHA

(1-Ad, 1-Ad, 1-Ad, 1-Ad)

COGL_MATERIAL_BLEND_FACTOR_SRC_ALPHA_SATURATE

(f,f,f,1) where f=MIN(As,1-Ad)

cogl_material_set_blend_factors ()

void                cogl_material_set_blend_factors     (CoglHandle material,
                                                         CoglMaterialBlendFactor src_factor,
                                                         CoglMaterialBlendFactor dst_factor);

This function lets you control how primitives using this material will get blended with the contents of your framebuffer. The blended RGBA components are calculated like this:

(RsSr+RdDr, GsSg+GdDg, BsSb+BsSb, AsSa+AdDa)

Where (Rs,Gs,Bs,As) represents your source - material- color, (Rd,Gd,Bd,Ad) represents your destination - framebuffer - color, (Sr,Sg,Sb,Sa) represents your source blend factor and (Dr,Dg,Db,Da) represents you destination blend factor.

All factors lie in the range [0,1] and incoming color components are also normalized to the range [0,1]

Since 1.0

material :

A CoglMaterial object

src_factor :

Chooses the CoglMaterialBlendFactor you want plugged in to the blend equation.

dst_factor :

Chooses the CoglMaterialBlendFactor you want plugged in to the blend equation.

CoglMaterialLayer

typedef struct {
  guint	       ref_count;
  guint	       index;	/*!< lowest index is blended first then others
			     on top */
  gulong       flags;
  CoglHandle   texture;	/*!< The texture for this layer, or COGL_INVALID_HANDLE
			     for an empty layer */

  /* Determines how the color of individual texture fragments
   * are calculated. */
  CoglMaterialLayerCombineFunc texture_combine_rgb_func;
  CoglMaterialLayerCombineSrc texture_combine_rgb_src[3];
  CoglMaterialLayerCombineOp texture_combine_rgb_op[3];

  CoglMaterialLayerCombineFunc texture_combine_alpha_func;
  CoglMaterialLayerCombineSrc texture_combine_alpha_src[3];
  CoglMaterialLayerCombineOp texture_combine_alpha_op[3];

  /* TODO: Support purely GLSL based material layers */

  CoglMatrix matrix;
} CoglMaterialLayer;


cogl_material_set_layer ()

void                cogl_material_set_layer             (CoglHandle material,
                                                         gint layer_index,
                                                         CoglHandle texture);

In addition to the standard OpenGL lighting model a Cogl material may have one or more layers comprised of textures that can be blended together in order, with a number of different texture combine modes. This function defines a new texture layer.

The index values of multiple layers do not have to be consecutive; it is only their relative order that is important.

XXX: In the future, we may define other types of material layers, such as purely GLSL based layers.

Since 1.0

material :

A CoglMaterial object

layer_index :

texture :


cogl_material_remove_layer ()

void                cogl_material_remove_layer          (CoglHandle material,
                                                         gint layer_index);

material :

layer_index :


enum CoglMaterialLayerCombineFunc

typedef enum _CoglMaterialLayerCombineFunc
{
  COGL_MATERIAL_LAYER_COMBINE_FUNC_REPLACE    = GL_REPLACE,
  COGL_MATERIAL_LAYER_COMBINE_FUNC_MODULATE   = GL_MODULATE,
  COGL_MATERIAL_LAYER_COMBINE_FUNC_ADD	      = GL_ADD,
  COGL_MATERIAL_LAYER_COMBINE_FUNC_ADD_SIGNED = GL_ADD_SIGNED,
  COGL_MATERIAL_LAYER_COMBINE_FUNC_INTERPOLATE = GL_INTERPOLATE,
  COGL_MATERIAL_LAYER_COMBINE_FUNC_SUBTRACT   = GL_SUBTRACT,
  COGL_MATERIAL_LAYER_COMBINE_FUNC_DOT3_RGB   = GL_DOT3_RGB,
  COGL_MATERIAL_LAYER_COMBINE_FUNC_DOT3_RGBA  = GL_DOT3_RGBA
} CoglMaterialLayerCombineFunc;

A material may comprise of 1 or more layers that can be combined using a number of different functions. By default layers are modulated, which is to say the components of the current source layer S are simply multipled together with the combined results of the previous layer P like this:

(Rs*Rp, Gs*Gp, Bs*Bp, As*Ap)

For more advanced techniques, Cogl exposes the fixed function texture combining capabilities of your GPU to give you greater control.

COGL_MATERIAL_LAYER_COMBINE_FUNC_REPLACE

Arg0

COGL_MATERIAL_LAYER_COMBINE_FUNC_MODULATE

Arg0 x Arg1

COGL_MATERIAL_LAYER_COMBINE_FUNC_ADD

Arg0 + Arg1

COGL_MATERIAL_LAYER_COMBINE_FUNC_ADD_SIGNED

Arg0 + Arg1 - 0.5

COGL_MATERIAL_LAYER_COMBINE_FUNC_INTERPOLATE

Arg0 x Arg + Arg1 x (1-Arg2)

COGL_MATERIAL_LAYER_COMBINE_FUNC_SUBTRACT

Arg0 - Arg1

COGL_MATERIAL_LAYER_COMBINE_FUNC_DOT3_RGB

4 x ((Arg0r - 0.5) x (Arg1r - 0.5)) +

COGL_MATERIAL_LAYER_COMBINE_FUNC_DOT3_RGBA

((Arg0b - 0.5) x (Arg1b - 0.5)) +

cogl_material_set_layer_combine_function ()

void                cogl_material_set_layer_combine_function
                                                        (CoglHandle material,
                                                         gint layer_index,
                                                         CoglMaterialLayerCombineChannels channels,
                                                         CoglMaterialLayerCombineFunc func);

There are three basic steps to describing how a layer should be combined:

  1. Choose a function.
  2. Specify the source color for each argument of the chosen function. (Note the functions don't all take the same number of arguments)
  3. Specify an operator for each argument that can modify the corresponding source color before the function is applied.

Cogl optionally lets you describe 2 seperate combine modes for a single layer; 1 for the RGB components, and 1 for the Alpha component, so in this case you would repeat the 3 steps for each channel selector.

(Note: you can't have different modes for each channel, so if you need more control you will need to use a glsl fragment shader)

For example here is how you could elect to use the ADD function for all components of layer 1 in your material:

//Step 1: Choose a function. Note the ADD function takes 2 arguments...
cogl_material_set_layer_combine_function (material,
                                          1,
                                          COGL_MATERIAL_LAYER_COMBINE_CHANNELS_RGBA)
                                          COGL_MATERIAL_LAYER_COMBINE_FUNC_ADD);
//Step 2: Specify the source color for the 2 ADD function arguments...
cogl_material_set_layer_combine_arg_src (material,
                                         1,//layer index
                                         0,//argument index
                                         COGL_MATERIAL_LAYER_COMBINE_SRC_PREVIOUS);
cogl_material_set_layer_combine_arg_src (material,
                                         1,//layer index
                                         1,//argument index
                                         COGL_MATERIAL_LAYER_COMBINE_CHANNELS_RGBA)
                                         COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE);
//Step 3: Specify the operators used to modify the arguments...
cogl_material_set_layer_combine_arg_op (material,
                                        1,//layer index
                                        0,//argument index
                                        COGL_MATERIAL_LAYER_COMBINE_CHANNELS_RGBA,
                                        COGL_MATERIAL_LAYER_COMBINE_OP_SRC_COLOR);
cogl_material_set_layer_combine_arg_op (material,
                                        1,//layer index
                                        1,//argument index
                                        COGL_MATERIAL_LAYER_COMBINE_CHANNELS_RGBA,
                                        COGL_MATERIAL_LAYER_COMBINE_OP_SRC_COLOR);

material :

A CoglMaterial object

layer_index :

Specifies the layer whos combine mode you want to modify

channels :

Specifies which channels combine mode you want to modify (RGB, ALPHA, or RGBA)

func :

Specifies the function you want to use for combining fragments of the specified layer with the results of previously combined layers.

enum CoglMaterialLayerCombineChannels

typedef enum _CoglMaterialLayerCombineChannels
{
  COGL_MATERIAL_LAYER_COMBINE_CHANNELS_RGB,
  COGL_MATERIAL_LAYER_COMBINE_CHANNELS_ALPHA,
  COGL_MATERIAL_LAYER_COMBINE_CHANNELS_RGBA
} CoglMaterialLayerCombineChannels;

Cogl optionally lets you describe 2 seperate combine modes for a single layer; 1 for the RGB components, and 1 for the Alpha component, so in this case you would repeat the 3 steps documented with the cogl_material_set_layer_combine_function function for each channel selector.

(Note: you can't have different modes for each channel, so if you need more control you will need to use a glsl fragment shader)

COGL_MATERIAL_LAYER_COMBINE_CHANNELS_RGB

Modify the function or argument src/op for the RGB components of a layer

COGL_MATERIAL_LAYER_COMBINE_CHANNELS_ALPHA

Modify the function or argument src/op for the Alpha component of a layer

COGL_MATERIAL_LAYER_COMBINE_CHANNELS_RGBA

Modify the function or argument src/op for all the components of a layer

enum CoglMaterialLayerCombineSrc

typedef enum _CoglMaterialLayerCombineSrc
{
  COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE = GL_TEXTURE,

  /* Can we find a nicer way... */
  COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE0 = GL_TEXTURE0,
  COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE1 = GL_TEXTURE1,
  COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE2 = GL_TEXTURE2,
  COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE3 = GL_TEXTURE3,
  COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE4 = GL_TEXTURE4,
  COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE5 = GL_TEXTURE5,
  COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE6 = GL_TEXTURE6,
  COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE7 = GL_TEXTURE7,
  /* .. who would ever need more than 8 texture layers.. :-) */

  COGL_MATERIAL_LAYER_COMBINE_SRC_CONSTANT	= GL_CONSTANT,
  COGL_MATERIAL_LAYER_COMBINE_SRC_PRIMARY_COLOR = GL_PRIMARY_COLOR,
  COGL_MATERIAL_LAYER_COMBINE_SRC_PREVIOUS	= GL_PREVIOUS
} CoglMaterialLayerCombineSrc;

Note for the constants COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE0..n the numbers may not correspond to the indices you choose for your layers since your layer indices don't need to be contiguous. If you need to use these it would probably be sensible to ensure the layer indices do infact correspond.

COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE

The fragment color of the current texture layer

COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE0

The fragment color of texture unit 0

COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE1

The fragment color of texture unit 1

COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE2

The fragment color of texture unit 2..7

COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE3

COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE4

COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE5

COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE6

COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE7

COGL_MATERIAL_LAYER_COMBINE_SRC_CONSTANT

A fixed constant color (TODO: no API yet to specify the actual color!)

COGL_MATERIAL_LAYER_COMBINE_SRC_PRIMARY_COLOR

The basic color of the primitive ignoring texturing

COGL_MATERIAL_LAYER_COMBINE_SRC_PREVIOUS

The result of combining all previous layers

cogl_material_set_layer_combine_arg_src ()

void                cogl_material_set_layer_combine_arg_src
                                                        (CoglHandle material,
                                                         gint layer_index,
                                                         gint argument,
                                                         CoglMaterialLayerCombineChannels channels,
                                                         CoglMaterialLayerCombineSrc src);

material :

A CoglMaterial object

layer_index :

argument :

channels :

src :


enum CoglMaterialLayerCombineOp

typedef enum _CoglMaterialLayerCombineOp
{
  COGL_MATERIAL_LAYER_COMBINE_OP_SRC_COLOR	     = GL_SRC_COLOR,
  COGL_MATERIAL_LAYER_COMBINE_OP_ONE_MINUS_SRC_COLOR = GL_ONE_MINUS_SRC_COLOR,

  COGL_MATERIAL_LAYER_COMBINE_OP_SRC_ALPHA	     = GL_SRC_ALPHA,
  COGL_MATERIAL_LAYER_COMBINE_OP_ONE_MINUS_SRC_ALPHA = GL_ONE_MINUS_SRC_ALPHA
} CoglMaterialLayerCombineOp;


cogl_material_set_layer_combine_arg_op ()

void                cogl_material_set_layer_combine_arg_op
                                                        (CoglHandle material,
                                                         gint layer_index,
                                                         gint argument,
                                                         CoglMaterialLayerCombineChannels channels,
                                                         CoglMaterialLayerCombineOp op);

material :

A CoglMaterial object

layer_index :

argument :

channels :

op :


cogl_material_set_layer_matrix ()

void                cogl_material_set_layer_matrix      (CoglHandle material,
                                                         gint layer_index,
                                                         CoglMatrix *matrix);

This function lets you set a matrix that can be used to e.g. translate and rotate a single layer of a material used to fill your geometry.

material :

A CoglMaterial object

layer_index :

matrix :


cogl_material_set_layer_alpha_combine ()

void                cogl_material_set_layer_alpha_combine
                                                        ();


cogl_material_set_layer_rgb_combine ()

void                cogl_material_set_layer_rgb_combine ();


cogl_material_get_cogl_enable_flags ()

gulong              cogl_material_get_cogl_enable_flags (CoglHandle handle);

This determines what flags need to be passed to cogl_enable before this material can be used. Normally you shouldn't need to use this function directly since Cogl will do this internally, but if you are developing custom primitives directly with OpenGL you may want to use this.

Note: This API is hopfully just a stop-gap solution. Ideally cogl_enable will be replaced.

handle :

Returns :


enum CoglMaterialFlushOption

typedef enum _CoglMaterialFlushOption
{
  COGL_MATERIAL_FLUSH_FALLBACK_MASK = 1,
  COGL_MATERIAL_FLUSH_DISABLE_MASK,
  COGL_MATERIAL_FLUSH_LAYER0_OVERRIDE,
} CoglMaterialFlushOption;

COGL_MATERIAL_FLUSH_FALLBACK_MASK

Follow this by a guin32 mask of the layers that can't be supported with the user supplied texture and need to be replaced with fallback textures. (1 = fallback, and the least significant bit = layer 0)

COGL_MATERIAL_FLUSH_DISABLE_MASK

Follow this by a guint32 mask of the layers that you want to completly disable texturing for (1 = fallback, and the least significant bit = layer 0)

COGL_MATERIAL_FLUSH_LAYER0_OVERRIDE

Follow this by a GLuint OpenGL texture name to override the texture used for layer 0 of the material. This is intended for dealing with sliced textures where you will need to point to each of the texture slices in turn when drawing your geometry. Passing a value of 0 is the same as not passing the option at all.

cogl_material_flush_gl_state ()

void                cogl_material_flush_gl_state        (CoglHandle material,
                                                         ...);

This function commits the state of the specified CoglMaterial - including the texture state for all the layers - to the OpenGL[ES] driver.

Normally you shouldn't need to use this function directly, but if you are developing a custom primitive using raw OpenGL that works with CoglMaterials, then you may want to use this function.

Since 1.0

material :

A CoglMaterial object

... :

A NULL terminated list of (CoglMaterialFlushOption, data) pairs

cogl_material_get_layers ()

const GList*        cogl_material_get_layers            (CoglHandle material_handle);

This function lets you access a materials internal list of layers for iteration.

Note: Normally you shouldn't need to use this function directly since Cogl will do this internally, but if you are developing custom primitives directly with OpenGL, you will need to iterate the layers that you want to texture with.

Note: This function may return more layers than OpenGL can use at once so it's your responsability limit yourself to CGL_MAX_COMBINED_TEXTURE_IMAGE_UNITS.

Note: It's a bit out of the ordinary to return a const GList *, but it was considered sensible to try and avoid list manipulation for every primitive emitted in a scene, every frame.

material_handle :

Returns :


enum CoglMaterialLayerType

typedef enum _CoglMaterialLayerType
{
  COGL_MATERIAL_LAYER_TYPE_TEXTURE
} CoglMaterialLayerType;

COGL_MATERIAL_LAYER_TYPE_TEXTURE

The layer represents a CoglTexture

cogl_material_layer_get_type ()

CoglMaterialLayerType cogl_material_layer_get_type      (CoglHandle layer_handle);

Currently there is only one type of layer defined: COGL_MATERIAL_LAYER_TYPE_TEXTURE, but considering we may add purely GLSL based layers in the future, you should write code that checks the type first.

Note: Normally you shouldn't need to use this function directly since Cogl will do this internally, but if you are developing custom primitives directly with OpenGL, you will need to iterate the layers that you want to texture with, and thus should be checking the layer types.

layer_handle :

Returns :


enum CoglMaterialLayerFlags

typedef enum _CoglMaterialLayerFlags
{
  COGL_MATERIAL_LAYER_FLAG_HAS_USER_MATRIX	= 1L<<0
} CoglMaterialLayerFlags;


cogl_material_layer_get_flags ()

gulong              cogl_material_layer_get_flags       (CoglHandle layer_handle);

This lets you get a number of flag attributes about the layer. Normally you shouldn't need to use this function directly since Cogl will do this internally, but if you are developing custom primitives directly with OpenGL you may need this.

layer_handle :

A CoglMaterial layer object

Returns :


cogl_material_layer_get_texture ()

CoglHandle          cogl_material_layer_get_texture     (CoglHandle layer_handle);

This lets you extract a CoglTexture handle for a specific layer. Normally you shouldn't need to use this function directly since Cogl will do this internally, but if you are developing custom primitives directly with OpenGL you may need this.

Note: In the future, we may support purely GLSL based layers which will likley return COGL_INVALID_HANDLE if you try to get the texture. Considering this, you should always call cogl_material_layer_get_type first, to check it is of type COGL_MATERIAL_LAYER_TYPE_TEXTURE.

layer_handle :

A CoglMaterial layer object

Returns :