diff --git a/cogl-material.h b/cogl-material.h index 973a9d7fb..43c603559 100644 --- a/cogl-material.h +++ b/cogl-material.h @@ -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. + * + * 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: + */ 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: + * + * + * (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. + */ 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: + * + * + * Choose a function. + * + * + * Specify the source color for each argument of the chosen function. (Note + * the functions don't all take the same number of arguments) + * + * + * 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); + * + */ +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: - * - * COGL_MATERIAL_BLEND_FACTOR_ZERO: (0,0,0,0) - * COGL_MATERIAL_BLEND_FACTOR_ONE: (1,1,1,1) - * COGL_MATERIAL_BLEND_FACTOR_DST_COLOR: (Rd,Gd,Bd,Ad) - * COGL_MATERIAL_BLEND_FACTOR_SRC_COLOR: (Rs,Gs,Bs,As) - * COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_DST_COLOR: - * (1,1,1,1)-(Rd,Gd,Bd,Ad) [Only valid for src_factor] - * COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_SRC_COLOR: - * (1,1,1,1)-(Rs,Gs,Bs,As) - * COGL_MATERIAL_BLEND_FACTOR_SRC_ALPHA: (As,As,As,As) - * COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA: - * (1,1,1,1)-(As,As,As,As) [Only valid for dst_factor] - * COGL_MATERIAL_BLEND_FACTOR_DST_ALPHA: (Ad,Ad,Ad,Ad) - * COGL_MATERIAL_BLEND_FACTOR_ONE_MINUS_DST_ALPHA: - * (1,1,1,1)-(Ad,Ad,Ad,Ad) - * COGL_MATERIAL_BLEND_FACTOR_SRC_ALPHA_SATURATE: - * (f,f,f,1) where f=MIN(As,1-Ad) - * - */ -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__ */ diff --git a/common/cogl-material.c b/common/cogl-material.c index d720c120f..7d98d3de1 100644 --- a/common/cogl-material.c +++ b/common/cogl-material.c @@ -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... */ diff --git a/doc/reference/cogl/cogl-docs.sgml b/doc/reference/cogl/cogl-docs.sgml index f872b0349..7e2c0974c 100644 --- a/doc/reference/cogl/cogl-docs.sgml +++ b/doc/reference/cogl/cogl-docs.sgml @@ -57,6 +57,7 @@ + diff --git a/doc/reference/cogl/cogl-sections.txt b/doc/reference/cogl/cogl-sections.txt index 84c43dbf3..fe81ddab1 100644 --- a/doc/reference/cogl/cogl-sections.txt +++ b/doc/reference/cogl/cogl-sections.txt @@ -304,3 +304,41 @@ cogl_matrix_translate cogl_matrix_scale +
+cogl-material +Materials +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 +
+