sungmg/mutter-performance-source
1
0
Fork 0
Code Activity

[doc] Miscellaneous documentation fixes

Browse source 
Remove private symbols, and add missing public ones.
This commit is contained in:
Emmanuele Bassi 2009-07-20 12:49:35 +01:00
parent 1da8ce3429
commit d1b8cab65d
5 changed files with 83 additions and 72 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

79
cogl-material.h
View file

@ -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>))
* </programlisting>
*
* <b>NOTE: The brackets around blend factors are currently not optional!</b>
* <warning>The brackets around blend factors are currently not optional!</warning>
*
* This is the list of source-names usable as blend factors:
* <itemizedlist>
@ -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 <link linkend="cogl-Blend-Strings">Cogl blend string</link>
* 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()
* </listitem>
* </itemizedlist>
* <section>
* <refsect2>
* <title>Example</title>
* This is effectively what the default blending is:
* <programlisting>
* "RGBA = MODULATE (PREVIOUS, TEXTURE)"
* </programlisting>
* |[
* 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.
* <programlisting>
* RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])
* </programlisting>
* </section>
* <b>Note: you can't give a multiplication factor for arguments as you can
* with blending.</b>
* |[
* RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])
* ]|
* </refsect2>
*
* 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.
* <note>You can't give a multiplication factor for arguments as you can
* with blending.</note>
*
* 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.
* <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.</note>
*
* 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.
*

16
cogl-types.h
View file

@ -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);
/**

31
cogl.h.in
View file

@ -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.
* <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. This might improve in the future when we can depend
* on fragment shaders.</note>
*/
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;
/**

7
doc/reference/cogl/Makefile.am
View file

@ -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

22
doc/reference/cogl/cogl-sections.txt
View file

@ -28,7 +28,6 @@ cogl_features_available
cogl_check_extension
cogl_get_proc_address
cogl_get_option_group
cogl_gl_error_to_string
<SUBSECTION>
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
<SUBSECTION Private>
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
<SUBSECTION Private>
CoglVertexBufferAttribFlags
COGL_VERTEX_BUFFER_ATTRIB_FLAG_GL_TYPE_MASK
COGL_VERTEX_BUFFER_ATTRIB_FLAG_TYPE_MASK
</SECTION>
<SECTION>
<FILE>cogl-matrix</FILE>
<TITLE>Matrices</TITLE>
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
<SUBSECTION Private>
CoglMaterial
CoglMaterialFlags
CoglMaterialLayerFlags
CoglMaterialLayerPrivFlags
</SECTION>
<SECTION>
<FILE>cogl-material-internals</FILE>
<TITLE>Material Internals</TITLE>
CoglMaterialLayer
cogl_material_get_layers
CoglMaterialLayerType
cogl_material_layer_get_type