mirror of
https://github.com/brl/mutter.git
synced 2024-09-19 22:15:54 -04:00
docs: Increase consistency in Cogl documentation
This commit is contained in:
Emmanuele Bassi
parent
fab83d14f4
commit
03439aede8
@ -68,7 +68,7 @@ CoglHandle cogl_texture_new_with_size (guint width,
|
||||
* @filename: the file to load
|
||||
* @flags: Optional flags for the texture, or %COGL_TEXTURE_NONE
|
||||
* @internal_format: the #CoglPixelFormat to use for the GPU storage of the
|
||||
* texture. If COGL_PIXEL_FORMAT_ANY is given then a premultiplied
|
||||
* texture. If %COGL_PIXEL_FORMAT_ANY is given then a premultiplied
|
||||
* format similar to the format of the source data will be used. The
|
||||
* default blending equations of Cogl expect premultiplied color data;
|
||||
* the main use of passing a non-premultiplied format here is if you
|
||||
@ -173,7 +173,7 @@ CoglHandle cogl_texture_new_from_bitmap (CoglHandle bmp_handle,
|
||||
*
|
||||
* Gets whether the given handle references an existing texture object.
|
||||
*
|
||||
* Returns: %TRUE if the handle references a texture,
|
||||
* Return value: %TRUE if the handle references a texture, and
|
||||
* %FALSE otherwise
|
||||
*/
|
||||
gboolean cogl_is_texture (CoglHandle handle);
|
||||
@ -182,9 +182,9 @@ gboolean cogl_is_texture (CoglHandle handle);
|
||||
* cogl_texture_get_width:
|
||||
* @handle: a #CoglHandle for a texture.
|
||||
*
|
||||
* Query the width of a cogl texture.
|
||||
* Queries the width of a cogl texture.
|
||||
*
|
||||
* Returns: the width of the GPU side texture in pixels:
|
||||
* Return value: the width of the GPU side texture in pixels
|
||||
*/
|
||||
guint cogl_texture_get_width (CoglHandle handle);
|
||||
|
||||
@ -192,9 +192,9 @@ guint cogl_texture_get_width (CoglHandle handle);
|
||||
* cogl_texture_get_height:
|
||||
* @handle: a #CoglHandle for a texture.
|
||||
*
|
||||
* Query the height of a cogl texture.
|
||||
* Queries the height of a cogl texture.
|
||||
*
|
||||
* Returns: the height of the GPU side texture in pixels:
|
||||
* Return value: the height of the GPU side texture in pixels
|
||||
*/
|
||||
guint cogl_texture_get_height (CoglHandle handle);
|
||||
|
||||
@ -202,9 +202,9 @@ guint cogl_texture_get_height (CoglHandle handle);
|
||||
* cogl_texture_get_format:
|
||||
* @handle: a #CoglHandle for a texture.
|
||||
*
|
||||
* Query the #CoglPixelFormat of a cogl texture.
|
||||
* Queries the #CoglPixelFormat of a cogl texture.
|
||||
*
|
||||
* Returns: the #CoglPixelFormat of the GPU side texture.
|
||||
* Return value: the #CoglPixelFormat of the GPU side texture
|
||||
*/
|
||||
CoglPixelFormat cogl_texture_get_format (CoglHandle handle);
|
||||
|
||||
@ -213,9 +213,9 @@ CoglPixelFormat cogl_texture_get_format (CoglHandle handle);
|
||||
* cogl_texture_get_rowstride:
|
||||
* @handle: a #CoglHandle for a texture.
|
||||
*
|
||||
* Query the rowstride of a cogl texture.
|
||||
* Queries the rowstride of a cogl texture.
|
||||
*
|
||||
* Returns: the offset in bytes between each consequetive row of pixels.
|
||||
* Return value: the offset in bytes between each consequetive row of pixels
|
||||
*/
|
||||
guint cogl_texture_get_rowstride (CoglHandle handle);
|
||||
|
||||
@ -223,10 +223,10 @@ guint cogl_texture_get_rowstride (CoglHandle handle);
|
||||
* cogl_texture_get_max_waste:
|
||||
* @handle: a #CoglHandle for a texture.
|
||||
*
|
||||
* Query the maximum wasted (unused) pixels in one dimension of a GPU side
|
||||
* Queries the maximum wasted (unused) pixels in one dimension of a GPU side
|
||||
* texture.
|
||||
*
|
||||
* Returns: the maximum waste.
|
||||
* Return value: the maximum waste
|
||||
*/
|
||||
gint cogl_texture_get_max_waste (CoglHandle handle);
|
||||
|
||||
@ -234,11 +234,11 @@ gint cogl_texture_get_max_waste (CoglHandle handle);
|
||||
* cogl_texture_is_sliced:
|
||||
* @handle: a #CoglHandle for a texture.
|
||||
*
|
||||
* Query if a texture is sliced (stored as multiple GPU side tecture
|
||||
* Queries if a texture is sliced (stored as multiple GPU side tecture
|
||||
* objects).
|
||||
*
|
||||
* Returns: %TRUE if the texture is sliced, %FALSE if the texture
|
||||
* is stored as a single GPU texture.
|
||||
* Return value: %TRUE if the texture is sliced, %FALSE if the texture
|
||||
* is stored as a single GPU texture
|
||||
*/
|
||||
gboolean cogl_texture_is_sliced (CoglHandle handle);
|
||||
|
||||
@ -250,12 +250,13 @@ gboolean cogl_texture_is_sliced (CoglHandle handle);
|
||||
* @out_gl_target: (out) (allow-none): pointer to return location for the
|
||||
* GL target type, or %NULL.
|
||||
*
|
||||
* Query the GL handles for a GPU side texture through it's #CoglHandle,
|
||||
* if the texture is spliced the data for the first sub texture will be
|
||||
* Queries the GL handles for a GPU side texture through its #CoglHandle.
|
||||
*
|
||||
* If the texture is spliced the data for the first sub texture will be
|
||||
* queried.
|
||||
*
|
||||
* Returns: %TRUE if the handle was successfully retrieved %FALSE
|
||||
* if the handle was invalid.
|
||||
* Return value: %TRUE if the handle was successfully retrieved, %FALSE
|
||||
* if the handle was invalid
|
||||
*/
|
||||
gboolean cogl_texture_get_gl_texture (CoglHandle handle,
|
||||
GLuint *out_gl_handle,
|
||||
@ -270,10 +271,10 @@ gboolean cogl_texture_get_gl_texture (CoglHandle handle,
|
||||
* @data: memory location to write contents of buffer, or %NULL if we're
|
||||
* only querying the data size through the return value.
|
||||
*
|
||||
* Copy the pixel data from a cogl texture to system memory.
|
||||
* Copies the pixel data from a cogl texture to system memory.
|
||||
*
|
||||
* Returns: the size of the texture data in bytes (or 0 if the texture
|
||||
* is not valid.)
|
||||
* Return value: the size of the texture data in bytes, or 0 if the texture
|
||||
* is not valid
|
||||
*/
|
||||
gint cogl_texture_get_data (CoglHandle handle,
|
||||
CoglPixelFormat format,
|
||||
@ -299,7 +300,8 @@ gint cogl_texture_get_data (CoglHandle handle,
|
||||
* Sets the pixels in a rectangular subregion of @handle from an in-memory
|
||||
* buffer containing pixel data.
|
||||
*
|
||||
* Returns: %TRUE if the subregion upload was successful, otherwise %FALSE.
|
||||
* Return value: %TRUE if the subregion upload was successful, and
|
||||
* %FALSE otherwise
|
||||
*/
|
||||
gboolean cogl_texture_set_region (CoglHandle handle,
|
||||
gint src_x,
|
||||
@ -314,13 +316,17 @@ gboolean cogl_texture_set_region (CoglHandle handle,
|
||||
guint rowstride,
|
||||
const guchar *data);
|
||||
|
||||
#ifndef COGL_DISABLE_DEPRECATED
|
||||
|
||||
/**
|
||||
* cogl_texture_ref:
|
||||
* @handle: a @CoglHandle.
|
||||
*
|
||||
* Increment the reference count for a cogl texture.
|
||||
*
|
||||
* Returns: the @handle.
|
||||
* Deprecated: 1.2: Use cogl_handle_ref() instead
|
||||
*
|
||||
* Return value: the @handle.
|
||||
*/
|
||||
CoglHandle cogl_texture_ref (CoglHandle handle);
|
||||
|
||||
@ -328,10 +334,14 @@ CoglHandle cogl_texture_ref (CoglHandle handle);
|
||||
* cogl_texture_unref:
|
||||
* @handle: a @CoglHandle.
|
||||
*
|
||||
* Deccrement the reference count for a cogl texture.
|
||||
* Decrement the reference count for a cogl texture.
|
||||
*
|
||||
* Deprecated: 1.2: Use cogl_handle_unref() instead
|
||||
*/
|
||||
void cogl_texture_unref (CoglHandle handle);
|
||||
|
||||
#endif /* COGL_DISABLE_DEPRECATED */
|
||||
|
||||
/**
|
||||
* cogl_rectangle_with_texture_coords:
|
||||
* @x1: x coordinate upper left on screen.
|
||||
@ -364,14 +374,14 @@ void cogl_rectangle_with_texture_coords (float x1,
|
||||
* @y1: y coordinate upper left on screen.
|
||||
* @x2: x coordinate lower right on screen.
|
||||
* @y2: y coordinate lower right on screen.
|
||||
* @tex_coords: (in) (array) (transfer none): An array containing groups of 4
|
||||
* float values: [tx1, ty1, tx2, ty2] that are interpreted as two texture
|
||||
* @tex_coords: (in) (array) (transfer none): An array containing groups of
|
||||
* 4 float values: [tx1, ty1, tx2, ty2] that are interpreted as two texture
|
||||
* coordinates; one for the upper left texel, and one for the lower right
|
||||
* texel. Each value should be between 0.0 and 1.0, where the coordinate
|
||||
* (0.0, 0.0) represents the top left of the texture, and (1.0, 1.0) the
|
||||
* bottom right.
|
||||
* @tex_coords_len: The length of the tex_coords array. (e.g. for one layer
|
||||
* and one group of texture coordinates, this would be 4)
|
||||
* and one group of texture coordinates, this would be 4)
|
||||
*
|
||||
* This function draws a rectangle using the current source material to
|
||||
* texture or fill with. As a material may contain multiple texture layers
|
||||
|
||||
@ -39,8 +39,7 @@ G_BEGIN_DECLS
|
||||
/**
|
||||
* SECTION:cogl-vertex-buffer
|
||||
* @short_description: An API for submitting extensible arrays of vertex
|
||||
* attributes to be mapped into the GPU for fast
|
||||
* drawing.
|
||||
* attributes to be mapped into the GPU for fast drawing.
|
||||
*
|
||||
* 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
|
||||
@ -111,8 +110,7 @@ cogl_vertex_buffer_get_n_vertices (CoglHandle handle);
|
||||
*
|
||||
* Since: 1.0
|
||||
*/
|
||||
typedef enum _CoglAttributeType
|
||||
{
|
||||
typedef enum {
|
||||
COGL_ATTRIBUTE_TYPE_BYTE = GL_BYTE,
|
||||
COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE = GL_UNSIGNED_BYTE,
|
||||
COGL_ATTRIBUTE_TYPE_SHORT = GL_SHORT,
|
||||
@ -124,51 +122,53 @@ typedef enum _CoglAttributeType
|
||||
* cogl_vertex_buffer_add:
|
||||
* @handle: A vertex buffer handle
|
||||
* @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 of GLSL)
|
||||
* <itemizedlist>
|
||||
* <listitem>"gl_Color"</listitem>
|
||||
* <listitem>"gl_Normal"</listitem>
|
||||
* <listitem>"gl_MultiTexCoord0, gl_MultiTexCoord1, ..."</listitem>
|
||||
* <listitem>"gl_Vertex"</listitem>
|
||||
* </itemizedlist>
|
||||
* To support adding multiple variations of the same attribute
|
||||
* the name can have a detail component, E.g.
|
||||
* "gl_Color::active" or "gl_Color::inactive"
|
||||
* @n_components: The number of components per attribute and must be 1,2,3 or 4
|
||||
* variable name and standard attribute types must use one of following
|
||||
* built-in names: (Note: they correspond to the built-in names of GLSL)
|
||||
* <itemizedlist>
|
||||
* <listitem>"gl_Color"</listitem>
|
||||
* <listitem>"gl_Normal"</listitem>
|
||||
* <listitem>"gl_MultiTexCoord0, gl_MultiTexCoord1, ..."</listitem>
|
||||
* <listitem>"gl_Vertex"</listitem>
|
||||
* </itemizedlist>
|
||||
* To support adding multiple variations of the same attribute the name
|
||||
* can have a detail component, E.g. "gl_Color::active" or
|
||||
* "gl_Color::inactive"
|
||||
* @n_components: The number of components per attribute and must be 1, 2,
|
||||
* 3 or 4
|
||||
* @type: a #CoglAttributeType specifying the data type of each component.
|
||||
* @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.0, 1.0]
|
||||
* for unsigned values. If GL_FALSE they are converted to floats
|
||||
* directly.
|
||||
* @normalized: If %TRUE, this specifies that values stored in an integer
|
||||
* format should be mapped into the range [-1.0, 1.0] or [0.0, 1.0]
|
||||
* for unsigned values. If %FALSE they are converted to floats
|
||||
* directly.
|
||||
* @stride: This specifies the number of bytes from the start of one attribute
|
||||
* value to the start of the next value (for the same attribute). So
|
||||
* for example with a position interleved with color like this:
|
||||
* XYRGBAXYRGBAXYRGBA, then if each letter represents a byte, the
|
||||
* 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 either call
|
||||
* cogl_vertex_buffer_submit() or issue a draw call.)
|
||||
* value to the start of the next value (for the same attribute). So, for
|
||||
* example, with a position interleved with color like this:
|
||||
* XYRGBAXYRGBAXYRGBA, then if each letter represents a byte, the
|
||||
* 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 either call cogl_vertex_buffer_submit() or
|
||||
* issue a draw call.
|
||||
*
|
||||
* This function lets you add an attribute to a buffer. You either use one
|
||||
* of the built-in names such as "gl_Vertex", or "gl_MultiTexCoord0" to add
|
||||
* standard attributes, like positions, colors and normals or you can add
|
||||
* custom attributes for use in shaders.
|
||||
* Adds an attribute to a buffer.
|
||||
*
|
||||
* You either can use one of the built-in names such as "gl_Vertex", or
|
||||
* "gl_MultiTexCoord0" to add standard attributes, like positions, colors
|
||||
* and normals, or you can add custom attributes for use in shaders.
|
||||
*
|
||||
* The number of vertices declared when calling cogl_vertex_buffer_new()
|
||||
* determines how many attribute values will be read from the supplied pointer.
|
||||
* determines how many attribute values will be read from the supplied
|
||||
* @pointer.
|
||||
*
|
||||
* The data for your attribute isn't copied anywhere until you call
|
||||
* cogl_vertex_buffer_submit(), (or issue a draw call which automatically
|
||||
* submits pending attribute changes) so the supplied pointer must remain
|
||||
* cogl_vertex_buffer_submit(), or issue a draw call which automatically
|
||||
* submits pending attribute changes. so the supplied pointer must remain
|
||||
* valid until then. If you are updating an existing attribute (done by
|
||||
* re-adding it) then you still 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.)
|
||||
* re-adding it) then you still 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 each interleaved
|
||||
* <note>If you are interleving attributes it is assumed that each interleaved
|
||||
* attribute starts no farther than +- stride bytes from the other attributes
|
||||
* it is interleved with. I.e. this is ok:
|
||||
* <programlisting>
|
||||
@ -178,7 +178,7 @@ typedef enum _CoglAttributeType
|
||||
* <programlisting>
|
||||
* |- - - - -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)</note>
|
||||
*/
|
||||
void
|
||||
cogl_vertex_buffer_add (CoglHandle handle,
|
||||
@ -194,8 +194,8 @@ cogl_vertex_buffer_add (CoglHandle handle,
|
||||
* @handle: A vertex buffer 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() or issue a draw call to commit this
|
||||
* Deletes an attribute from a buffer. You will need to call
|
||||
* cogl_vertex_buffer_submit() or issue a draw call to commit this
|
||||
* change to the GPU.
|
||||
*/
|
||||
void
|
||||
@ -206,8 +206,8 @@ cogl_vertex_buffer_delete (CoglHandle handle,
|
||||
* cogl_vertex_buffer_submit:
|
||||
* @handle: A vertex buffer handle
|
||||
*
|
||||
* This function submits all the user added attributes to the GPU; once
|
||||
* submitted the attributes can be used for drawing.
|
||||
* 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 since it implies
|
||||
* validating your data; it potentially incurs a transport cost (especially if
|
||||
@ -222,13 +222,14 @@ 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.
|
||||
* 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.
|
||||
*
|
||||
* 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,
|
||||
@ -239,7 +240,7 @@ cogl_vertex_buffer_disable (CoglHandle handle,
|
||||
* @handle: A vertex buffer handle
|
||||
* @attribute_name: The name of the attribute you want to enable
|
||||
*
|
||||
* This function enables a previosuly disabled attribute.
|
||||
* 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
|
||||
@ -266,8 +267,7 @@ cogl_vertex_buffer_enable (CoglHandle handle,
|
||||
*
|
||||
* Since: 1.0
|
||||
*/
|
||||
typedef enum _CoglVerticesMode
|
||||
{
|
||||
typedef enum {
|
||||
COGL_VERTICES_MODE_POINTS = GL_POINTS,
|
||||
COGL_VERTICES_MODE_LINE_STRIP = GL_LINE_STRIP,
|
||||
COGL_VERTICES_MODE_LINE_LOOP = GL_LINE_LOOP,
|
||||
@ -281,11 +281,11 @@ typedef enum _CoglVerticesMode
|
||||
* cogl_vertex_buffer_draw:
|
||||
* @handle: A vertex buffer handle
|
||||
* @mode: A #CoglVerticesMode specifying how the vertices should be
|
||||
* interpreted.
|
||||
* interpreted.
|
||||
* @first: Specifies the index of the first vertex you want to draw with
|
||||
* @count: Specifies the number of vertices you want to draw.
|
||||
*
|
||||
* This function lets you draw geometry using all or a subset of the
|
||||
* Allows you to draw geometry using all or a subset of the
|
||||
* vertices in a vertex buffer.
|
||||
*
|
||||
* Any un-submitted attribute changes are automatically submitted before
|
||||
@ -306,8 +306,7 @@ cogl_vertex_buffer_draw (CoglHandle handle,
|
||||
* range, since it reduces the size of your index array and can help
|
||||
* reduce the demand on memory bandwidth.
|
||||
*/
|
||||
typedef enum _CoglIndicesType
|
||||
{
|
||||
typedef enum {
|
||||
COGL_INDICES_TYPE_UNSIGNED_BYTE,
|
||||
COGL_INDICES_TYPE_UNSIGNED_SHORT,
|
||||
} CoglIndicesType;
|
||||
@ -315,8 +314,9 @@ typedef enum _CoglIndicesType
|
||||
/**
|
||||
* cogl_vertex_buffer_indices_new:
|
||||
* @indices_type: a #CoglIndicesType specifying the data type used for
|
||||
* the indices.
|
||||
* @indices_array: Specifies the address of your array of indices
|
||||
* the indices.
|
||||
* @indices_array: (array length=indices_len): Specifies the address of
|
||||
* your array of indices
|
||||
* @indices_len: The number of indices in indices_array
|
||||
*
|
||||
* Depending on how much geometry you are submitting it can be worthwhile
|
||||
@ -324,8 +324,8 @@ typedef enum _CoglIndicesType
|
||||
* array allows you to reference vertices multiple times, for example
|
||||
* during triangle strips.
|
||||
*
|
||||
* Returns: A CoglHandle for the indices which you can pass to
|
||||
* cogl_vertex_buffer_draw_elements().
|
||||
* Return value: A CoglHandle for the indices which you can pass to
|
||||
* cogl_vertex_buffer_draw_elements().
|
||||
*/
|
||||
CoglHandle
|
||||
cogl_vertex_buffer_indices_new (CoglIndicesType indices_type,
|
||||
@ -347,13 +347,13 @@ cogl_vertex_buffer_indices_get_type (CoglHandle indices);
|
||||
* cogl_vertex_buffer_draw_elements:
|
||||
* @handle: A vertex buffer handle
|
||||
* @mode: A #CoglVerticesMode specifying how the vertices should be
|
||||
* interpreted.
|
||||
* interpreted.
|
||||
* @indices: A CoglHandle for a set of indices allocated via
|
||||
* cogl_vertex_buffer_indices_new ()
|
||||
* cogl_vertex_buffer_indices_new ()
|
||||
* @min_index: Specifies the minimum vertex index contained in indices
|
||||
* @max_index: Specifies the maximum vertex index contained in indices
|
||||
* @indices_offset: An offset into named indices. The offset marks the first
|
||||
* index to use for drawing.
|
||||
* index to use for drawing.
|
||||
* @count: Specifies the number of vertices you want to draw.
|
||||
*
|
||||
* This function lets you use an array of indices to specify the vertices
|
||||
@ -372,13 +372,17 @@ cogl_vertex_buffer_draw_elements (CoglHandle handle,
|
||||
int indices_offset,
|
||||
int count);
|
||||
|
||||
#ifndef COGL_DISABLE_DEPRECATED
|
||||
|
||||
/**
|
||||
* cogl_vertex_buffer_ref:
|
||||
* @handle: a @CoglHandle.
|
||||
*
|
||||
* Increment the reference count for a vertex buffer
|
||||
*
|
||||
* Returns: the @handle.
|
||||
* Return value: the @handle.
|
||||
*
|
||||
* Deprecated: 1.2: Use cogl_handle_ref() instead
|
||||
*/
|
||||
CoglHandle
|
||||
cogl_vertex_buffer_ref (CoglHandle handle);
|
||||
@ -388,10 +392,14 @@ cogl_vertex_buffer_ref (CoglHandle handle);
|
||||
* @handle: a @CoglHandle.
|
||||
*
|
||||
* Decrement the reference count for a vertex buffer
|
||||
*
|
||||
* Deprecated: 1.2: Use cogl_handle_unref() instead
|
||||
*/
|
||||
void
|
||||
cogl_vertex_buffer_unref (CoglHandle handle);
|
||||
|
||||
#endif /* COGL_DISABLE_DEPRECATED */
|
||||
|
||||
/**
|
||||
* cogl_vertex_buffer_indices_get_for_quads:
|
||||
* @n_indices: the number of indices in the vertex buffer.
|
||||
|
||||
90
cogl/cogl.h
90
cogl/cogl.h
@ -104,7 +104,7 @@ gboolean cogl_features_available (CoglFeatureFlags features);
|
||||
* appropriate function for the current backend.
|
||||
*
|
||||
* Return value: a pointer to the requested function or %NULL if the
|
||||
* function is not available.
|
||||
* function is not available.
|
||||
*/
|
||||
CoglFuncPtr cogl_get_proc_address (const gchar *name);
|
||||
|
||||
@ -115,17 +115,17 @@ CoglFuncPtr cogl_get_proc_address (const gchar *name);
|
||||
*
|
||||
* Check whether @name occurs in list of extensions in @ext.
|
||||
*
|
||||
* Returns: %TRUE if the extension occurs in the list, %FALSE otherwize.
|
||||
* Return value: %TRUE if the extension occurs in the list, %FALSE otherwize.
|
||||
*/
|
||||
gboolean cogl_check_extension (const gchar *name,
|
||||
const gchar *ext);
|
||||
|
||||
/**
|
||||
* cogl_get_bitmasks:
|
||||
* @red: Return location for the number of red bits or %NULL
|
||||
* @green: Return location for the number of green bits or %NULL
|
||||
* @blue: Return location for the number of blue bits or %NULL
|
||||
* @alpha: Return location for the number of alpha bits or %NULL
|
||||
* @red: (out): Return location for the number of red bits or %NULL
|
||||
* @green: (out): Return location for the number of green bits or %NULL
|
||||
* @blue: (out): Return location for the number of blue bits or %NULL
|
||||
* @alpha: (out): Return location for the number of alpha bits or %NULL
|
||||
*
|
||||
* Gets the number of bitplanes used for each of the color components
|
||||
* in the color buffer. Pass %NULL for any of the arguments if the
|
||||
@ -240,12 +240,12 @@ void cogl_viewport (guint width,
|
||||
|
||||
/**
|
||||
* cogl_set_viewport:
|
||||
* @x: viewport X offset
|
||||
* @x: viewport Y offset
|
||||
* @x: X offset of the viewport
|
||||
* @y: Y offset of the viewport
|
||||
* @width: Width of the viewport
|
||||
* @height: Height of the viewport
|
||||
*
|
||||
* Replace the current viewport with the given values.
|
||||
* Replaces the current viewport with the given values.
|
||||
*
|
||||
* Since: 1.2
|
||||
*/
|
||||
@ -257,7 +257,7 @@ void cogl_set_viewport (int x,
|
||||
/**
|
||||
* cogl_push_matrix:
|
||||
*
|
||||
* Store the current model-view matrix on the matrix stack. The matrix
|
||||
* Stores the current model-view matrix on the matrix stack. The matrix
|
||||
* can later be restored with cogl_pop_matrix().
|
||||
*/
|
||||
void cogl_push_matrix (void);
|
||||
@ -265,7 +265,7 @@ void cogl_push_matrix (void);
|
||||
/**
|
||||
* cogl_pop_matrix:
|
||||
*
|
||||
* Restore the current model-view matrix from the matrix stack.
|
||||
* Restores the current model-view matrix from the matrix stack.
|
||||
*/
|
||||
void cogl_pop_matrix (void);
|
||||
|
||||
@ -315,7 +315,7 @@ void cogl_rotate (float angle,
|
||||
|
||||
/**
|
||||
* cogl_get_modelview_matrix:
|
||||
* @matrix: pointer to a CoglMatrix to recieve the matrix
|
||||
* @matrix: (out): return location for the model-view matrix
|
||||
*
|
||||
* Stores the current model-view matrix in @matrix.
|
||||
*/
|
||||
@ -323,15 +323,15 @@ void cogl_get_modelview_matrix (CoglMatrix *matrix);
|
||||
|
||||
/**
|
||||
* cogl_set_modelview_matrix:
|
||||
* @matrix: pointer to a CoglMatrix to set as the new model-view matrix
|
||||
* @matrix: the new model-view matrix
|
||||
*
|
||||
* Loads matrix as the new model-view matrix.
|
||||
* Loads @matrix as the new model-view matrix.
|
||||
*/
|
||||
void cogl_set_modelview_matrix (CoglMatrix *matrix);
|
||||
|
||||
/**
|
||||
* cogl_get_projection_matrix:
|
||||
* @matrix: pointer to a CoglMatrix to recieve the matrix
|
||||
* @matrix: (out): return location for the projection matrix
|
||||
*
|
||||
* Stores the current projection matrix in @matrix.
|
||||
*/
|
||||
@ -339,7 +339,7 @@ void cogl_get_projection_matrix (CoglMatrix *matrix);
|
||||
|
||||
/**
|
||||
* cogl_set_projection_matrix:
|
||||
* @matrix: pointer to a CoglMatrix to set as the new projection matrix
|
||||
* @matrix: the new projection matrix
|
||||
*
|
||||
* Loads matrix as the new projection matrix.
|
||||
*/
|
||||
@ -347,8 +347,8 @@ void cogl_set_projection_matrix (CoglMatrix *matrix);
|
||||
|
||||
/**
|
||||
* cogl_get_viewport:
|
||||
* @v: pointer to a 4 element array of #float<!-- -->s to
|
||||
* receive the viewport dimensions.
|
||||
* @v: (out) (array fixed-size=4): pointer to a 4 element array
|
||||
* of #float<!-- -->s to receive the viewport dimensions.
|
||||
*
|
||||
* Stores the current viewport in @v. @v[0] and @v[1] get the x and y
|
||||
* position of the viewport and @v[2] and @v[3] get the width and
|
||||
@ -373,7 +373,7 @@ void cogl_set_depth_test_enabled (gboolean setting);
|
||||
*
|
||||
* Queries if depth testing has been enabled via cogl_set_depth_test_enable()
|
||||
*
|
||||
* Returns: %TRUE if depth testing is enabled, and %FALSE otherwise
|
||||
* Return value: %TRUE if depth testing is enabled, and %FALSE otherwise
|
||||
*/
|
||||
gboolean cogl_get_depth_test_enabled (void);
|
||||
|
||||
@ -395,19 +395,19 @@ void cogl_set_backface_culling_enabled (gboolean setting);
|
||||
* Queries if backface culling has been enabled via
|
||||
* cogl_set_backface_culling_enabled()
|
||||
*
|
||||
* Returns: %TRUE if backface culling is enabled, and %FALSE otherwise
|
||||
* Return value: %TRUE if backface culling is enabled, and %FALSE otherwise
|
||||
*/
|
||||
gboolean cogl_get_backface_culling_enabled (void);
|
||||
|
||||
/**
|
||||
* cogl_set_fog:
|
||||
* @fog_color: The color of the fog
|
||||
* @mode: A CoglFogMode that determines the equation used to calculate the
|
||||
* fogging blend factor.
|
||||
* @density: Used by the EXPONENTIAL and EXPONENTIAL_SQUARED CoglFogMode
|
||||
* equations.
|
||||
* @z_near: Position along z-axis where no fogging should be applied
|
||||
* @z_far: Position along z-axes where full fogging should be applied
|
||||
* @mode: A #CoglFogMode that determines the equation used to calculate the
|
||||
* fogging blend factor.
|
||||
* @density: Used by %COGL_FOG_MODE_EXPONENTIAL and by
|
||||
* %COGL_FOG_MODE_EXPONENTIAL_SQUARED equations.
|
||||
* @z_near: Position along Z axis where no fogging should be applied
|
||||
* @z_far: Position along Z axis where full fogging should be applied
|
||||
*
|
||||
* Enables fogging. Fogging causes vertices that are further away from the eye
|
||||
* to be rendered with a different color. The color is determined according to
|
||||
@ -468,14 +468,14 @@ void cogl_clear (const CoglColor *color,
|
||||
|
||||
/**
|
||||
* cogl_set_source:
|
||||
* @material: A CoglMaterial object
|
||||
* @material: A #CoglHandle for a 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,
|
||||
* <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.
|
||||
* same.</note>
|
||||
*
|
||||
* Since: 1.0
|
||||
*/
|
||||
@ -867,17 +867,20 @@ void cogl_flush (void);
|
||||
* Note: this doesn't help you modify the behaviour of Cogl drawing functions
|
||||
* through the modification of GL state; that will never be reliably supported,
|
||||
* but if you are trying to do something like:
|
||||
* <programlisting>
|
||||
*
|
||||
* |[
|
||||
* {
|
||||
* - setup some OpenGL state.
|
||||
* - draw using OpenGL (e.g. glDrawArrays() )
|
||||
* - reset modified OpenGL state.
|
||||
* - continue using Cogl to draw
|
||||
* }
|
||||
* </programlisting>
|
||||
* ]|
|
||||
*
|
||||
* You should surround blocks of drawing using raw GL with cogl_begin_gl()
|
||||
* and cogl_end_gl():
|
||||
* <programlisting>
|
||||
*
|
||||
* |[
|
||||
* {
|
||||
* cogl_begin_gl ();
|
||||
* - setup some OpenGL state.
|
||||
@ -886,16 +889,18 @@ void cogl_flush (void);
|
||||
* cogl_end_gl ();
|
||||
* - continue using Cogl to draw
|
||||
* }
|
||||
* </programlisting>
|
||||
* ]|
|
||||
*
|
||||
* Don't ever try and do:
|
||||
* <programlisting>
|
||||
*
|
||||
* |[
|
||||
* {
|
||||
* - setup some OpenGL state.
|
||||
* - use Cogl to draw
|
||||
* - reset modified OpenGL state.
|
||||
* }
|
||||
* </programlisting>
|
||||
* ]|
|
||||
*
|
||||
* When the internals of Cogl evolves, this is very liable to break.
|
||||
*
|
||||
* This function will flush all batched primitives, and subsequently flush
|
||||
@ -907,16 +912,16 @@ void cogl_flush (void);
|
||||
* state such as backface culling, depth and fogging enabledness will be sent
|
||||
* to OpenGL.
|
||||
*
|
||||
* Note: no special material state is flushed, so if you want Cogl to setup a
|
||||
* <note>No special material state is flushed, so if you want Cogl to setup a
|
||||
* simplified material state it is your responsibility to set a simple source
|
||||
* material before calling cogl_begin_gl. E.g. by calling
|
||||
* cogl_set_source_color4ub().
|
||||
* material before calling cogl_begin_gl(). E.g. by calling
|
||||
* cogl_set_source_color4ub().</note>
|
||||
*
|
||||
* Note: It is your responsibility to restore any OpenGL state that you modify
|
||||
* <note>It is your responsibility to restore any OpenGL state that you modify
|
||||
* to how it was after calling cogl_begin_gl() if you don't do this then the
|
||||
* result of further Cogl calls is undefined.
|
||||
* result of further Cogl calls is undefined.</note>
|
||||
*
|
||||
* Note: You can not nest begin/end blocks.
|
||||
* <note>You can not nest begin/end blocks.</note>
|
||||
*
|
||||
* Again we would like to stress, we do not advise the use of this API and if
|
||||
* possible we would prefer to improve Cogl than have developers require raw
|
||||
@ -951,6 +956,7 @@ void _cogl_destroy_context (void);
|
||||
* wasn't complete, and so we assume no one is using this yet. Util we
|
||||
* have some one with a good usecase, we can't pretend to support breaking
|
||||
* out into raw OpenGL. */
|
||||
|
||||
#if 0
|
||||
/*
|
||||
* cogl_flush_gl_state:
|
||||
@ -968,7 +974,7 @@ void _cogl_destroy_context (void);
|
||||
void cogl_flush_gl_state (int flags);
|
||||
#endif
|
||||
|
||||
/* private */
|
||||
/*< private >*/
|
||||
#define COGL_DRIVER_ERROR (_cogl_driver_error_quark ())
|
||||
|
||||
typedef enum { /*< prefix=COGL_DRIVER_ERROR >*/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user