isa/mutter
1
0
Fork 0
mirror of https://github.com/brl/mutter.git synced 2024-11-26 10:00:45 -05:00
Code Issues Packages Projects Releases Wiki Activity

[docs] Various gtk-doc updates for Cogl

Browse Source 
This hides a number of internal structs and enums from the docs, and moves
some functions to more appropriate sections as well as misc description
updates (mostly for the vertex buffer api)
This commit is contained in:
Robert Bragg 2009-02-06 11:16:42 +00:00
parent c3b8dcd2f0
commit 5901b4d045
7 changed files with 281 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
cogl-color.h
View File

@ -224,61 +224,6 @@ float cogl_color_get_blue (const CoglColor *color);
*/ */
float cogl_color_get_alpha (const CoglColor *color); float cogl_color_get_alpha (const CoglColor *color);
/**
* cogl_set_source_color:
* @color: a #CoglColor
*
* Sets the source color using normalized values for each component.
* This color will be used for any subsequent drawing operation.
*
* See also cogl_set_source_color4ub() and cogl_set_source_color4f()
* if you already have the color components.
*
* Since: 1.0
*/
void cogl_set_source_color (const CoglColor *color);
/**
* cogl_set_source_color4ub:
* @red: value of the red channel, between 0 and 255
* @green: value of the green channel, between 0 and 255
* @blue: value of the blue channel, between 0 and 255
* @alpha: value of the alpha channel, between 0 and 255
*
* Sets the source color using unsigned bytes for each component. This
* color will be used for any subsequent drawing operation.
*
* The value for each component is an unsigned byte in the range
* between 0 and 255.
*
* Since: 1.0
*/
void cogl_set_source_color4ub (guint8 red,
guint8 green,
guint8 blue,
guint8 alpha);
/**
* cogl_set_source_color4f:
* @red: value of the red channel, between 0 and %1.0
* @green: value of the green channel, between 0 and %1.0
* @blue: value of the blue channel, between 0 and %1.0
* @alpha: value of the alpha channel, between 0 and %1.0
*
* Sets the source color using normalized values for each component.
* This color will be used for any subsequent drawing operation.
*
* The value for each component is a fixed point number in the range
* between 0 and %1.0. If the values passed in are outside that
* range, they will be clamped.
*
* Since: 1.0
*/
void cogl_set_source_color4f (float red,
float green,
float blue,
float alpha);
G_END_DECLS G_END_DECLS
#endif /* __COGL_COLOR_H__ */ #endif /* __COGL_COLOR_H__ */

109
cogl-material.h
View File

@ -68,7 +68,7 @@ void cogl_material_unref (CoglHandle handle);
void cogl_material_set_color (CoglHandle material, const CoglColor *color); void cogl_material_set_color (CoglHandle material, const CoglColor *color);
/** /**
* cogl_material_set_color: * cogl_material_set_color4ub:
* @material: A CoglMaterial object * @material: A CoglMaterial object
* @red: The red component * @red: The red component
* @green: The green component * @green: The green component
@ -81,11 +81,31 @@ void cogl_material_set_color (CoglHandle material, const CoglColor *color);
* *
* Since 1.0 * Since 1.0
*/ */
void cogl_material_set_color4ub (CoglHandle handle, void cogl_material_set_color4ub (CoglHandle material,
guint8 red, guint8 red,
guint8 green, guint8 green,
guint8 blue, guint8 blue,
guint8 alpha); guint8 alpha);
/**
* cogl_material_set_color4f:
* @material: A CoglMaterial object
* @red: The red component
* @green: The green component
* @blue: The blue component
* @alpha: The alpha component
*
* 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
*/
void cogl_material_set_color4f (CoglHandle material,
float red,
float green,
float blue,
float alpha);
/** /**
* cogl_material_get_color: * cogl_material_get_color:
@ -96,7 +116,7 @@ void cogl_material_set_color4ub (CoglHandle handle,
* *
* Since 1.0 * Since 1.0
*/ */
void cogl_material_get_color (CoglHandle handle, CoglColor *color); void cogl_material_get_color (CoglHandle material, CoglColor *color);
/** /**
* cogl_material_set_ambient: * cogl_material_set_ambient:
@ -125,7 +145,7 @@ void cogl_material_set_ambient (CoglHandle material,
* *
* Since 1.0 * Since 1.0
*/ */
void cogl_material_get_ambient (CoglHandle handle, CoglColor *ambient); void cogl_material_get_ambient (CoglHandle material, CoglColor *ambient);
/** /**
* cogl_material_set_diffuse: * cogl_material_set_diffuse:
@ -153,7 +173,7 @@ void cogl_material_set_diffuse (CoglHandle material,
* *
* Since 1.0 * Since 1.0
*/ */
void cogl_material_get_diffuse (CoglHandle handle, CoglColor *diffuse); void cogl_material_get_diffuse (CoglHandle material, CoglColor *diffuse);
/** /**
* cogl_material_set_ambient_and_diffuse: * cogl_material_set_ambient_and_diffuse:
@ -197,7 +217,7 @@ void cogl_material_set_specular (CoglHandle material,
* *
* Since 1.0 * Since 1.0
*/ */
void cogl_material_get_specular (CoglHandle handle, CoglColor *specular); void cogl_material_get_specular (CoglHandle material, CoglColor *specular);
/** /**
* cogl_material_set_shininess: * cogl_material_set_shininess:
@ -224,7 +244,7 @@ void cogl_material_set_shininess (CoglHandle material,
* *
* Since 1.0 * Since 1.0
*/ */
float cogl_material_get_shininess (CoglHandle handle); float cogl_material_get_shininess (CoglHandle material);
/** /**
* cogl_material_set_emission: * cogl_material_set_emission:
@ -251,7 +271,7 @@ void cogl_material_set_emission (CoglHandle material,
* *
* Since 1.0 * Since 1.0
*/ */
void cogl_material_get_emission (CoglHandle handle, CoglColor *emission); void cogl_material_get_emission (CoglHandle material, CoglColor *emission);
/** /**
* CoglMaterialAlphaFunc: * CoglMaterialAlphaFunc:
@ -660,18 +680,30 @@ void cogl_material_set_layer_matrix (CoglHandle material,
gint layer_index, gint layer_index,
CoglMatrix *matrix); CoglMatrix *matrix);
/**
* SECTION:cogl-material-internals
* @short_description: Functions for creating custom primitives that make use
* of Cogl materials for filling.
*
* Normally you shouldn't need to use this API directly, but if you need to
* developing a custom/specialised primitive - probably using raw OpenGL - then
* this API aims to expose enough of the material internals to support being
* able to fill your geometry according to a given Cogl material.
*/
/** /**
* cogl_material_get_cogl_enable_flags: * cogl_material_get_cogl_enable_flags:
* @material: A CoglMaterial object * @material: A CoglMaterial object
* *
* This determines what flags need to be passed to cogl_enable before * This determines what flags need to be passed to cogl_enable before this
* this material can be used. Normally you shouldn't need to use this * material can be used. Normally you shouldn't need to use this function
* function directly since Cogl will do this internally, but if you are * directly since Cogl will do this internally, but if you are developing
* developing custom primitives directly with OpenGL you may want to use * custom primitives directly with OpenGL you may want to use this.
* this.
* *
* Note: This API is hopfully just a stop-gap solution. Ideally * Note: This API is hopfully just a stop-gap solution. Ideally cogl_enable
* cogl_enable will be replaced. * will be replaced.
*/ */
/* TODO: find a nicer solution! */ /* TODO: find a nicer solution! */
gulong gulong
@ -710,7 +742,7 @@ typedef enum _CoglMaterialLayerType
/** /**
* cogl_material_layer_get_type: * cogl_material_layer_get_type:
* @material: A CoglMaterial object * @layer_handle: A CoglMaterialLayer handle
* *
* Currently there is only one type of layer defined: * Currently there is only one type of layer defined:
* COGL_MATERIAL_LAYER_TYPE_TEXTURE, but considering we may add purely GLSL * COGL_MATERIAL_LAYER_TYPE_TEXTURE, but considering we may add purely GLSL
@ -726,7 +758,7 @@ CoglMaterialLayerType cogl_material_layer_get_type (CoglHandle layer_handle);
/** /**
* cogl_material_layer_get_texture: * cogl_material_layer_get_texture:
* @layer_handle: A CoglMaterial layer object * @layer_handle: A CoglMaterialLayer handle
* *
* This lets you extract a CoglTexture handle for a specific layer. Normally * 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 * you shouldn't need to use this function directly since Cogl will do this
@ -754,7 +786,7 @@ typedef enum _CoglMaterialLayerFlags
/** /**
* cogl_material_layer_get_flags: * cogl_material_layer_get_flags:
* @layer_handle: A CoglMaterial layer object * @layer_handle: A CoglMaterialLayer layer handle
* *
* This lets you get a number of flag attributes about the layer. Normally * 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 * you shouldn't need to use this function directly since Cogl will do this
@ -793,44 +825,11 @@ typedef enum _CoglMaterialFlushOption
* This function commits the state of the specified CoglMaterial - including * This function commits the state of the specified CoglMaterial - including
* the texture state for all the layers - to the OpenGL[ES] driver. * 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 * Since 1.0
*/ */
void cogl_material_flush_gl_state (CoglHandle material, void cogl_material_flush_gl_state (CoglHandle material,
...) G_GNUC_NULL_TERMINATED; ...) G_GNUC_NULL_TERMINATED;
/**
* 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.
*
* 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
*/
/* XXX: This doesn't really belong to the cogl-material API, it should
* move to cogl.h */
void cogl_set_source (CoglHandle material);
/**
* cogl_set_source_texture:
* @texture_handle: The Cogl texture you want as your source
*
* This is a convenience function for creating a material with the first
* layer set to #texture_handle and setting that material as the source with
* cogl_set_source.
*
* Since 1.0
*/
void cogl_set_source_texture (CoglHandle texture_handle);
G_END_DECLS G_END_DECLS
#endif /* __COGL_MATERIAL_H__ */ #endif /* __COGL_MATERIAL_H__ */

8
cogl-matrix.h
View File

@ -10,9 +10,9 @@ G_BEGIN_DECLS
* @short_description: Fuctions for initializing and manipulating 4x4 * @short_description: Fuctions for initializing and manipulating 4x4
* matrices. * matrices.
* *
* Matrices are used in Cogl to describe affine model-view transforms and * Matrices are used in Cogl to describe affine model-view transforms, texture
* texture transforms, and projective transforms. This exposes a utility API * transforms, and projective transforms. This exposes a utility API that can
* that can be used for direct manipulation of these matrices. * be used for direct manipulation of these matrices.
*/ */
@ -22,7 +22,7 @@ G_BEGIN_DECLS
* A CoglMatrix holds a 4x4 transform matrix. This is a single precision, * A CoglMatrix holds a 4x4 transform matrix. This is a single precision,
* column-major matrix which means it is compatible with what OpenGL expects. * column-major matrix which means it is compatible with what OpenGL expects.
* *
* A CoglMatix can represent transforms such as, rotations, scaling, * A CoglMatrix can represent transforms such as, rotations, scaling,
* translation, sheering, and linear projections. You can combine these * translation, sheering, and linear projections. You can combine these
* transforms by multiplying multiple matrices in the order you want them * transforms by multiplying multiple matrices in the order you want them
* applied. * applied.

150
cogl-vertex-buffer.h
View File

@ -38,44 +38,39 @@ G_BEGIN_DECLS
/** /**
* SECTION:cogl-vertex-buffer * SECTION:cogl-vertex-buffer
* @short_description: An API for submitting extensible arrays of vertex * @short_description: An API for submitting extensible arrays of vertex
* attributes to OpenGL in a way that aims to minimise * attributes to be mapped into the GPU for fast
* copying or reformatting of the original data. * drawing.
* *
* The Attributes Buffer API is designed to be a fairly raw mechanism for * For example to describe a textured triangle, you could create a new cogl
* vertex buffer with 3 vertices, and then you might add 2 attributes for each
* vertex:
* <orderedlist>
* <listitem>
* a "gl_Position" describing the (x,y,z) position for each vertex.
* </listitem>
* <listitem>
* a "gl_MultiTexCoord0" describing the (tx,ty) texture coordinates for each
* vertex.
* </listitem>
* </orderedlist>
*
* The Vertex Buffer API is designed to be a fairly raw mechanism for
* developers to be able to submit geometry to Cogl in a format that can be * developers to be able to submit geometry to Cogl in a format that can be
* directly consumed by an OpenGL driver and with awareness of the specific * directly consumed by an OpenGL driver and mapped into your GPU for fast
* hardware being used then costly format conversion can also be avoided. * re-use. It is designed to avoid repeated validation of the attributes by the
* driver; to minimize transport costs (considering indirect GLX use-cases)
* and to potentially avoid repeated format conversions when attributes are
* supplied in a format that is not natively supported by the GPU.
* *
* They are designed to work on top of buffer objects and developers should * Although this API does allow you to modify attributes after they have been
* understand that attribute buffers are not that cheap to create but once they * submitted to the GPU you should be aware that modification is not that
* have been submitted they can be stored in GPU addressable memory and can * cheap, since it implies validating the new data and potentially the
* be quickly reused. * OpenGL driver will need to reformat it for the GPU.
* *
* Although this API does allow you to modify attribute buffers after they have * If at all possible think of tricks that let you re-use static attributes,
* been submitted to the GPU you must note that modification is also not that * and if you do need to repeatedly update attributes (e.g. for some kind of
* cheap, so if at all possible think of tricks that let you reuse a static * morphing geometry) then only update and re-submit the specific attributes
* buffer. To help with this, it is possible to enable and disable individual * that have changed.
* attributes cheaply.
*
* Take for example attributes representing an elipse. If you were to submit
* color attributes, texture coordinates and normals, then you would be able
* to draw an elipses in the following different ways without modifying
* the vertex buffer, only by changing your source material.
* <itemizedlist>
* <listitem>Flat colored elipse</listitem>
* <listitem>Textured elipse</listitem>
* <listitem>Smoothly lit textured elipse blended with the color.</listitem>
* </itemizedlist>
*
* Another trick that can be used is submitting highly detailed vertices and
* then using cogl_vertex_buffer_draw_range_elements to sample sub-sets of
* the geometry or lower resolution geometry out from a fixed buffer.
*
* The API doesn't currently give you any control over the actual OpenGL buffer
* objects that are created, but you can expect that when you first submit
* your attributes they start off in one or more GL_STATIC_DRAW buffers.
* If you then update some of your attributes; then these attributes will
* normally be moved into new GL_DYNAMIC_DRAW draw buffers.
*/ */
/** /**
@ -94,7 +89,7 @@ cogl_vertex_buffer_new (guint n_vertices);
* @attribute_name: The name of your attribute. It should be a valid GLSL * @attribute_name: The name of your attribute. It should be a valid GLSL
* variable name and standard attribute types must use one * variable name and standard attribute types must use one
* of following built-in names: (Note: they correspond to the * of following built-in names: (Note: they correspond to the
* built-in names in GLSL) * built-in names of GLSL)
* <itemizedlist> * <itemizedlist>
* <listitem>"gl_Color"</listitem> * <listitem>"gl_Color"</listitem>
* <listitem>"gl_Normal"</listitem> * <listitem>"gl_Normal"</listitem>
@ -106,8 +101,7 @@ cogl_vertex_buffer_new (guint n_vertices);
* "gl_Color::active" or "gl_Color::inactive" * "gl_Color::active" or "gl_Color::inactive"
* @n_components: The number of components per attribute and must be 1,2,3 or 4 * @n_components: The number of components per attribute and must be 1,2,3 or 4
* @gl_type: Specifies the data type of each component (GL_BYTE, GL_UNSIGNED_BYTE, * @gl_type: Specifies the data type of each component (GL_BYTE, GL_UNSIGNED_BYTE,
* GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT or * GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT or GL_FLOAT)
* GL_DOUBLE)
* @normalized: If GL_TRUE, this specifies that values stored in an integer * @normalized: If GL_TRUE, this specifies that values stored in an integer
* format should be mapped into the range [-1.0, 1.0] or [0.1, 1.0] * format should be mapped into the range [-1.0, 1.0] or [0.1, 1.0]
* for unsigned values. If GL_FALSE they are converted to floats * for unsigned values. If GL_FALSE they are converted to floats
@ -119,32 +113,33 @@ cogl_vertex_buffer_new (guint n_vertices);
* stride for both attributes is 6. The special value 0 means the * stride for both attributes is 6. The special value 0 means the
* values are stored sequentially in memory. * values are stored sequentially in memory.
* @pointer: This addresses the first attribute in the vertex array. (This * @pointer: This addresses the first attribute in the vertex array. (This
* must remain valid until you call cogl_vertex_buffer_submit) * must remain valid until you call cogl_vertex_buffer_submit())
* *
* This function lets you add an attribute to a buffer. You either use one * This function lets you add an attribute to a buffer. You either use one
* of the built-in names to add standard attributes, like positions, colors * of the built-in names such as "gl_Vertex", or "glMultiTexCoord0" to add
* and normals or you can add custom attributes for use in shaders. * standard attributes, like positions, colors and normals or you can add
* custom attributes for use in shaders.
* *
* Note: The number of vertices declared when first creating the vertex * The number of vertices declared when calling cogl_vertex_buffer_new()
* buffer is used to determine how many attribute values will be read from the * determines how many attribute values will be read from the supplied pointer.
* supplied pointer.
* *
* Note: the data supplied here isn't copied anywhere until you call * The data for your attribute isn't copied anywhere until you call
* cogl_vertex_buffer_submit, so the supplied pointer must remain valid * cogl_vertex_buffer_submit(), so the supplied pointer must remain valid
* until then. * until then. If you are updating an attribute by re-adding it then you will
* (This is an important optimisation since we can't create the underlying * also need to re-call cogl_vertex_buffer_submit() to commit the changes to
* OpenGL buffer object until we know about all the attributes, and repeatedly * the GPU. (Be carefull to minimize the number of calls to
* copying large buffers of vertex data may be very costly) If you add * cogl_vertex_buffer_submit though.)
* attributes after submitting then you will need to re-call
* cogl_vertex_buffer_submit to commit the changes to the GPU. (Be carefull
* to minimize the number of calls to cogl_vertex_buffer_submit though)
* *
* Note: If you are interleving attributes it is assumed that that each * Note: If you are interleving attributes it is assumed that that each
* interleaved attribute starts no farther than +- stride bytes from the other * interleaved attribute starts no farther than +- stride bytes from the other
* attributes it is interleved with. I.e. this is ok: * attributes it is interleved with. I.e. this is ok:
* <programlisting>
* |-0-0-0-0-0-0-0-0-0-0| * |-0-0-0-0-0-0-0-0-0-0|
* </programlisting>
* This is not ok: * This is not ok:
* <programlisting>
* |- - - - -0-0-0-0-0-0 0 0 0 0| * |- - - - -0-0-0-0-0-0 0 0 0 0|
* </programlisting>
* (Though you can have multiple groups of interleved attributes) * (Though you can have multiple groups of interleved attributes)
*/ */
void void
@ -162,38 +157,23 @@ cogl_vertex_buffer_add (CoglHandle handle,
* @attribute_name: The name of a previously added attribute * @attribute_name: The name of a previously added attribute
* *
* This function deletes an attribute from a buffer. You will need to * This function deletes an attribute from a buffer. You will need to
* call cogl_vertex_buffer_submit to commit this change to the GPU. * call cogl_vertex_buffer_submit() to commit this change to the GPU.
*/ */
void void
cogl_vertex_buffer_delete (CoglHandle handle, cogl_vertex_buffer_delete (CoglHandle handle,
const char *attribute_name); const char *attribute_name);
/**
* cogl_vertex_buffer_enable:
* @handle: A vertex buffer handle
* @attribute_name: The name of the attribute you want to enable
*
* This function enables a previosuly added attribute
*
* Since it can be costly to add and remove new attributes to buffers; to make
* individual buffers more reuseable it is possible to enable and disable
* attributes before using a buffer for drawing.
*
* Note: You don't need to call cogl_vertex_buffer_submit after using this
* function
*/
void
cogl_vertex_buffer_enable (CoglHandle handle,
const char *attribute_name);
/** /**
* cogl_vertex_buffer_submit: * cogl_vertex_buffer_submit:
* @handle: A vertex buffer handle * @handle: A vertex buffer handle
* *
* This function copies all the user added attributes into buffer objects * This function submits all the user added attributes to the GPU; once
* managed by the OpenGL driver. * submitted the attributes can be used for drawing.
* *
* You should aim to minimize calls to this function. * You should aim to minimize calls to this function since it implies
* validating your data; it potentially incurs a transport cost (especially if
* you are using GLX indirect rendering) and potentially a format conversion
* cost if the GPU doesn't natively support any of the given attribute formats.
*/ */
void void
cogl_vertex_buffer_submit (CoglHandle handle); cogl_vertex_buffer_submit (CoglHandle handle);
@ -203,19 +183,35 @@ cogl_vertex_buffer_submit (CoglHandle handle);
* @handle: A vertex buffer handle * @handle: A vertex buffer handle
* @attribute_name: The name of the attribute you want to disable * @attribute_name: The name of the attribute you want to disable
* *
* This function disables a previosuly added attribute * This function disables a previosuly added attribute.
* *
* Since it can be costly to add and remove new attributes to buffers; to make * Since it can be costly to add and remove new attributes to buffers; to make
* individual buffers more reuseable it is possible to enable and disable * individual buffers more reuseable it is possible to enable and disable
* attributes before using a buffer for drawing. * attributes before using a buffer for drawing.
* *
* Note: You don't need to call cogl_vertex_buffer_submit after using this * You don't need to call cogl_vertex_buffer_submit() after using this function.
* function
*/ */
void void
cogl_vertex_buffer_disable (CoglHandle handle, cogl_vertex_buffer_disable (CoglHandle handle,
const char *attribute_name); const char *attribute_name);
/**
* cogl_vertex_buffer_enable:
* @handle: A vertex buffer handle
* @attribute_name: The name of the attribute you want to enable
*
* This function enables a previosuly disabled attribute.
*
* Since it can be costly to add and remove new attributes to buffers; to make
* individual buffers more reuseable it is possible to enable and disable
* attributes before using a buffer for drawing.
*
* You don't need to call cogl_vertex_buffer_submit() after using this function
*/
void
cogl_vertex_buffer_enable (CoglHandle handle,
const char *attribute_name);
/** /**
* cogl_vertex_buffer_draw: * cogl_vertex_buffer_draw:
* @handle: A vertex buffer handle * @handle: A vertex buffer handle

94
cogl.h.in
View File

@ -435,6 +435,100 @@ void cogl_set_fog (const CoglColor *fog_color,
*/ */
void cogl_paint_init (const CoglColor *color); void cogl_paint_init (const CoglColor *color);
/**
* 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.
*
* 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
*/
void cogl_set_source (CoglHandle material);
/**
* cogl_set_source_color:
* @color: a #CoglColor
*
* Sets the source color using normalized values for each component.
* This color will be used for any subsequent drawing operation.
*
* See also cogl_set_source_color4ub() and cogl_set_source_color4f()
* if you already have the color components.
*
* Since: 1.0
*/
void cogl_set_source_color (const CoglColor *color);
/**
* cogl_set_source_color4ub:
* @red: value of the red channel, between 0 and 255
* @green: value of the green channel, between 0 and 255
* @blue: value of the blue channel, between 0 and 255
* @alpha: value of the alpha channel, between 0 and 255
*
* This is a convenience function for creating a solid fill source material
* from the given color using unsigned bytes for each component. This
* color will be used for any subsequent drawing operation.
*
* The value for each component is an unsigned byte in the range
* between 0 and 255.
*
* Since: 1.0
*/
void cogl_set_source_color4ub (guint8 red,
guint8 green,
guint8 blue,
guint8 alpha);
/**
* cogl_set_source_color4f:
* @red: value of the red channel, between 0 and %1.0
* @green: value of the green channel, between 0 and %1.0
* @blue: value of the blue channel, between 0 and %1.0
* @alpha: value of the alpha channel, between 0 and %1.0
*
* This is a convenience function for creating a solid fill source material
* from the given color using normalized values for each component. This color
* will be used for any subsequent drawing operation.
*
* The value for each component is a fixed point number in the range
* between 0 and %1.0. If the values passed in are outside that
* range, they will be clamped.
*
* Since: 1.0
*/
void cogl_set_source_color4f (float red,
float green,
float blue,
float alpha);
/**
* cogl_set_source_texture:
* @texture_handle: The Cogl texture you want as your source
*
* This is a convenience function for creating a material with the first
* layer set to #texture_handle and setting that material as the source with
* cogl_set_source.
*
* Note: There is no interaction between calls to cogl_set_source_color
* and cogl_set_source_texture. If you need to blend a texture with a color then
* you can create a simple material like this:
* <programlisting>
* material = cogl_material_new ();
* cogl_material_set_color4ub (material, 0xff, 0x00, 0x00, 0x80);
* cogl_material_set_layer (material, 0, tex_handle);
* cogl_set_source (material);
* </programlisting>
*
* Since 1.0
*/
void cogl_set_source_texture (CoglHandle texture_handle);
G_END_DECLS G_END_DECLS
#undef __COGL_H_INSIDE__ #undef __COGL_H_INSIDE__

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

@ -53,17 +53,15 @@
</section> </section>
<xi:include href="xml/cogl.xml"/> <xi:include href="xml/cogl.xml"/>
<xi:include href="xml/cogl-primitives.xml"/> <xi:include href="xml/cogl-color.xml"/>
<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-texture.xml"/>
<xi:include href="xml/cogl-material.xml"/> <xi:include href="xml/cogl-material.xml"/>
<xi:include href="xml/cogl-primitives.xml"/>
<xi:include href="xml/cogl-vertex-buffer.xml"/>
<xi:include href="xml/cogl-matrix.xml"/>
<xi:include href="xml/cogl-shaders.xml"/> <xi:include href="xml/cogl-shaders.xml"/>
<xi:include href="xml/cogl-offscreen.xml"/> <xi:include href="xml/cogl-offscreen.xml"/>
<xi:include href="xml/cogl-fixed.xml"/> <xi:include href="xml/cogl-fixed.xml"/>
<xi:include href="xml/cogl-color.xml"/>
<xi:include href="xml/cogl-vertex-buffer.xml"/>
<xi:include href="xml/cogl-material.xml"/>
</chapter> </chapter>

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

@ -1,6 +1,9 @@
<SECTION> <SECTION>
<FILE>cogl</FILE> <FILE>cogl</FILE>
<TITLE>General API</TITLE> <TITLE>General API</TITLE>
COGL_INVALID_HANDLE
CoglHandle
CoglFuncPtr
COGL_PIXEL_FORMAT_24 COGL_PIXEL_FORMAT_24
COGL_PIXEL_FORMAT_32 COGL_PIXEL_FORMAT_32
COGL_A_BIT COGL_A_BIT
@ -12,6 +15,15 @@ COGL_UNPREMULT_MASK
CoglPixelFormat CoglPixelFormat
CoglBufferTarget CoglBufferTarget
<SUBSECTION> <SUBSECTION>
cogl_create_context
cogl_destroy_context
<SUBSECTION>
CoglFeatureFlags
cogl_get_features
cogl_features_available
cogl_check_extension
cogl_get_proc_address
<SUBSECTION>
cogl_perspective cogl_perspective
cogl_frustum cogl_frustum
cogl_setup_viewport cogl_setup_viewport
@ -26,6 +38,9 @@ cogl_scale
cogl_translate cogl_translate
cogl_rotate cogl_rotate
<SUBSECTION> <SUBSECTION>
cogl_get_bitmasks
cogl_paint_init
<SUBSECTION>
CoglClipStackState CoglClipStackState
cogl_clip_set cogl_clip_set
cogl_clip_set_from_path cogl_clip_set_from_path
@ -38,32 +53,27 @@ cogl_clip_ensure
cogl_enable_depth_test cogl_enable_depth_test
cogl_enable_backface_culling cogl_enable_backface_culling
cogl_fog_set cogl_fog_set
</SECTION>
<SECTION>
<FILE>cogl-util</FILE>
<TITLE>Utility API</TITLE>
cogl_create_context
cogl_destroy_context
COGL_INVALID_HANDLE
CoglHandle
CoglFuncPtr
<SUBSECTION>
CoglFeatureFlags
cogl_get_features
cogl_features_available
<SUBSECTION>
cogl_get_proc_address
cogl_check_extension
cogl_get_bitmasks
cogl_paint_init
<SUBSECTION> <SUBSECTION>
cogl_set_source
cogl_set_source_color
cogl_set_source_color4ub
cogl_set_source_color4f
cogl_set_source_texture
<SUBSECTION Private>
cogl_util_next_p2 cogl_util_next_p2
</SECTION> </SECTION>
<SECTION> <SECTION>
<FILE>cogl-primitives</FILE> <FILE>cogl-primitives</FILE>
<TITLE>Primitives</TITLE> <TITLE>Primitives</TITLE>
<SUBSECTION>
cogl_rectangle
cogl_rectangle_with_texture_coords
cogl_rectangles_with_texture_coords
cogl_rectangle_with_multitexture_coords
cogl_polygon
<SUBSECTION>
cogl_path_new cogl_path_new
cogl_path_move_to cogl_path_move_to
cogl_path_close cogl_path_close
@ -85,18 +95,7 @@ cogl_path_fill
cogl_path_fill_preserve cogl_path_fill_preserve
cogl_path_stroke cogl_path_stroke
cogl_path_stroke_preserve cogl_path_stroke_preserve
cogl_set_source_color
cogl_set_source_color4ub
cogl_set_source_color4f
cogl_set_source_texture
cogl_color cogl_color
<SUBSECTION>
cogl_rectangle
cogl_polygon
cogl_rectangle_with_multitexture_coords
cogl_rectangle_with_texture_coords
cogl_rectangles_with_texture_coords
</SECTION> </SECTION>
<SECTION> <SECTION>
@ -132,7 +131,6 @@ CoglBitmap
cogl_bitmap_new_from_file cogl_bitmap_new_from_file
cogl_bitmap_free cogl_bitmap_free
cogl_bitmap_get_size_from_file cogl_bitmap_get_size_from_file
</SECTION> </SECTION>
<SECTION> <SECTION>
@ -166,13 +164,14 @@ cogl_program_uniform_matrix
<FILE>cogl-offscreen</FILE> <FILE>cogl-offscreen</FILE>
<TITLE>Offscreen Buffers</TITLE> <TITLE>Offscreen Buffers</TITLE>
cogl_offscreen_new_to_texture cogl_offscreen_new_to_texture
cogl_offscreen_new_multisample
cogl_offscreen_ref cogl_offscreen_ref
cogl_offscreen_unref cogl_offscreen_unref
cogl_is_offscreen cogl_is_offscreen
cogl_offscreen_blit cogl_offscreen_blit
cogl_offscreen_blit_region cogl_offscreen_blit_region
cogl_draw_buffer cogl_draw_buffer
<SUBSECTION Private>
cogl_offscreen_new_multisample
</SECTION> </SECTION>
<SECTION> <SECTION>
@ -269,7 +268,6 @@ cogl_color_new
cogl_color_copy cogl_color_copy
cogl_color_free cogl_color_free
cogl_color_set_from_4ub cogl_color_set_from_4ub
cogl_color_set_from_4d
cogl_color_set_from_4f cogl_color_set_from_4f
<SUBSECTION> <SUBSECTION>
@ -294,19 +292,20 @@ cogl_color_get_alpha_float
<SECTION> <SECTION>
<FILE>cogl-vertex-buffer</FILE> <FILE>cogl-vertex-buffer</FILE>
<TITLE>Vertex Buffers</TITLE> <TITLE>Vertex Buffers</TITLE>
CoglVertexBufferAttribFlags
COGL_VERTEX_BUFFER_ATTRIB_FLAG_GL_TYPE_MASK
COGL_VERTEX_BUFFER_ATTRIB_FLAG_TYPE_MASK
cogl_vertex_buffer_new cogl_vertex_buffer_new
cogl_vertex_buffer_ref cogl_vertex_buffer_ref
cogl_vertex_buffer_unref cogl_vertex_buffer_unref
cogl_vertex_buffer_add cogl_vertex_buffer_add
cogl_vertex_buffer_delete cogl_vertex_buffer_delete
cogl_vertex_buffer_enable
cogl_vertex_buffer_disable
cogl_vertex_buffer_submit cogl_vertex_buffer_submit
cogl_vertex_buffer_disable
cogl_vertex_buffer_enable
cogl_vertex_buffer_draw cogl_vertex_buffer_draw
cogl_vertex_buffer_draw_range_elements cogl_vertex_buffer_draw_range_elements
<SUBSECTION Private>
CoglVertexBufferAttribFlags
COGL_VERTEX_BUFFER_ATTRIB_FLAG_GL_TYPE_MASK
COGL_VERTEX_BUFFER_ATTRIB_FLAG_TYPE_MASK
</SECTION> </SECTION>
<SECTION> <SECTION>
@ -323,31 +322,29 @@ cogl_matrix_scale
<SECTION> <SECTION>
<FILE>cogl-material</FILE> <FILE>cogl-material</FILE>
<TITLE>Materials</TITLE> <TITLE>Materials</TITLE>
CoglMaterial
CoglMaterialFlags
cogl_material_new cogl_material_new
cogl_material_ref cogl_material_ref
cogl_material_unref cogl_material_unref
cogl_material_set_ambient
cogl_material_get_ambient
cogl_material_set_ambient_and_diffuse
cogl_material_set_color cogl_material_set_color
cogl_material_set_color4ub cogl_material_set_color4ub
cogl_material_set_color4f
cogl_material_get_color cogl_material_get_color
cogl_material_set_ambient
cogl_material_get_ambient
cogl_material_set_diffuse cogl_material_set_diffuse
cogl_material_get_diffuse cogl_material_get_diffuse
cogl_material_set_ambient_and_diffuse
cogl_material_set_emission cogl_material_set_emission
cogl_material_get_emission cogl_material_get_emission
cogl_material_set_specular cogl_material_set_specular
cogl_material_get_specular cogl_material_get_specular
cogl_material_set_shininess cogl_material_set_shininess
cogl_material_get_shininess cogl_material_get_shininess
cogl_set_source <SUBSECTION Advanced Blending>
CoglMaterialAlphaFunc CoglMaterialAlphaFunc
cogl_material_set_alpha_test_function cogl_material_set_alpha_test_function
CoglMaterialBlendFactor CoglMaterialBlendFactor
cogl_material_set_blend_factors cogl_material_set_blend_factors
CoglMaterialLayer
cogl_material_set_layer cogl_material_set_layer
cogl_material_remove_layer cogl_material_remove_layer
CoglMaterialLayerCombineFunc CoglMaterialLayerCombineFunc
@ -358,14 +355,21 @@ cogl_material_set_layer_combine_arg_src
CoglMaterialLayerCombineOp CoglMaterialLayerCombineOp
cogl_material_set_layer_combine_arg_op cogl_material_set_layer_combine_arg_op
cogl_material_set_layer_matrix cogl_material_set_layer_matrix
<SUBSECTION Private>
CoglMaterial
CoglMaterialFlags
CoglMaterialLayerPrivFlags
cogl_material_set_layer_alpha_combine cogl_material_set_layer_alpha_combine
cogl_material_set_layer_rgb_combine cogl_material_set_layer_rgb_combine
</SECTION>
<SECTION>
<FILE>cogl-material-internals</FILE>
<TITLE>Material Internals</TITLE>
cogl_material_get_cogl_enable_flags cogl_material_get_cogl_enable_flags
CoglMaterialFlushOption CoglMaterialFlushOption
cogl_material_flush_gl_material_state
cogl_material_flush_gl_alpha_func
cogl_material_flush_gl_blend_func
cogl_material_flush_gl_state cogl_material_flush_gl_state
CoglMaterialLayer
cogl_material_get_layers cogl_material_get_layers
CoglMaterialLayerType CoglMaterialLayerType
cogl_material_layer_get_type cogl_material_layer_get_type
@ -373,8 +377,4 @@ CoglMaterialLayerFlags
cogl_material_layer_get_flags cogl_material_layer_get_flags
cogl_material_layer_get_texture cogl_material_layer_get_texture
cogl_material_layer_flush_gl_sampler_state cogl_material_layer_flush_gl_sampler_state
<SUBSECTION Private>
CoglMaterialLayerPrivFlags
</SECTION> </SECTION>