mirror of
https://github.com/brl/mutter.git
synced 2024-11-22 16:10:41 -05:00
[docs] Various gtk-doc updates for Cogl
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
parent
c3b8dcd2f0
commit
5901b4d045
55
cogl-color.h
55
cogl-color.h
@ -224,61 +224,6 @@ float cogl_color_get_blue (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
|
||||
|
||||
#endif /* __COGL_COLOR_H__ */
|
||||
|
||||
109
cogl-material.h
109
cogl-material.h
@ -68,7 +68,7 @@ void cogl_material_unref (CoglHandle handle);
|
||||
void cogl_material_set_color (CoglHandle material, const CoglColor *color);
|
||||
|
||||
/**
|
||||
* cogl_material_set_color:
|
||||
* cogl_material_set_color4ub:
|
||||
* @material: A CoglMaterial object
|
||||
* @red: The red component
|
||||
* @green: The green component
|
||||
@ -81,11 +81,31 @@ void cogl_material_set_color (CoglHandle material, const CoglColor *color);
|
||||
*
|
||||
* Since 1.0
|
||||
*/
|
||||
void cogl_material_set_color4ub (CoglHandle handle,
|
||||
guint8 red,
|
||||
guint8 green,
|
||||
guint8 blue,
|
||||
guint8 alpha);
|
||||
void cogl_material_set_color4ub (CoglHandle material,
|
||||
guint8 red,
|
||||
guint8 green,
|
||||
guint8 blue,
|
||||
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:
|
||||
@ -96,7 +116,7 @@ void cogl_material_set_color4ub (CoglHandle handle,
|
||||
*
|
||||
* 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:
|
||||
@ -125,7 +145,7 @@ void cogl_material_set_ambient (CoglHandle material,
|
||||
*
|
||||
* 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:
|
||||
@ -153,7 +173,7 @@ void cogl_material_set_diffuse (CoglHandle material,
|
||||
*
|
||||
* 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:
|
||||
@ -197,7 +217,7 @@ void cogl_material_set_specular (CoglHandle material,
|
||||
*
|
||||
* 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:
|
||||
@ -224,7 +244,7 @@ void cogl_material_set_shininess (CoglHandle material,
|
||||
*
|
||||
* Since 1.0
|
||||
*/
|
||||
float cogl_material_get_shininess (CoglHandle handle);
|
||||
float cogl_material_get_shininess (CoglHandle material);
|
||||
|
||||
/**
|
||||
* cogl_material_set_emission:
|
||||
@ -251,7 +271,7 @@ void cogl_material_set_emission (CoglHandle material,
|
||||
*
|
||||
* Since 1.0
|
||||
*/
|
||||
void cogl_material_get_emission (CoglHandle handle, CoglColor *emission);
|
||||
void cogl_material_get_emission (CoglHandle material, CoglColor *emission);
|
||||
|
||||
/**
|
||||
* CoglMaterialAlphaFunc:
|
||||
@ -660,18 +680,30 @@ void cogl_material_set_layer_matrix (CoglHandle material,
|
||||
gint layer_index,
|
||||
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:
|
||||
* @material: A CoglMaterial object
|
||||
*
|
||||
* 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.
|
||||
* 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.
|
||||
* Note: This API is hopfully just a stop-gap solution. Ideally cogl_enable
|
||||
* will be replaced.
|
||||
*/
|
||||
/* TODO: find a nicer solution! */
|
||||
gulong
|
||||
@ -710,7 +742,7 @@ typedef enum _CoglMaterialLayerType
|
||||
|
||||
/**
|
||||
* cogl_material_layer_get_type:
|
||||
* @material: A CoglMaterial object
|
||||
* @layer_handle: A CoglMaterialLayer handle
|
||||
*
|
||||
* Currently there is only one type of layer defined:
|
||||
* 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:
|
||||
* @layer_handle: A CoglMaterial layer object
|
||||
* @layer_handle: A CoglMaterialLayer 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
|
||||
@ -754,7 +786,7 @@ typedef enum _CoglMaterialLayerFlags
|
||||
|
||||
/**
|
||||
* 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
|
||||
* 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
|
||||
* 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
|
||||
*/
|
||||
void cogl_material_flush_gl_state (CoglHandle material,
|
||||
...) 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
|
||||
|
||||
#endif /* __COGL_MATERIAL_H__ */
|
||||
|
||||
@ -10,9 +10,9 @@ G_BEGIN_DECLS
|
||||
* @short_description: Fuctions for initializing and manipulating 4x4
|
||||
* matrices.
|
||||
*
|
||||
* Matrices are used in Cogl to describe affine model-view transforms and
|
||||
* texture transforms, and projective transforms. This exposes a utility API
|
||||
* that can be used for direct manipulation of these matrices.
|
||||
* Matrices are used in Cogl to describe affine model-view transforms, texture
|
||||
* transforms, and projective transforms. This exposes a utility API that can
|
||||
* 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,
|
||||
* 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
|
||||
* transforms by multiplying multiple matrices in the order you want them
|
||||
* applied.
|
||||
|
||||
@ -38,44 +38,39 @@ G_BEGIN_DECLS
|
||||
/**
|
||||
* SECTION:cogl-vertex-buffer
|
||||
* @short_description: An API for submitting extensible arrays of vertex
|
||||
* attributes to OpenGL in a way that aims to minimise
|
||||
* copying or reformatting of the original data.
|
||||
* attributes to be mapped into the GPU for fast
|
||||
* 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
|
||||
* directly consumed by an OpenGL driver and with awareness of the specific
|
||||
* hardware being used then costly format conversion can also be avoided.
|
||||
* directly consumed by an OpenGL driver and mapped into your GPU for fast
|
||||
* 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
|
||||
* understand that attribute buffers are not that cheap to create but once they
|
||||
* have been submitted they can be stored in GPU addressable memory and can
|
||||
* be quickly reused.
|
||||
* Although this API does allow you to modify attributes after they have been
|
||||
* submitted to the GPU you should be aware that modification is not that
|
||||
* cheap, since it implies validating the new data and potentially the
|
||||
* OpenGL driver will need to reformat it for the GPU.
|
||||
*
|
||||
* Although this API does allow you to modify attribute buffers after they have
|
||||
* been submitted to the GPU you must note that modification is also not that
|
||||
* cheap, so if at all possible think of tricks that let you reuse a static
|
||||
* buffer. To help with this, it is possible to enable and disable individual
|
||||
* 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.
|
||||
* If at all possible think of tricks that let you re-use static attributes,
|
||||
* and if you do need to repeatedly update attributes (e.g. for some kind of
|
||||
* morphing geometry) then only update and re-submit the specific attributes
|
||||
* that have changed.
|
||||
*/
|
||||
|
||||
/**
|
||||
@ -94,7 +89,7 @@ cogl_vertex_buffer_new (guint n_vertices);
|
||||
* @attribute_name: The name of your attribute. It should be a valid GLSL
|
||||
* variable name and standard attribute types must use one
|
||||
* of following built-in names: (Note: they correspond to the
|
||||
* built-in names in GLSL)
|
||||
* built-in names of GLSL)
|
||||
* <itemizedlist>
|
||||
* <listitem>"gl_Color"</listitem>
|
||||
* <listitem>"gl_Normal"</listitem>
|
||||
@ -106,8 +101,7 @@ cogl_vertex_buffer_new (guint n_vertices);
|
||||
* "gl_Color::active" or "gl_Color::inactive"
|
||||
* @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_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT or
|
||||
* GL_DOUBLE)
|
||||
* GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT or GL_FLOAT)
|
||||
* @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]
|
||||
* 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
|
||||
* values are stored sequentially in memory.
|
||||
* @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
|
||||
* of the built-in names to add standard attributes, like positions, colors
|
||||
* and normals or you can add custom attributes for use in shaders.
|
||||
* of the built-in names such as "gl_Vertex", or "glMultiTexCoord0" to add
|
||||
* 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
|
||||
* buffer is used to determine how many attribute values will be read from the
|
||||
* supplied pointer.
|
||||
* The number of vertices declared when calling cogl_vertex_buffer_new()
|
||||
* determines how many attribute values will be read from the supplied pointer.
|
||||
*
|
||||
* Note: the data supplied here isn't copied anywhere until you call
|
||||
* cogl_vertex_buffer_submit, so the supplied pointer must remain valid
|
||||
* until then.
|
||||
* (This is an important optimisation since we can't create the underlying
|
||||
* OpenGL buffer object until we know about all the attributes, and repeatedly
|
||||
* copying large buffers of vertex data may be very costly) If you add
|
||||
* 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)
|
||||
* The data for your attribute isn't copied anywhere until you call
|
||||
* cogl_vertex_buffer_submit(), so the supplied pointer must remain valid
|
||||
* until then. If you are updating an attribute by re-adding it then you will
|
||||
* also 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
|
||||
* interleaved attribute starts no farther than +- stride bytes from the other
|
||||
* attributes it is interleved with. I.e. this is ok:
|
||||
* <programlisting>
|
||||
* |-0-0-0-0-0-0-0-0-0-0|
|
||||
* </programlisting>
|
||||
* This is not ok:
|
||||
* <programlisting>
|
||||
* |- - - - -0-0-0-0-0-0 0 0 0 0|
|
||||
* </programlisting>
|
||||
* (Though you can have multiple groups of interleved attributes)
|
||||
*/
|
||||
void
|
||||
@ -162,38 +157,23 @@ cogl_vertex_buffer_add (CoglHandle handle,
|
||||
* @attribute_name: The name of a previously added attribute
|
||||
*
|
||||
* 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
|
||||
cogl_vertex_buffer_delete (CoglHandle handle,
|
||||
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:
|
||||
* @handle: A vertex buffer handle
|
||||
*
|
||||
* This function copies all the user added attributes into buffer objects
|
||||
* managed by the OpenGL driver.
|
||||
* This function submits all the user added attributes to the GPU; once
|
||||
* 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
|
||||
cogl_vertex_buffer_submit (CoglHandle handle);
|
||||
@ -203,19 +183,35 @@ cogl_vertex_buffer_submit (CoglHandle handle);
|
||||
* @handle: A vertex buffer handle
|
||||
* @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
|
||||
* 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
|
||||
* You don't need to call cogl_vertex_buffer_submit() after using this function.
|
||||
*/
|
||||
void
|
||||
cogl_vertex_buffer_disable (CoglHandle handle,
|
||||
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:
|
||||
* @handle: A vertex buffer handle
|
||||
|
||||
94
cogl.h.in
94
cogl.h.in
@ -435,6 +435,100 @@ void cogl_set_fog (const CoglColor *fog_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
|
||||
|
||||
#undef __COGL_H_INSIDE__
|
||||
|
||||
@ -53,17 +53,15 @@
|
||||
</section>
|
||||
|
||||
<xi:include href="xml/cogl.xml"/>
|
||||
<xi:include href="xml/cogl-primitives.xml"/>
|
||||
<xi:include href="xml/cogl-util.xml"/>
|
||||
<xi:include href="xml/cogl-matrix.xml"/>
|
||||
<xi:include href="xml/cogl-color.xml"/>
|
||||
<xi:include href="xml/cogl-texture.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-offscreen.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>
|
||||
|
||||
|
||||
@ -1,6 +1,9 @@
|
||||
<SECTION>
|
||||
<FILE>cogl</FILE>
|
||||
<TITLE>General API</TITLE>
|
||||
COGL_INVALID_HANDLE
|
||||
CoglHandle
|
||||
CoglFuncPtr
|
||||
COGL_PIXEL_FORMAT_24
|
||||
COGL_PIXEL_FORMAT_32
|
||||
COGL_A_BIT
|
||||
@ -12,6 +15,15 @@ COGL_UNPREMULT_MASK
|
||||
CoglPixelFormat
|
||||
CoglBufferTarget
|
||||
<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_frustum
|
||||
cogl_setup_viewport
|
||||
@ -26,6 +38,9 @@ cogl_scale
|
||||
cogl_translate
|
||||
cogl_rotate
|
||||
<SUBSECTION>
|
||||
cogl_get_bitmasks
|
||||
cogl_paint_init
|
||||
<SUBSECTION>
|
||||
CoglClipStackState
|
||||
cogl_clip_set
|
||||
cogl_clip_set_from_path
|
||||
@ -38,32 +53,27 @@ cogl_clip_ensure
|
||||
cogl_enable_depth_test
|
||||
cogl_enable_backface_culling
|
||||
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>
|
||||
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
|
||||
</SECTION>
|
||||
|
||||
<SECTION>
|
||||
<FILE>cogl-primitives</FILE>
|
||||
<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_move_to
|
||||
cogl_path_close
|
||||
@ -85,18 +95,7 @@ cogl_path_fill
|
||||
cogl_path_fill_preserve
|
||||
cogl_path_stroke
|
||||
cogl_path_stroke_preserve
|
||||
cogl_set_source_color
|
||||
cogl_set_source_color4ub
|
||||
cogl_set_source_color4f
|
||||
cogl_set_source_texture
|
||||
cogl_color
|
||||
|
||||
<SUBSECTION>
|
||||
cogl_rectangle
|
||||
cogl_polygon
|
||||
cogl_rectangle_with_multitexture_coords
|
||||
cogl_rectangle_with_texture_coords
|
||||
cogl_rectangles_with_texture_coords
|
||||
</SECTION>
|
||||
|
||||
<SECTION>
|
||||
@ -132,7 +131,6 @@ CoglBitmap
|
||||
cogl_bitmap_new_from_file
|
||||
cogl_bitmap_free
|
||||
cogl_bitmap_get_size_from_file
|
||||
|
||||
</SECTION>
|
||||
|
||||
<SECTION>
|
||||
@ -166,13 +164,14 @@ cogl_program_uniform_matrix
|
||||
<FILE>cogl-offscreen</FILE>
|
||||
<TITLE>Offscreen Buffers</TITLE>
|
||||
cogl_offscreen_new_to_texture
|
||||
cogl_offscreen_new_multisample
|
||||
cogl_offscreen_ref
|
||||
cogl_offscreen_unref
|
||||
cogl_is_offscreen
|
||||
cogl_offscreen_blit
|
||||
cogl_offscreen_blit_region
|
||||
cogl_draw_buffer
|
||||
<SUBSECTION Private>
|
||||
cogl_offscreen_new_multisample
|
||||
</SECTION>
|
||||
|
||||
<SECTION>
|
||||
@ -269,7 +268,6 @@ cogl_color_new
|
||||
cogl_color_copy
|
||||
cogl_color_free
|
||||
cogl_color_set_from_4ub
|
||||
cogl_color_set_from_4d
|
||||
cogl_color_set_from_4f
|
||||
|
||||
<SUBSECTION>
|
||||
@ -294,19 +292,20 @@ cogl_color_get_alpha_float
|
||||
<SECTION>
|
||||
<FILE>cogl-vertex-buffer</FILE>
|
||||
<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_ref
|
||||
cogl_vertex_buffer_unref
|
||||
cogl_vertex_buffer_add
|
||||
cogl_vertex_buffer_delete
|
||||
cogl_vertex_buffer_enable
|
||||
cogl_vertex_buffer_disable
|
||||
cogl_vertex_buffer_submit
|
||||
cogl_vertex_buffer_disable
|
||||
cogl_vertex_buffer_enable
|
||||
cogl_vertex_buffer_draw
|
||||
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>
|
||||
@ -323,31 +322,29 @@ cogl_matrix_scale
|
||||
<SECTION>
|
||||
<FILE>cogl-material</FILE>
|
||||
<TITLE>Materials</TITLE>
|
||||
CoglMaterial
|
||||
CoglMaterialFlags
|
||||
cogl_material_new
|
||||
cogl_material_ref
|
||||
cogl_material_unref
|
||||
cogl_material_set_ambient
|
||||
cogl_material_get_ambient
|
||||
cogl_material_set_ambient_and_diffuse
|
||||
cogl_material_set_color
|
||||
cogl_material_set_color4ub
|
||||
cogl_material_set_color4f
|
||||
cogl_material_get_color
|
||||
cogl_material_set_ambient
|
||||
cogl_material_get_ambient
|
||||
cogl_material_set_diffuse
|
||||
cogl_material_get_diffuse
|
||||
cogl_material_set_ambient_and_diffuse
|
||||
cogl_material_set_emission
|
||||
cogl_material_get_emission
|
||||
cogl_material_set_specular
|
||||
cogl_material_get_specular
|
||||
cogl_material_set_shininess
|
||||
cogl_material_get_shininess
|
||||
cogl_set_source
|
||||
<SUBSECTION Advanced Blending>
|
||||
CoglMaterialAlphaFunc
|
||||
cogl_material_set_alpha_test_function
|
||||
CoglMaterialBlendFactor
|
||||
cogl_material_set_blend_factors
|
||||
CoglMaterialLayer
|
||||
cogl_material_set_layer
|
||||
cogl_material_remove_layer
|
||||
CoglMaterialLayerCombineFunc
|
||||
@ -358,14 +355,21 @@ cogl_material_set_layer_combine_arg_src
|
||||
CoglMaterialLayerCombineOp
|
||||
cogl_material_set_layer_combine_arg_op
|
||||
cogl_material_set_layer_matrix
|
||||
<SUBSECTION Private>
|
||||
CoglMaterial
|
||||
CoglMaterialFlags
|
||||
CoglMaterialLayerPrivFlags
|
||||
cogl_material_set_layer_alpha_combine
|
||||
cogl_material_set_layer_rgb_combine
|
||||
</SECTION>
|
||||
|
||||
<SECTION>
|
||||
<FILE>cogl-material-internals</FILE>
|
||||
<TITLE>Material Internals</TITLE>
|
||||
cogl_material_get_cogl_enable_flags
|
||||
CoglMaterialFlushOption
|
||||
cogl_material_flush_gl_material_state
|
||||
cogl_material_flush_gl_alpha_func
|
||||
cogl_material_flush_gl_blend_func
|
||||
cogl_material_flush_gl_state
|
||||
CoglMaterialLayer
|
||||
cogl_material_get_layers
|
||||
CoglMaterialLayerType
|
||||
cogl_material_layer_get_type
|
||||
@ -373,8 +377,4 @@ CoglMaterialLayerFlags
|
||||
cogl_material_layer_get_flags
|
||||
cogl_material_layer_get_texture
|
||||
cogl_material_layer_flush_gl_sampler_state
|
||||
|
||||
<SUBSECTION Private>
|
||||
CoglMaterialLayerPrivFlags
|
||||
</SECTION>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user