diff --git a/clutter/cogl/cogl/cogl-texture.h b/clutter/cogl/cogl/cogl-texture.h index fdd0e38a7..b831d1ae1 100644 --- a/clutter/cogl/cogl/cogl-texture.h +++ b/clutter/cogl/cogl/cogl-texture.h @@ -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 diff --git a/clutter/cogl/cogl/cogl-vertex-buffer.h b/clutter/cogl/cogl/cogl-vertex-buffer.h index 5f7f87088..1a4823e52 100644 --- a/clutter/cogl/cogl/cogl-vertex-buffer.h +++ b/clutter/cogl/cogl/cogl-vertex-buffer.h @@ -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) - * - * "gl_Color" - * "gl_Normal" - * "gl_MultiTexCoord0, gl_MultiTexCoord1, ..." - * "gl_Vertex" - * - * 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) + * + * "gl_Color" + * "gl_Normal" + * "gl_MultiTexCoord0, gl_MultiTexCoord1, ..." + * "gl_Vertex" + * + * 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 + * 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: * @@ -178,7 +178,7 @@ typedef enum _CoglAttributeType * * |- - - - -0-0-0-0-0-0 0 0 0 0| * - * (Though you can have multiple groups of interleved attributes) + * (Though you can have multiple groups of interleved attributes) */ 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. diff --git a/clutter/cogl/cogl/cogl.h b/clutter/cogl/cogl/cogl.h index 2e9772de4..e03688ee6 100644 --- a/clutter/cogl/cogl/cogl.h +++ b/clutter/cogl/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 #floats to - * receive the viewport dimensions. + * @v: (out) (array fixed-size=4): pointer to a 4 element array + * of #floats 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, + * 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. * * 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: - * + * + * |[ * { * - setup some OpenGL state. * - draw using OpenGL (e.g. glDrawArrays() ) * - reset modified OpenGL state. * - continue using Cogl to draw * } - * + * ]| + * * You should surround blocks of drawing using raw GL with cogl_begin_gl() * and cogl_end_gl(): - * + * + * |[ * { * cogl_begin_gl (); * - setup some OpenGL state. @@ -886,16 +889,18 @@ void cogl_flush (void); * cogl_end_gl (); * - continue using Cogl to draw * } - * + * ]| * * Don't ever try and do: - * + * + * |[ * { * - setup some OpenGL state. * - use Cogl to draw * - reset modified OpenGL state. * } - * + * ]| + * * 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 + * 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: It is your responsibility to restore any OpenGL state that you modify + * 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: You can not nest begin/end blocks. + * You can not nest begin/end blocks. * * 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 >*/