![]() |
![]() |
![]() |
COGL 0.9.3 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
CoglHandle cogl_material_new (void); CoglHandle cogl_material_ref (CoglHandle handle); void cogl_material_unref (CoglHandle handle); gboolean cogl_is_material (CoglHandle handle); void cogl_material_set_color (CoglHandle material, const CoglColor *color); void cogl_material_set_color4ub (CoglHandle material, guint8 red, guint8 green, guint8 blue, guint8 alpha); void cogl_material_set_color4f (CoglHandle material, float red, float green, float blue, float alpha); void cogl_material_get_color (CoglHandle material, CoglColor *color); void cogl_material_set_ambient (CoglHandle material, const CoglColor *ambient); void cogl_material_get_ambient (CoglHandle material, CoglColor *ambient); void cogl_material_set_diffuse (CoglHandle material, const CoglColor *diffuse); void cogl_material_get_diffuse (CoglHandle material, CoglColor *diffuse); void cogl_material_set_ambient_and_diffuse (CoglHandle material, const CoglColor *color); void cogl_material_set_emission (CoglHandle material, const CoglColor *emission); void cogl_material_get_emission (CoglHandle material, CoglColor *emission); void cogl_material_set_specular (CoglHandle material, const CoglColor *specular); void cogl_material_get_specular (CoglHandle material, CoglColor *specular); void cogl_material_set_shininess (CoglHandle material, float shininess); float cogl_material_get_shininess (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); 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);
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.
CoglHandle cogl_material_new (void);
Allocates and initializes a blank white material
Returns : |
a handle to the new material |
CoglHandle cogl_material_ref (CoglHandle handle);
Increment the reference count for a cogl material.
|
a CoglHandle .
|
Returns : |
the handle .
Since 1.0
|
void cogl_material_unref (CoglHandle handle);
Decrement the reference count for a cogl material.
Since 1.0
|
a CoglHandle .
|
gboolean cogl_is_material (CoglHandle handle);
Gets whether the given handle references an existing material object.
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
|
A CoglMaterial object |
|
The components of the color |
void cogl_material_set_color4ub (CoglHandle material, guint8 red, guint8 green, guint8 blue, guint8 alpha);
This is the basic color of the material, used when no lighting is enabled.
The default value is (0xff, 0xff, 0xff, 0xff)
Since 1.0
|
A CoglMaterial object |
|
The red component |
|
The green component |
|
The blue component |
|
The alpha component |
void cogl_material_set_color4f (CoglHandle material, float red, float green, float blue, float alpha);
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
|
A CoglMaterial object |
|
The red component |
|
The green component |
|
The blue component |
|
The alpha component |
void cogl_material_get_color (CoglHandle material, CoglColor *color);
This retrieves the current material color.
Since 1.0
|
A CoglMaterial object |
|
The location to store the color |
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
|
A CoglMaterial object |
|
The components of the desired ambient color |
void cogl_material_get_ambient (CoglHandle material, CoglColor *ambient);
This retrieves the materials current ambient color.
Since 1.0
|
A CoglMaterial object |
|
The location to store the ambient color |
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
|
A CoglMaterial object |
|
The components of the desired diffuse color |
void cogl_material_get_diffuse (CoglHandle material, CoglColor *diffuse);
This retrieves the materials current diffuse color.
Since 1.0
|
A CoglMaterial object |
|
The location to store the diffuse color |
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
|
A CoglMaterial object |
|
The components of the desired ambient and diffuse colors |
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
|
A CoglMaterial object |
|
The components of the desired emissive color |
void cogl_material_get_emission (CoglHandle material, CoglColor *emission);
This retrieves the materials current emission color.
Since 1.0
|
A CoglMaterial object |
|
The location to store the emission color |
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
|
A CoglMaterial object |
|
The components of the desired specular color |
void cogl_material_get_specular (CoglHandle material, CoglColor *specular);
This retrieves the materials current specular color.
Since 1.0
|
A CoglMaterial object |
|
The location to store the specular color |
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
|
A CoglMaterial object shininess: The desired shininess; range: [0.0, 1.0] |
|
float cogl_material_get_shininess (CoglHandle material);
This retrieves the materials current emission color.
|
A CoglMaterial object |
Returns : |
The materials current shininess value Since 1.0 |
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.
Never let the fragment through. | |
Let the fragment through if the incoming alpha value is less than the reference alpha value. | |
Let the fragment through if the incoming alpha value equals the reference alpha value. | |
Let the fragment through if the incoming alpha value is less than or equal to the reference alpha value. | |
Let the fragment through if the incoming alpha value is greater than the reference alpha value. | |
Let the fragment through if the incoming alpha value does not equal the reference alpha value. | |
Let the fragment through if the incoming alpha value is greater than or equal to the reference alpha value. | |
Always let the fragment through. |
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
|
A CoglMaterial object |
|
A CoglMaterialAlphaFunc constant
|
|
A reference point that the chosen alpha function uses to compare incoming fragments to. |
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:
(0, 0, 0, 0) | |
(1, 1, 1, 1) | |
(Rs, Gs, Bs, As) | |
(Rd, Gd, Bd, Ad) | |
(1-Rs, 1-Gs, 1-Bs, 1-As) | |
(1-Rd, 1-Gd, 1-Bd, 1-Ad) | |
(As, As, As, As) | |
(1-As, 1-As, 1-As, 1-As) | |
(Ad, Ad, Ad, Ad) | |
(1-Ad, 1-Ad, 1-Ad, 1-Ad) | |
(f,f,f,1) where f=MIN(As,1-Ad) |
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
|
A CoglMaterial object |
|
Chooses the CoglMaterialBlendFactor you want plugged in to
the blend equation.
|
|
Chooses the CoglMaterialBlendFactor you want plugged in to
the blend equation.
|
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
|
A CoglMaterial object |
|
|
|
void cogl_material_remove_layer (CoglHandle material, gint layer_index);
|
|
|
typedef enum _CoglMaterialLayerCombineFunc { COGL_MATERIAL_LAYER_COMBINE_FUNC_REPLACE = CGL_REPLACE, COGL_MATERIAL_LAYER_COMBINE_FUNC_MODULATE = CGL_MODULATE, COGL_MATERIAL_LAYER_COMBINE_FUNC_ADD = CGL_ADD, COGL_MATERIAL_LAYER_COMBINE_FUNC_ADD_SIGNED = CGL_ADD_SIGNED, COGL_MATERIAL_LAYER_COMBINE_FUNC_INTERPOLATE = CGL_INTERPOLATE, COGL_MATERIAL_LAYER_COMBINE_FUNC_SUBTRACT = CGL_SUBTRACT, COGL_MATERIAL_LAYER_COMBINE_FUNC_DOT3_RGB = CGL_DOT3_RGB, COGL_MATERIAL_LAYER_COMBINE_FUNC_DOT3_RGBA = CGL_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.
Arg0 | |
Arg0 x Arg1 | |
Arg0 + Arg1 | |
Arg0 + Arg1 - 0.5 | |
Arg0 x Arg + Arg1 x (1-Arg2) | |
Arg0 - Arg1 | |
4 x ((Arg0r - 0.5) x (Arg1r - 0.5)) + | |
((Arg0b - 0.5) x (Arg1b - 0.5)) + |
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:
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);
|
A CoglMaterial object |
|
Specifies the layer whos combine mode you want to modify |
|
Specifies which channels combine mode you want to modify (RGB, ALPHA, or RGBA) |
|
Specifies the function you want to use for combining fragments of the specified layer with the results of previously combined layers. |
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)
Modify the function or argument src/op for the RGB components of a layer | |
Modify the function or argument src/op for the Alpha component of a layer | |
Modify the function or argument src/op for all the components of a layer |
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 = CGL_CONSTANT, COGL_MATERIAL_LAYER_COMBINE_SRC_PRIMARY_COLOR = CGL_PRIMARY_COLOR, COGL_MATERIAL_LAYER_COMBINE_SRC_PREVIOUS = CGL_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.
The fragment color of the current texture layer | |
The fragment color of texture unit 0 | |
The fragment color of texture unit 1 | |
The fragment color of texture unit 2..7 | |
A fixed constant color (TODO: no API yet to specify the actual color!) | |
The basic color of the primitive ignoring texturing | |
The result of combining all previous layers |
void cogl_material_set_layer_combine_arg_src (CoglHandle material, gint layer_index, gint argument, CoglMaterialLayerCombineChannels channels, CoglMaterialLayerCombineSrc src);
|
A CoglMaterial object |
|
|
|
|
|
|
|
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;
void cogl_material_set_layer_combine_arg_op (CoglHandle material, gint layer_index, gint argument, CoglMaterialLayerCombineChannels channels, CoglMaterialLayerCombineOp op);
|
A CoglMaterial object |
|
|
|
|
|
|
|
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.
|
A CoglMaterial object |
|
|
|