From b1d98c25f4d70bc355e2b4d66c2496ab58b9b60c Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Mon, 20 Jul 2009 12:49:35 +0100 Subject: [PATCH] [doc] Miscellaneous documentation fixes Remove private symbols, and add missing public ones. --- clutter/cogl/cogl-material.h | 79 ++++++++++++++++-------------- clutter/cogl/cogl-types.h | 16 ++++++ clutter/cogl/cogl.h.in | 31 ++++++------ doc/reference/clutter/clutter-sections.txt | 1 - doc/reference/cogl/Makefile.am | 7 +++ doc/reference/cogl/cogl-sections.txt | 22 +-------- 6 files changed, 83 insertions(+), 73 deletions(-) diff --git a/clutter/cogl/cogl-material.h b/clutter/cogl/cogl-material.h index 94ea5b2..3223817 100644 --- a/clutter/cogl/cogl-material.h +++ b/clutter/cogl/cogl-material.h @@ -304,7 +304,7 @@ void cogl_material_get_specular (CoglHandle material, CoglColor *specular); /** * cogl_material_set_shininess: * @material: A CoglMaterial object - * shininess: The desired shininess; range: [0.0, 1.0] + * @shininess: The desired shininess; range: [0.0, 1.0] * * This function sets the materials shininess which determines how * specular highlights are calculated. A higher shininess will produce @@ -441,7 +441,7 @@ void cogl_material_set_alpha_test_function (CoglHandle material, * <channel-mask>=ADD(SRC_COLOR*(<factor>), DST_COLOR*(<factor>)) * * - * NOTE: The brackets around blend factors are currently not optional! + * The brackets around blend factors are currently not optional! * * This is the list of source-names usable as blend factors: * @@ -548,7 +548,7 @@ void cogl_material_remove_layer (CoglHandle material, * @layer_index: Specifies the layer you want define a combine function for * @blend_string: A Cogl blend string * describing the desired texture combine function. - * @error: A GError that may report parse errors or lack of GPU/driver support. + * @error: A #GError that may report parse errors or lack of GPU/driver support. * May be %NULL, in which case a warning will be printed out if an * error is encountered. * @@ -606,33 +606,34 @@ void cogl_material_remove_layer (CoglHandle material, * cogl_material_set_color() * * - *
+ * * Example * This is effectively what the default blending is: - * - * "RGBA = MODULATE (PREVIOUS, TEXTURE)" - * + * |[ + * RGBA = MODULATE (PREVIOUS, TEXTURE) + * ]| * This could be used to cross-fade between two images, using the alpha * component of a constant as the interpolator. The constant color * is given by calling cogl_material_set_layer_constant. - * - * RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A]) - * - *
- * Note: you can't give a multiplication factor for arguments as you can - * with blending. + * |[ + * RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A]) + * ]| + * * - * Returns: TRUE if the blend string was successfully parsed, and the described - * texture combining is supported by the underlying driver/hardware. - * If there was an error, it returns FALSE. + * You can't give a multiplication factor for arguments as you can + * with blending. + * + * Returns: %TRUE if the blend string was successfully parsed, and the + * described texture combining is supported by the underlying driver and + * or hardware. If there was an error, it returns FALSE. * * Since: 1.0 */ gboolean -cogl_material_set_layer_combine (CoglHandle material, - gint layer_index, - const char *blend_string, - GError **error); +cogl_material_set_layer_combine (CoglHandle material, + gint layer_index, + const char *blend_string, + GError **error); /** * cogl_material_set_layer_combine_constant: @@ -653,6 +654,8 @@ void cogl_material_set_layer_combine_constant (CoglHandle material, /** * cogl_material_set_layer_matrix: * @material: A CoglMaterial object + * @layer_index: the index for the layer inside @material + * @matrix: the transformation matrix for the layer * * This function lets you set a matrix that can be used to e.g. translate * and rotate a single layer of a material used to fill your geometry. @@ -663,21 +666,24 @@ void cogl_material_set_layer_matrix (CoglHandle material, /** * cogl_material_get_layers: - * @material: A CoglMaterial object + * @material: a #CoglHandle for a material * * This function lets you access a materials internal list of layers * for iteration. * * Returns: A list of #CoglHandle's that can be passed to the - * cogl_material_layer_* functions. + * cogl_material_layer_* functions. The list is owned by COGL and it + * should not be modified or freed */ -const GList *cogl_material_get_layers (CoglHandle material); +G_CONST_RETURN GList *cogl_material_get_layers (CoglHandle material); /** * cogl_material_get_n_layers: - * @material: A CoglMaterial object + * @material: a #CoglHandle for a material * - * Returns: The number of layers defined for the given material + * Retrieves the number of layers defined for the given @material + * + * Returns: the number of layers * * Since: 1.0 */ @@ -693,14 +699,13 @@ int cogl_material_get_n_layers (CoglHandle material); * * Since: 1.0 */ -typedef enum _CoglMaterialLayerType -{ +typedef enum { /*< prefix=COGL_MATERIAL_LAYER_TYPE >*/ COGL_MATERIAL_LAYER_TYPE_TEXTURE } CoglMaterialLayerType; /** * cogl_material_layer_get_type: - * @layer_handle: A Cogl material layer handle + * @layer_handle: A #CoglHandle for a material layer * * Retrieves the type of the layer * @@ -709,26 +714,28 @@ typedef enum _CoglMaterialLayerType * based layers in the future, you should write code that checks the type * first. * - * Return value: the type of the layer + * Returns: the type of the layer */ CoglMaterialLayerType cogl_material_layer_get_type (CoglHandle layer_handle); /** * cogl_material_layer_get_texture: - * @layer_handle: A CoglMaterialLayer handle + * @layer_handle: A #CoglHandle for a material layer * * This lets you extract a CoglTexture handle for a specific layer. * - * Note: In the future, we may support purely GLSL based layers which will - * likely return COGL_INVALID_HANDLE if you try to get the texture. - * Considering this, you can call cogl_material_layer_get_type first, - * to check it is of type COGL_MATERIAL_LAYER_TYPE_TEXTURE. + * In the future, we may support purely GLSL based layers which will + * likely return %COGL_INVALID_HANDLE if you try to get the texture. + * Considering this, you can call cogl_material_layer_get_type first, + * to check it is of type %COGL_MATERIAL_LAYER_TYPE_TEXTURE. + * + * Returns: a #CoglHandle for the texture inside @layer_handle */ CoglHandle cogl_material_layer_get_texture (CoglHandle layer_handle); /** * cogl_material_layer_get_min_filter: - * @layer_handle: a #CoglHandle for a material layer. + * @layer_handle: a #CoglHandle for a material layer * * Query the currently set downscaling filter for a cogl material layer. * @@ -738,7 +745,7 @@ CoglMaterialFilter cogl_material_layer_get_min_filter (CoglHandle layer_handle); /** * cogl_material_layer_get_mag_filter: - * @layer_handle: a #CoglHandle for a material layer. + * @layer_handle: a #CoglHandle for a material layer * * Query the currently set downscaling filter for a cogl material layer. * diff --git a/clutter/cogl/cogl-types.h b/clutter/cogl/cogl-types.h index db54351..7178d8d 100644 --- a/clutter/cogl/cogl-types.h +++ b/clutter/cogl/cogl-types.h @@ -51,7 +51,23 @@ typedef gpointer CoglHandle; #define COGL_TYPE_HANDLE (cogl_handle_get_type ()) GType cogl_handle_get_type (void) G_GNUC_CONST; +/** + * cogl_handle_ref: + * @handle: a #CoglHandle + * + * Increases the reference count of @handle by 1 + * + * Returns: the handle, with its reference count increased + */ CoglHandle cogl_handle_ref (CoglHandle handle); + +/** + * cogl_handle_unref: + * @handle: a #CoglHandle + * + * Drecreases the reference count of @handle by 1; if the reference + * count reaches 0, the resources allocated by @handle will be freed + */ void cogl_handle_unref (CoglHandle Handle); /** diff --git a/clutter/cogl/cogl.h.in b/clutter/cogl/cogl.h.in index ffa5cce..9d38769 100644 --- a/clutter/cogl/cogl.h.in +++ b/clutter/cogl/cogl.h.in @@ -346,11 +346,11 @@ void cogl_get_viewport (float v[4]); void cogl_set_depth_test_enabled (gboolean setting); /** - * cogl_get_depth_test_enable: + * cogl_get_depth_test_enabled: * * Queries if depth testing has been enabled via cogl_set_depth_test_enable() * - * Returns: TRUE if depth testing is enabled else FALSE + * Returns: %TRUE if depth testing is enabled, and %FALSE otherwise */ gboolean cogl_get_depth_test_enabled (void); @@ -372,7 +372,7 @@ 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 else FALSE + * Returns: %TRUE if backface culling is enabled, and %FALSE otherwise */ gboolean cogl_get_backface_culling_enabled (void); @@ -393,15 +393,13 @@ gboolean cogl_get_backface_culling_enabled (void); * vertices at @z_far are drawn fully with @fog_color. Fogging will remain * enabled until you call cogl_disable_fog(). * - * Note: The fogging functions only work correctly when primitives use - * unmultiplied alpha colors. By default Cogl will premultiply textures - * and cogl_set_source_color will premultiply colors, so unless you - * explicitly load your textures requesting an unmultiplied - * internal_format and use cogl_material_set_color you can only use - * fogging with fully opaque primitives. - * - * We can look to improve this in the future when we can depend on - * fragment shaders. + * The fogging functions only work correctly when primitives use + * unmultiplied alpha colors. By default Cogl will premultiply textures + * and cogl_set_source_color() will premultiply colors, so unless you + * explicitly load your textures requesting an unmultiplied internal format + * and use cogl_material_set_color() you can only use fogging with fully + * opaque primitives. This might improve in the future when we can depend + * on fragment shaders. */ void cogl_set_fog (const CoglColor *fog_color, CoglFogMode mode, @@ -694,10 +692,13 @@ void cogl_pop_draw_buffer (void); /** * CoglReadPixelsFlags: * @COGL_READ_PIXELS_COLOR_BUFFER: Read from the color buffer + * + * Flags for cogl_read_pixels() + * + * Since: 1.0 */ -typedef enum _CoglReadPixelsFlags -{ - COGL_READ_PIXELS_COLOR_BUFFER = 1L<<0 +typedef enum { /*< prefix=COGL_READ_PIXELS >*/ + COGL_READ_PIXELS_COLOR_BUFFER = 1L << 0 } CoglReadPixelsFlags; /** diff --git a/doc/reference/clutter/clutter-sections.txt b/doc/reference/clutter/clutter-sections.txt index 87495cd..7f2649e 100644 --- a/doc/reference/clutter/clutter-sections.txt +++ b/doc/reference/clutter/clutter-sections.txt @@ -291,7 +291,6 @@ ClutterAllocationFlags clutter_actor_allocate clutter_actor_allocate_preferred_size clutter_actor_allocate_available_size -clutter_actor_get_allocation_coords clutter_actor_get_allocation_box clutter_actor_get_allocation_geometry clutter_actor_get_allocation_vertices diff --git a/doc/reference/cogl/Makefile.am b/doc/reference/cogl/Makefile.am index 9f30199..9d7575a 100644 --- a/doc/reference/cogl/Makefile.am +++ b/doc/reference/cogl/Makefile.am @@ -56,6 +56,13 @@ CFILE_GLOB=\ IGNORE_HFILES=\ cogl-defines-gl.h \ cogl-defines-gles.h \ + cogl-internal.h \ + cogl-material-private.h \ + cogl-current-matrix.h \ + cogl-bitmap-private.h \ + cogl-blend-string.h \ + cogl-vertex-buffer-private.h \ + cogl-util.h \ cogl-handle.h \ gl \ gles diff --git a/doc/reference/cogl/cogl-sections.txt b/doc/reference/cogl/cogl-sections.txt index f236673..f340cb0 100644 --- a/doc/reference/cogl/cogl-sections.txt +++ b/doc/reference/cogl/cogl-sections.txt @@ -28,7 +28,6 @@ cogl_features_available cogl_check_extension cogl_get_proc_address cogl_get_option_group -cogl_gl_error_to_string cogl_push_matrix @@ -90,14 +89,12 @@ COGL_TYPE_INDICES_TYPE COGL_TYPE_MATERIAL_ALPHA_FUNC COGL_TYPE_MATERIAL_FILTER COGL_TYPE_MATERIAL_LAYER_TYPE -COGL_TYPE_MATRIX_MODE COGL_TYPE_PIXEL_FORMAT COGL_TYPE_SHADER_TYPE COGL_TYPE_TEXTURE_FLAGS COGL_TYPE_VERTICES_MODE -cogl_util_next_p2 cogl_attribute_type_get_type cogl_buffer_bit_get_type cogl_buffer_target_get_type @@ -110,12 +107,10 @@ cogl_indices_type_get_type cogl_material_alpha_func_get_type cogl_material_filter_get_type cogl_material_layer_type_get_type -cogl_matrix_mode_get_type cogl_pixel_format_get_type cogl_shader_type_get_type cogl_texture_flags_get_type cogl_vertices_mode_get_type -GE COGL_NOTE CoglDebugFlags cogl_debug_flags @@ -380,18 +375,12 @@ CoglIndicesType cogl_vertex_buffer_indices_new cogl_vertex_buffer_draw_elements cogl_vertex_buffer_indices_get_for_quads - -CoglVertexBufferAttribFlags -COGL_VERTEX_BUFFER_ATTRIB_FLAG_GL_TYPE_MASK -COGL_VERTEX_BUFFER_ATTRIB_FLAG_TYPE_MASK
cogl-matrix Matrices CoglMatrix -CoglMatrixMode -CoglMatrixStack cogl_matrix_init_identity cogl_matrix_frustum cogl_matrix_ortho @@ -429,11 +418,7 @@ cogl_material_set_shininess cogl_material_get_shininess CoglMaterialAlphaFunc cogl_material_set_alpha_test_function -CoglBlendStringChannelMask -CoglBlendStringColorSourceType -CoglBlendStringContext CoglBlendStringError -CoglBlendStringFunctionType COGL_BLEND_STRING_ERROR cogl_material_set_blend cogl_material_set_blend_constant @@ -443,23 +428,18 @@ cogl_material_set_layer_combine cogl_material_set_layer_combine_constant cogl_material_set_layer_matrix cogl_material_get_layers +cogl_material_get_n_layers CoglMaterialFilter cogl_material_set_layer_filters cogl_material_layer_get_type cogl_material_layer_get_texture cogl_material_layer_get_min_filter cogl_material_layer_get_mag_filter - -CoglMaterial -CoglMaterialFlags -CoglMaterialLayerFlags -CoglMaterialLayerPrivFlags
cogl-material-internals Material Internals -CoglMaterialLayer cogl_material_get_layers CoglMaterialLayerType cogl_material_layer_get_type -- 2.7.4