brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[doc] Hooks up cogl-material reference documentation

Browse Source 
Adds some more gtk-doc comments to cogl-material.h, and adds a new section to
cogl-sections.txt
This commit is contained in:
Robert Bragg
2008-12-22 16:19:49 +00:00
parent eb3b48e9ff
commit aee2589cc6
4 changed files with 528 additions and 275 deletions
Download Patch File Download Diff File Expand all files Collapse all files

692
clutter/cogl/cogl-material.h
View File

@ -20,8 +20,180 @@ G_BEGIN_DECLS
* blended together.
*/
G_END_DECLS
/**
* cogl_material_new:
*
* Allocates and initializes a blank white material
*
* Returns: a handle to the new material
*/
CoglHandle cogl_material_new (void);
/**
* cogl_material_ref:
* @handle: a @CoglHandle.
*
* Increment the reference count for a cogl material.
*
* Returns: the @handle.
*
* Since 1.0
*/
CoglHandle cogl_material_ref (CoglHandle handle);
/**
* cogl_material_unref:
* @handle: a @CoglHandle.
*
* Decrement the reference count for a cogl material.
*
* Since 1.0
*/
void cogl_material_unref (CoglHandle handle);
/**
* cogl_material_set_ambient:
* @material: A CoglMaterial object
* @ambient: The components of the desired ambient color
*
* 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
*/
void cogl_material_set_ambient (CoglHandle material,
const CoglColor *ambient);
/**
* cogl_material_set_diffuse:
* @material: A CoglMaterial object
* @diffuse: The components of the desired diffuse color
*
* 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
*/
void cogl_material_set_diffuse (CoglHandle material,
const CoglColor *diffuse);
/**
* cogl_material_set_ambient_and_diffuse:
* @material: A CoglMaterial object
* @color: The components of the desired ambient and diffuse colors
*
* 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
*/
void cogl_material_set_ambient_and_diffuse (CoglHandle material,
const CoglColor *color);
/**
* cogl_material_set_specular:
* @material: A CoglMaterial object
* @specular: The components of the desired specular color
*
* 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
*/
void cogl_material_set_specular (CoglHandle material,
const CoglColor *specular);
/**
* cogl_material_set_shininess:
* @material: A CoglMaterial object
* shininess: The desired shininess; range: [0.0, 1.0]
*
* 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
*/
void cogl_material_set_shininess (CoglHandle material,
float shininess);
/**
* cogl_material_set_emission:
* @material: A CoglMaterial object
* @emission: The components of the desired emissive color
*
* 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
*/
void cogl_material_set_emission (CoglHandle material,
const CoglColor *emission);
/**
* cogl_set_source:
* @material: A CoglMaterial object
*
* This function sets the source material that will be used to fill
* subsequent geometry emitted via the cogl API.
*
* XXX: This doesn't really belong to the cogl-material API, it should
* move to cogl.h
*
* Since 1.0
*/
void cogl_set_source (CoglHandle material);
/**
* CoglMaterialAlphaFunc:
* @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.
*
* 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.
*/
typedef enum _CoglMaterialAlphaFunc
{
COGL_MATERIAL_ALPHA_FUNC_NEVER = GL_NEVER,
@ -34,34 +206,157 @@ typedef enum _CoglMaterialAlphaFunc
COGL_MATERIAL_ALPHA_FUNC_ALWAYS = GL_ALWAYS
} CoglMaterialAlphaFunc;
/**
* cogl_material_set_alpha_test_function:
* @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.
*
* 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
*/
void cogl_material_set_alpha_test_function (CoglHandle material,
CoglMaterialAlphaFunc alpha_func,
float alpha_reference);
/**
* CoglMaterialBlendFactor:
* @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)
*
* Blending occurs after the alpha test function, and combines fragments with
* the framebuffer.
* <para>
* 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:
* </para>
* <programlisting>
* R = Rs*Sr + Rd*Dr
* G = Gs*Sg + Gd*Dg
* B = Bs*Sb + Bd*Db
* A = As*Sa + Ad*Da
* </programlisting>
*
* All factors have a range [0, 1]
*
* The factors are selected with the following constants:
*/
typedef enum _CoglMaterialBlendFactor
{
COGL_MATERIAL_BLEND_FACTOR_ZERO = GL_ZERO,
COGL_MATERIAL_BLEND_FACTOR_ONE = GL_ONE,
COGL_MATERIAL_BLEND_FACTOR_DST_COLOR = GL_DST_COLOR,
COGL_MATERIAL_BLEND_FACTOR_SRC_COLOR = GL_SRC_COLOR,
COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_DST_COLOR = GL_ONE_MINUS_DST_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,
#if 0
COGL_MATERIAL_BLEND_FACTOR_CONSTANT_COLOR = GL_CONSTANT_COLOR,
COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR =
GL_ONE_MINUS_CONSTANT_COLOR,
COGL_MATERIAL_BLEND_FACTOR_CONSTANT_ALPHA = GL_CONSTANT_ALPHA,
COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA =
GL_ONE_MINUS_CONSTANT_ALPHA
#endif
} CoglMaterialBlendFactor;
typedef enum _CoglMaterialLayerType
{
COGL_MATERIAL_LAYER_TYPE_TEXTURE
} CoglMaterialLayerType;
/**
* cogl_material_set_blend_factors:
* @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.
*
* 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
*/
void cogl_material_set_blend_factors (CoglHandle material,
CoglMaterialBlendFactor src_factor,
CoglMaterialBlendFactor dst_factor);
/**
* cogl_material_set_layer:
* @material: A CoglMaterial object
*
* 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
*/
void cogl_material_set_layer (CoglHandle material,
gint layer_index,
CoglHandle texture);
/**
* cogl_material_add_texture:
* @material: A CoglMaterial object
* @layer_index: Specifies the layer you want to remove
*
* This function removes a layer from your material
*/
void cogl_material_remove_layer (CoglHandle material,
gint layer_index);
/**
* CoglMaterialLayerCombineFunc:
* @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)) +
*
* 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:
*
* <programlisting>
* (Rs*Rp, Gs*Gp, Bs*Bp, As*Ap)
* </programlisting>
*
* For more advanced techniques, Cogl exposes the fixed function texture
* combining capabilities of your GPU to give you greater control.
*/
typedef enum _CoglMaterialLayerCombineFunc
{
COGL_MATERIAL_LAYER_COMBINE_FUNC_REPLACE = GL_REPLACE,
@ -74,6 +369,27 @@ typedef enum _CoglMaterialLayerCombineFunc
COGL_MATERIAL_LAYER_COMBINE_FUNC_DOT3_RGBA = GL_DOT3_RGBA
} CoglMaterialLayerCombineFunc;
/**
* CoglMaterialLayerCombineChannels:
* @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
*
* 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)
*/
typedef enum _CoglMaterialLayerCombineChannels
{
COGL_MATERIAL_LAYER_COMBINE_CHANNELS_RGB,
@ -81,6 +397,90 @@ typedef enum _CoglMaterialLayerCombineChannels
COGL_MATERIAL_LAYER_COMBINE_CHANNELS_RGBA
} CoglMaterialLayerCombineChannels;
/**
* cogl_material_set_layer_combine_function:
* @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.
*
* There are three basic steps to describing how a layer should be combined:
* <orderedlist>
* <listitem>
* Choose a function.
* </listitem>
* <listitem>
* Specify the source color for each argument of the chosen function. (Note
* the functions don't all take the same number of arguments)
* </listitem>
* <listitem>
* Specify an operator for each argument that can modify the corresponding
* source color before the function is applied.
* </listitem>
* </orderedlist>
*
* 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:
* <programlisting>
* //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);
* </programlisting>
*/
void cogl_material_set_layer_combine_function (CoglHandle material,
gint layer_index,
CoglMaterialLayerCombineChannels channels,
CoglMaterialLayerCombineFunc func);
/**
* CoglMaterialLayerCombineSrc:
* @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_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
*
* 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.
*/
typedef enum _CoglMaterialLayerCombineSrc
{
COGL_MATERIAL_LAYER_COMBINE_SRC_TEXTURE = GL_TEXTURE,
@ -101,6 +501,21 @@ typedef enum _CoglMaterialLayerCombineSrc
COGL_MATERIAL_LAYER_COMBINE_SRC_PREVIOUS = GL_PREVIOUS
} CoglMaterialLayerCombineSrc;
/**
* cogl_material_set_layer_combine_arg_src:
* @material: A CoglMaterial object
* @layer_index:
* @argument:
* @channels:
* @src:
*
*/
void cogl_material_set_layer_combine_arg_src (CoglHandle material,
gint layer_index,
gint argument,
CoglMaterialLayerCombineChannels channels,
CoglMaterialLayerCombineSrc src);
typedef enum _CoglMaterialLayerCombineOp
{
COGL_MATERIAL_LAYER_COMBINE_OP_SRC_COLOR = GL_SRC_COLOR,
@ -111,231 +526,19 @@ typedef enum _CoglMaterialLayerCombineOp
} CoglMaterialLayerCombineOp;
/**
* cogl_material_new:
*
* Allocates and initializes blank white material
*/
CoglHandle cogl_material_new (void);
/**
* cogl_material_ref:
* @handle: a @CoglHandle.
*
* Increment the reference count for a cogl material.
*
* Returns: the @handle.
*/
CoglHandle cogl_material_ref (CoglHandle handle);
/**
* cogl_material_unref:
* @handle: a @CoglHandle.
*
* Deccrement the reference count for a cogl material.
*/
void cogl_material_unref (CoglHandle handle);
/**
* cogl_material_set_diffuse:
* cogl_material_set_layer_combine_arg_op:
* @material: A CoglMaterial object
* @diffuse: The components of the desired diffuse color
*
* 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.
*/
void cogl_material_set_diffuse (CoglHandle material,
const CoglColor *diffuse);
/**
* cogl_material_set_ambient:
* @material: A CoglMaterial object
* @ambient: The components of the desired ambient color
*
* 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.
*/
void cogl_material_set_ambient (CoglHandle material,
const CoglColor *ambient);
/**
* cogl_material_set_ambient_and_diffuse:
* @material: A CoglMaterial object
* @color: The components of the desired ambient and diffuse colors
*
* This is a convenience for setting the diffuse and ambient color
* of the material at the same time.
*/
void cogl_material_set_ambient_and_diffuse (CoglHandle material,
const CoglColor *color);
/**
* cogl_material_set_specular:
* @material: A CoglMaterial object
* @specular: The components of the desired specular color
*
* 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.
*/
void cogl_material_set_specular (CoglHandle material,
const CoglColor *specular);
/**
* cogl_material_set_shininess:
* @material: A CoglMaterial object
* shininess: The desired shininess; range: [0.0, 1.0]
*
* This function sets the materials shininess which determines how
* specular highlights are calculated. A higher shininess will produce
* smaller brigher highlights.
*/
void cogl_material_set_shininess (CoglHandle material,
float shininess);
/**
* cogl_material_set_emission:
* @material: A CoglMaterial object
* @emission: The components of the desired emissive color
*
* 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.
*/
void cogl_material_set_emission (CoglHandle material,
const CoglColor *emission);
/**
* cogl_set_source:
* @material: A CoglMaterial object
*
* This function sets the source material that will be used to fill
* subsequent geometry emitted via the cogl API.
*
* XXX: This doesn't really belong to the cogl-material API, it should
* move to cogl.h
*/
void cogl_set_source (CoglHandle material);
/**
* cogl_material_set_alpha_test_func:
* @material: A CoglMaterial object
*
* 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.
* TODO: expand on this
*/
void cogl_material_set_alpha_test_func (CoglHandle material,
CoglMaterialAlphaFunc alpha_func,
float alpha_reference);
/**
* cogl_material_set_blend_function:
* @material: A CoglMaterial object
* @src_factor: Chooses the source factor you want plugged in to the blend
* equation.
* @dst_factor: Chooses the source factor you want plugged in to the blend
* equation.
*
* 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]
*
* The factors are selected with the following constants:
* <itemizedlist>
* <listitem>COGL_MATERIAL_BLEND_FACTOR_ZERO: (0,0,0,0)</listitem>
* <listitem>COGL_MATERIAL_BLEND_FACTOR_ONE: (1,1,1,1)</listitem>
* <listitem>COGL_MATERIAL_BLEND_FACTOR_DST_COLOR: (Rd,Gd,Bd,Ad)</listitem>
* <listitem>COGL_MATERIAL_BLEND_FACTOR_SRC_COLOR: (Rs,Gs,Bs,As)</listitem>
* <listitem>COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_DST_COLOR:
* (1,1,1,1)-(Rd,Gd,Bd,Ad) [Only valid for src_factor]</listitem>
* <listitem>COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_SRC_COLOR:
* (1,1,1,1)-(Rs,Gs,Bs,As)</listitem>
* <listitem>COGL_MATERIAL_BLEND_FACTOR_SRC_ALPHA: (As,As,As,As)</listitem>
* <listitem>COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA:
* (1,1,1,1)-(As,As,As,As) [Only valid for dst_factor]</listitem>
* <listitem>COGL_MATERIAL_BLEND_FACTOR_DST_ALPHA: (Ad,Ad,Ad,Ad)</listitem>
* <listitem>COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_DST_ALPHA:
* (1,1,1,1)-(Ad,Ad,Ad,Ad)</listitem>
* <listitem>COGL_MATERIAL_BLEND_FACTOR_SRC_ALPHA_SATURATE:
* (f,f,f,1) where f=MIN(As,1-Ad)</listitem>
* </itemizedlist>
*/
void cogl_material_set_blend_function (CoglHandle material,
CoglMaterialBlendFactor src_factor,
CoglMaterialBlendFactor dst_factor);
/**
* cogl_material_set_layer:
* @material: A CoglMaterial object
*
* 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.
*/
void cogl_material_set_layer (CoglHandle material,
gint layer_index,
CoglHandle texture);
/**
* cogl_material_add_texture:
* @material: A CoglMaterial object
*
* @layer_index:
* @argument:
* @channels:
* @op:
*
*/
void cogl_material_remove_layer (CoglHandle material,
gint layer_index);
/**
* cogl_material_set_layer_alpha_combine_func:
* @material: A CoglMaterial object
*
* TODO: Brew, a nice hot cup of tea, and document these functions...
*/
void cogl_material_set_layer_combine_func (
CoglHandle material,
gint layer_index,
CoglMaterialLayerCombineChannels channels,
CoglMaterialLayerCombineFunc func);
void cogl_material_set_layer_combine_arg_src (
CoglHandle material,
gint layer_index,
gint argument,
CoglMaterialLayerCombineChannels channels,
CoglMaterialLayerCombineSrc src);
void cogl_material_set_layer_combine_arg_op (
CoglHandle material,
gint layer_index,
gint argument,
CoglMaterialLayerCombineChannels channels,
CoglMaterialLayerCombineOp op);
void cogl_material_set_layer_combine_arg_op (CoglHandle material,
gint layer_index,
gint argument,
CoglMaterialLayerCombineChannels channels,
CoglMaterialLayerCombineOp op);
/* TODO: */
#if 0
@ -366,8 +569,8 @@ void cogl_material_set_layer_alpha_combine (CoglHandle material
* 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.
*/
void cogl_material_set_layer_matrix (CoglHandle material,
gint layer_index,
void cogl_material_set_layer_matrix (CoglHandle material,
gint layer_index,
CoglMatrix *matrix);
/**
@ -433,6 +636,15 @@ void cogl_material_flush_gl_blend_func (CoglHandle material_handle);
*/
const GList *cogl_material_get_layers (CoglHandle material_handle);
/**
* CoglMaterialLayerType:
* @COGL_MATERIAL_LAYER_TYPE_TEXTURE: The layer represents a CoglTexture
*/
typedef enum _CoglMaterialLayerType
{
COGL_MATERIAL_LAYER_TYPE_TEXTURE
} CoglMaterialLayerType;
/**
* cogl_material_layer_get_type:
* @material: A CoglMaterial object
@ -479,5 +691,7 @@ CoglHandle cogl_material_layer_get_texture (CoglHandle layer_handle);
*/
void cogl_material_layer_flush_gl_sampler_state (CoglHandle layer_handle);
G_END_DECLS
#endif /* __COGL_MATERIAL_H__ */

72
clutter/cogl/common/cogl-material.c
View File

@ -29,10 +29,10 @@ cogl_material_new (void)
GLfloat *diffuse = material->diffuse;
GLfloat *specular = material->specular;
GLfloat *emission = material->emission;
material->ref_count = 1;
COGL_HANDLE_DEBUG_NEW (material, material);
/* Use the same defaults as the GL spec... */
ambient[0] = 0.2; ambient[1] = 0.2; ambient[2] = 0.2; ambient[3] = 1.0;
diffuse[0] = 0.8; diffuse[1] = 0.8; diffuse[2] = 0.8; diffuse[3] = 1.0;
@ -42,7 +42,7 @@ cogl_material_new (void)
/* Use the same defaults as the GL spec... */
material->alpha_func = COGL_MATERIAL_ALPHA_FUNC_ALWAYS;
material->alpha_func_reference = 0.0;
/* Not the same as the GL default, but seems saner... */
material->blend_src_factor = COGL_MATERIAL_BLEND_FACTOR_SRC_ALPHA;
material->blend_dst_factor = COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA;
@ -69,9 +69,9 @@ cogl_material_set_ambient (CoglHandle handle,
{
CoglMaterial *material;
GLfloat *ambient;
g_return_if_fail (cogl_is_material (handle));
material = _cogl_material_pointer_from_handle (handle);
ambient = material->ambient;
@ -88,9 +88,9 @@ cogl_material_set_diffuse (CoglHandle handle,
{
CoglMaterial *material;
GLfloat *diffuse;
g_return_if_fail (cogl_is_material (handle));
material = _cogl_material_pointer_from_handle (handle);
diffuse = material->diffuse;
@ -115,9 +115,9 @@ cogl_material_set_specular (CoglHandle handle,
{
CoglMaterial *material;
GLfloat *specular;
g_return_if_fail (cogl_is_material (handle));
material = _cogl_material_pointer_from_handle (handle);
specular = material->specular;
@ -133,13 +133,13 @@ cogl_material_set_shininess (CoglHandle handle,
float shininess)
{
CoglMaterial *material;
g_return_if_fail (cogl_is_material (handle));
if (shininess < 0.0 || shininess > 1.0)
g_warning ("Out of range shininess %f supplied for material\n",
shininess);
material = _cogl_material_pointer_from_handle (handle);
material->shininess = (GLfloat)shininess * 128.0;
@ -151,9 +151,9 @@ cogl_material_set_emission (CoglHandle handle,
{
CoglMaterial *material;
GLfloat *emission;
g_return_if_fail (cogl_is_material (handle));
material = _cogl_material_pointer_from_handle (handle);
emission = material->emission;
@ -169,9 +169,9 @@ void
cogl_set_source (CoglHandle material_handle)
{
_COGL_GET_CONTEXT (ctx, NO_RETVAL);
g_return_if_fail (cogl_is_material (material_handle));
if (ctx->source_material)
cogl_material_unref (ctx->source_material);
@ -180,28 +180,28 @@ cogl_set_source (CoglHandle material_handle)
}
void
cogl_material_set_alpha_test_func (CoglHandle handle,
CoglMaterialAlphaFunc alpha_func,
float alpha_reference)
cogl_material_set_alpha_test_function (CoglHandle handle,
CoglMaterialAlphaFunc alpha_func,
float alpha_reference)
{
CoglMaterial *material;
g_return_if_fail (cogl_is_material (handle));
material = _cogl_material_pointer_from_handle (handle);
material->alpha_func = alpha_func;
material->alpha_func_reference = (GLfloat)alpha_reference;
}
void
cogl_material_set_blend_function (CoglHandle handle,
CoglMaterialBlendFactor src_factor,
CoglMaterialBlendFactor dst_factor)
cogl_material_set_blend_factors (CoglHandle handle,
CoglMaterialBlendFactor src_factor,
CoglMaterialBlendFactor dst_factor)
{
CoglMaterial *material;
g_return_if_fail (cogl_is_material (handle));
material = _cogl_material_pointer_from_handle (handle);
material->blend_src_factor = src_factor;
material->blend_dst_factor = dst_factor;
@ -243,7 +243,7 @@ _cogl_material_get_layer (CoglMaterial *material,
layer->index = index;
layer->texture = COGL_INVALID_HANDLE;
/* Choose the same default combine mode as OpenGL:
/* Choose the same default combine mode as OpenGL:
* MODULATE(PREVIOUS[RGBA],TEXTURE[RGBA]) */
layer->texture_combine_rgb_func = COGL_MATERIAL_LAYER_COMBINE_FUNC_MODULATE;
layer->texture_combine_rgb_src[0] = COGL_MATERIAL_LAYER_COMBINE_SRC_PREVIOUS;
@ -283,7 +283,7 @@ cogl_material_set_layer (CoglHandle material_handle,
material = _cogl_material_pointer_from_handle (material_handle);
layer = _cogl_material_get_layer (material_handle, layer_index, TRUE);
/* XXX: If we expose manual control over ENABLE_BLEND, we'll add
* a flag to know when it's user configured, so we don't trash it */
if (cogl_texture_get_format (texture_handle) & COGL_A_BIT)
@ -313,7 +313,7 @@ cogl_material_set_layer (CoglHandle material_handle,
}
void
cogl_material_set_layer_combine_func (
cogl_material_set_layer_combine_function (
CoglHandle handle,
gint layer_index,
CoglMaterialLayerCombineChannels channels,
@ -323,7 +323,7 @@ cogl_material_set_layer_combine_func (
CoglMaterialLayer *layer;
gboolean set_alpha_func = FALSE;
gboolean set_rgb_func = FALSE;
g_return_if_fail (cogl_is_material (handle));
material = _cogl_material_pointer_from_handle (handle);
@ -356,7 +356,7 @@ cogl_material_set_layer_combine_arg_src (
CoglMaterialLayer *layer;
gboolean set_arg_alpha_src = FALSE;
gboolean set_arg_rgb_src = FALSE;
g_return_if_fail (cogl_is_material (handle));
g_return_if_fail (argument >=0 && argument <= 3);
@ -371,7 +371,7 @@ cogl_material_set_layer_combine_arg_src (
set_arg_rgb_src = TRUE;
else if (channels == COGL_MATERIAL_LAYER_COMBINE_CHANNELS_ALPHA)
set_arg_alpha_src = TRUE;
if (set_arg_rgb_src)
layer->texture_combine_rgb_src[argument] = src;
if (set_arg_alpha_src)
@ -390,7 +390,7 @@ cogl_material_set_layer_combine_arg_op (
CoglMaterialLayer *layer;
gboolean set_arg_alpha_op = FALSE;
gboolean set_arg_rgb_op = FALSE;
g_return_if_fail (cogl_is_material (material_handle));
g_return_if_fail (argument >=0 && argument <= 3);
@ -405,7 +405,7 @@ cogl_material_set_layer_combine_arg_op (
set_arg_rgb_op = TRUE;
else if (channels == COGL_MATERIAL_LAYER_COMBINE_CHANNELS_ALPHA)
set_arg_alpha_op = TRUE;
if (set_arg_rgb_op)
layer->texture_combine_rgb_op[argument] = op;
if (set_arg_alpha_op)
@ -419,7 +419,7 @@ cogl_material_set_layer_matrix (CoglHandle material_handle,
{
CoglMaterial *material;
CoglMaterialLayer *layer;
g_return_if_fail (cogl_is_material (material_handle));
material = _cogl_material_pointer_from_handle (material_handle);
@ -500,7 +500,7 @@ cogl_material_flush_gl_material_state (CoglHandle material_handle)
g_return_if_fail (cogl_is_material (material_handle));
material = _cogl_material_pointer_from_handle (material_handle);
GE (glMaterialfv (GL_FRONT_AND_BACK, GL_AMBIENT, material->ambient));
GE (glMaterialfv (GL_FRONT_AND_BACK, GL_DIFFUSE, material->diffuse));
GE (glMaterialfv (GL_FRONT_AND_BACK, GL_SPECULAR, material->specular));
@ -619,9 +619,9 @@ cogl_material_layer_flush_gl_sampler_state (CoglHandle layer_handle)
GE (glTexEnvi (GL_TEXTURE_ENV,
GL_COMBINE_ALPHA,
layer->texture_combine_alpha_func));
/*
* Setup the function arguments...
/*
* Setup the function arguments...
*/
/* For the RGB components... */

1
doc/reference/cogl/cogl-docs.sgml
View File

@ -57,6 +57,7 @@
<xi:include href="xml/cogl-util.xml"/>
<xi:include href="xml/cogl-matrix.xml"/>
<xi:include href="xml/cogl-texture.xml"/>
<xi:include href="xml/cogl-material.xml"/>
<xi:include href="xml/cogl-shaders.xml"/>
<xi:include href="xml/cogl-offscreen.xml"/>
<xi:include href="xml/cogl-fixed.xml"/>

38
doc/reference/cogl/cogl-sections.txt
View File

@ -304,3 +304,41 @@ cogl_matrix_translate
cogl_matrix_scale
</SECTION>
<SECTION>
<FILE>cogl-material</FILE>
<TITLE>Materials</TITLE>
cogl_material_new
cogl_material_ref
cogl_material_unref
cogl_material_set_diffuse
cogl_material_set_ambient
cogl_material_set_ambient_and_diffuse
cogl_material_set_specular
cogl_material_set_shininess
cogl_material_set_emission
cogl_set_source
CoglMaterialAlphaFunc
cogl_material_set_alpha_test_function
CoglMaterialBlendFactor
cogl_material_set_blend_factors
cogl_material_set_layer
cogl_material_remove_layer
CoglMaterialLayerCombineFunc
cogl_material_set_layer_combine_function
CoglMaterialLayerCombineChannels
CoglMaterialLayerCombineSrc
cogl_material_set_layer_combine_arg_src
CoglMaterialLayerCombineOp
cogl_material_set_layer_combine_arg_op
cogl_material_set_layer_matrix
cogl_material_get_cogl_enable_flags
cogl_material_flush_gl_material_state
cogl_material_flush_gl_alpha_func
cogl_material_flush_gl_blend_func
cogl_material_get_layers
CoglMaterialLayerType
cogl_material_layer_get_type
cogl_material_layer_get_texture
cogl_material_layer_flush_gl_sampler_state
</SECTION>