![]() |
![]() |
![]() |
COGL 0.9.0 Reference Manual | ![]() |
---|---|---|---|---|
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);
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.
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;
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;
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 .
|
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 handle, CoglColor *ambient);
This retrieves the materials current ambient color.
Since 1.0
|
|
|
The location to store the ambient 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_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 |
|
void cogl_material_set_color4ub (CoglHandle handle, guint8 red, guint8 green, guint8 blue, guint8 alpha);
|
|
|
|
|
|
|
|
|
void cogl_material_get_color (CoglHandle handle, CoglColor *color);
This retrieves the current material color.
Since 1.0
|
|
|
The location to store the 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 handle, CoglColor *diffuse);
This retrieves the materials current diffuse color.
Since 1.0
|
|
|
The location to store the diffuse color |
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 handle, CoglColor *emission);
This retrieves the materials current emission color.
Since 1.0
|
|
|
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 handle, CoglColor *specular);
This retrieves the materials current specular color.
Since 1.0
|
|
|
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 handle);
This retrieves the materials current emission color.
|
|
Returns : |
The materials current shininess value Since 1.0 |
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
|
A CoglMaterial object |
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.
|
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;
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 = 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.
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 = 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.
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 |
|
|
|
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.
|
|
Returns : |
typedef enum _CoglMaterialFlushOption { COGL_MATERIAL_FLUSH_FALLBACK_MASK = 1, COGL_MATERIAL_FLUSH_DISABLE_MASK, COGL_MATERIAL_FLUSH_LAYER0_OVERRIDE, } CoglMaterialFlushOption;
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) | |
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) | |
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. |
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
|
A CoglMaterial object |
|
A NULL terminated list of (CoglMaterialFlushOption, data) pairs |
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.
|
|
Returns : |
typedef enum _CoglMaterialLayerType { COGL_MATERIAL_LAYER_TYPE_TEXTURE } CoglMaterialLayerType;
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.
|
|
Returns : |
typedef enum _CoglMaterialLayerFlags { COGL_MATERIAL_LAYER_FLAG_HAS_USER_MATRIX = 1L<<0 } CoglMaterialLayerFlags;
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.
|
A CoglMaterial layer object |
Returns : |
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.
|
A CoglMaterial layer object |
Returns : |