isa/mutter
1
0
Fork 0
mirror of https://github.com/brl/mutter.git synced 2024-11-26 18:11:05 -05:00
Code Issues Packages Projects Releases Wiki Activity

[docs] Various gtk-doc fixes for COGL

Browse Source 
Try to keep the gtk-doc errors down to a minimum.
This commit is contained in:
Emmanuele Bassi 2009-06-10 12:50:45 +01:00
parent 19c2e66398
commit bd3254c0f8
8 changed files with 126 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
clutter/cogl/cogl-bitmap.h
View File

@ -47,11 +47,11 @@ G_BEGIN_DECLS
* @filename: the file to load.
* @error: a #GError or %NULL.
*
* Load an image file from disk. This function can be safely called from
* Loads an image file from disk. This function can be safely called from
* within a thread.
*
* Returns: A CoglBitmap to the new loaded image data, or %NULL if loading
* the image failed.
* Returns: a #CoglHandle to the new loaded image data, or
* %COGL_INVALID_HANDLE if loading the image failed.
*
* Since: 1.0
*/
@ -67,6 +67,8 @@ CoglHandle cogl_bitmap_new_from_file (const gchar *filename,
* Parses an image file enough to extract the width and height
* of the bitmap.
*
* Returns: %TRUE if the image was successfully parsed
*
* Since: 1.0
*/
gboolean cogl_bitmap_get_size_from_file (const gchar *filename,

24
clutter/cogl/cogl-material.h
View File

@ -500,7 +500,9 @@ void cogl_material_set_blend_constant (CoglHandle material,
/**
* cogl_material_set_layer:
* @material: A CoglMaterial object
* @material: A #CoglHandle for a material object
* @layer_index: the index of the layer
* @texture: a #CoglHandle for the layer object
*
* In addition to the standard OpenGL lighting model a Cogl material may have
* one or more layers comprised of textures that can be blended together in
@ -510,8 +512,8 @@ void cogl_material_set_blend_constant (CoglHandle material,
* The index values of multiple layers do not have to be consecutive; it is
* only their relative order that is important.
*
* XXX: In the future, we may define other types of material layers, such
* as purely GLSL based layers.
* <note>In the future, we may define other types of material layers, such
* as purely GLSL based layers.</note>
*
* Since 1.0
*/
@ -627,16 +629,16 @@ cogl_material_set_layer_combine (CoglHandle material,
* @material: A CoglMaterial object
* @layer_index: Specifies the layer you want to specify a constant used
* for texture combining
* @color_constant: The constant color you want
* @constant: The constant color you want
*
* When you are using the 'CONSTANT' color source in a layer combine
* description then you can use this function to define its value.
*
* Since 1.0
*/
void cogl_material_set_layer_combine_constant (CoglHandle material,
int layer_index,
CoglColor *constant);
void cogl_material_set_layer_combine_constant (CoglHandle material,
int layer_index,
CoglColor *constant);
/**
* cogl_material_set_layer_matrix:
@ -659,7 +661,7 @@ void cogl_material_set_layer_matrix (CoglHandle material,
* Returns: A list of #CoglHandle<!-- -->'s that can be passed to the
* cogl_material_layer_* functions.
*/
const GList *cogl_material_get_layers (CoglHandle material_handle);
const GList *cogl_material_get_layers (CoglHandle material);
/**
* CoglMaterialLayerType:
@ -680,10 +682,14 @@ typedef enum _CoglMaterialLayerType
* cogl_material_layer_get_type:
* @layer_handle: A Cogl material layer handle
*
* Retrieves the type of the layer
*
* Currently there is only one type of layer defined:
* COGL_MATERIAL_LAYER_TYPE_TEXTURE, but considering we may add purely GLSL
* %COGL_MATERIAL_LAYER_TYPE_TEXTURE, but considering we may add purely GLSL
* based layers in the future, you should write code that checks the type
* first.
*
* Return value: the type of the layer
*/
CoglMaterialLayerType cogl_material_layer_get_type (CoglHandle layer_handle);

32
clutter/cogl/cogl-matrix.h
View File

@ -54,21 +54,24 @@ G_BEGIN_DECLS
* applied.
*
* The transformation of a vertex (x, y, z, w) by a CoglMatrix is given by:
* <programlisting>
* x_new = xx * x + xy * y + xz * z + xw * w
* y_new = yx * x + yy * y + yz * z + yw * w
* z_new = zx * x + zy * y + zz * z + zw * w
* w_new = wx * x + wy * y + wz * z + ww * w
* </programlisting>
*
* |[
* x_new = xx * x + xy * y + xz * z + xw * w
* y_new = yx * x + yy * y + yz * z + yw * w
* z_new = zx * x + zy * y + zz * z + zw * w
* w_new = wx * x + wy * y + wz * z + ww * w
* ]|
*
* Where w is normally 1
*
* Note: You must consider the members of the CoglMatrix structure read only,
* <note>You must consider the members of the CoglMatrix structure read only,
* and all matrix modifications must be done via the cogl_matrix API. This
* allows Cogl to annotate the matrices internally. Violation of this will give
* undefined results. If you need to initialize a matrix with a constant other
* than the identity matrix you can use cogl_matrix_init_from_array().
* than the identity matrix you can use cogl_matrix_init_from_array().</note>
*/
typedef struct _CoglMatrix {
/*< private >*/
/* column 0 */
float xx;
@ -94,8 +97,6 @@ typedef struct _CoglMatrix {
float zw;
float ww;
/*< private >*/
/* Note: we may want to extend this later with private flags
* and a cache of the inverse transform matrix. */
float _padding0[16];
@ -184,11 +185,10 @@ void cogl_matrix_scale (CoglMatrix *matrix,
* @right: coord of right vertical clipping plane
* @bottom: coord of bottom horizontal clipping plane
* @top: coord of top horizontal clipping plane
* @near: positive distance to near depth clipping plane
* @far: positive distance to far depth clipping plane
* @z_near: positive distance to near depth clipping plane
* @z_far: positive distance to far depth clipping plane
*
* Multiplies the matrix by the given frustum perspective matrix.
*
*/
void cogl_matrix_frustum (CoglMatrix *matrix,
float left,
@ -210,7 +210,7 @@ void cogl_matrix_frustum (CoglMatrix *matrix,
*
* Multiplies the matrix by the described perspective matrix
*
* Note: you should be careful not to have to great a z_far / z_near ratio
* Note: you should be careful not to have to great a @z_far / @z_near ratio
* since that will reduce the effectiveness of depth testing since there wont
* be enough precision to identify the depth of objects near to each other.
*/
@ -259,8 +259,10 @@ void cogl_matrix_init_from_array (CoglMatrix *matrix, const float *array);
*
* This casts a CoglMatrix to a float array which can be directly passed to
* OpenGL.
*
* Return value: a pointer to the float array
*/
const float *cogl_matrix_get_array (const CoglMatrix *matrix);
G_CONST_RETURN float *cogl_matrix_get_array (const CoglMatrix *matrix);
/**
* cogl_matrix_transform_point:

4
clutter/cogl/cogl-offscreen.h
View File

@ -55,10 +55,10 @@ G_BEGIN_DECLS
*
* Note: This does not work with sliced Cogl textures.
*
* Returns: a CoglHandle for the new offscreen buffer or COGL_INVALID_HANDLE
* Returns: a #CoglHandle for the new offscreen buffer or %COGL_INVALID_HANDLE
* if it wasn't possible to create the buffer.
*/
CoglHandle cogl_offscreen_new_to_texture (CoglHandle texhandle);
CoglHandle cogl_offscreen_new_to_texture (CoglHandle handle);
/**
* cogl_offscreen_ref:

9
clutter/cogl/cogl-vertex-buffer.h
View File

@ -79,8 +79,9 @@ G_BEGIN_DECLS
* cogl_vertex_buffer_new:
* @n_vertices: The number of vertices that your attributes will correspond to.
*
* This creates a Cogl handle for a new vertex buffer that you can then start
* to add attributes too.
* Creates a new vertex buffer that you can use to add attributes.
*
* Return value: a new #CoglHandle
*/
CoglHandle
cogl_vertex_buffer_new (guint n_vertices);
@ -89,7 +90,9 @@ cogl_vertex_buffer_new (guint n_vertices);
* cogl_vertex_buffer_get_n_vertices:
* @handle: A vertex buffer handle
*
* This returns the number of vertices that @handle represents
* Retrieves the number of vertices that @handle represents
*
* Return value: the number of vertices
*/
guint
cogl_vertex_buffer_get_n_vertices (CoglHandle handle);

6
clutter/cogl/cogl.h.in
View File

@ -334,7 +334,7 @@ void cogl_set_projection_matrix (CoglMatrix *matrix);
void cogl_get_viewport (float v[4]);
/**
* cogl_set_depth_test_enable:
* cogl_set_depth_test_enabled:
* @setting: %TRUE to enable depth testing or %FALSE to disable.
*
* Sets whether depth testing is enabled. If it is disabled then the
@ -343,7 +343,7 @@ void cogl_get_viewport (float v[4]);
* clutter_actor_lower(), otherwise it will also take into account the
* actor's depth. Depth testing is disabled by default.
*/
void cogl_set_depth_test_enable (gboolean setting);
void cogl_set_depth_test_enabled (gboolean setting);
/**
* cogl_get_depth_test_enable:
@ -352,7 +352,7 @@ void cogl_set_depth_test_enable (gboolean setting);
*
* Returns: TRUE if depth testing is enabled else FALSE
*/
gboolean cogl_get_depth_test_enable (void);
gboolean cogl_get_depth_test_enabled (void);
/**
* cogl_set_backface_culling_enabled:

2
doc/reference/cogl/Makefile.am
View File

@ -54,11 +54,9 @@ CFILE_GLOB=\
# Header files to ignore when scanning.
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
IGNORE_HFILES=\
cogl-bitmap.h \
cogl-defines-gl.h \
cogl-defines-gles.h \
cogl-handle.h \
cogl-primitives.h \
gl \
gles

83
doc/reference/cogl/cogl-sections.txt
View File

@ -3,6 +3,10 @@
<TITLE>General API</TITLE>
COGL_INVALID_HANDLE
CoglHandle
cogl_handle_ref
cogl_handle_unref
<SUBSECTION>
CoglFuncPtr
COGL_PIXEL_FORMAT_24
COGL_PIXEL_FORMAT_32
@ -14,12 +18,18 @@ COGL_UNORDERED_MASK
COGL_UNPREMULT_MASK
CoglPixelFormat
CoglBufferTarget
CoglBufferBit
CoglAttributeType
<SUBSECTION>
CoglFeatureFlags
cogl_get_features
cogl_features_available
cogl_check_extension
cogl_get_proc_address
cogl_get_option_group
cogl_gl_error_to_string
<SUBSECTION>
cogl_push_matrix
cogl_pop_matrix
@ -29,14 +39,15 @@ cogl_rotate
cogl_frustum
cogl_perspective
cogl_ortho
<SUBSECTION>
cogl_get_modelview_matrix
cogl_set_modelview_matrix
cogl_get_projection_matrix
cogl_set_projection_matrix
cogl_viewport
cogl_setup_viewport
cogl_get_viewport
<SUBSECTION>
cogl_clear
cogl_get_bitmasks
@ -44,18 +55,61 @@ cogl_set_depth_test_enabled
cogl_get_depth_test_enabled
cogl_set_backface_culling_enabled
cogl_get_backface_culling_enabled
<SUBSECTION>
CoglFogMode
cogl_set_fog
cogl_disable_fog
<SUBSECTION>
cogl_set_source
cogl_set_source_color
cogl_set_source_color4ub
cogl_set_source_color4f
cogl_set_source_texture
<SUBSECTION Standard>
COGL_TYPE_ATTRIBUTE_TYPE
COGL_TYPE_BUFFER_BIT
COGL_TYPE_BUFFER_TARGET
COGL_TYPE_DEBUG_FLAGS
COGL_TYPE_FEATURE_FLAGS
COGL_TYPE_FIXED
COGL_TYPE_FOG_MODE
COGL_TYPE_HANDLE
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
cogl_debug_flags_get_type
cogl_feature_flags_get_type
cogl_fixed_get_type
cogl_fog_mode_get_type
cogl_handle_get_type
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
</SECTION>
<SECTION>
@ -64,6 +118,7 @@ CoglClipStackState
cogl_clip_push
cogl_clip_push_from_path
cogl_clip_push_from_path_preserve
cogl_clip_push_window_rect
cogl_clip_pop
cogl_clip_stack_save
cogl_clip_stack_restore
@ -75,6 +130,7 @@ cogl_clip_ensure
<TITLE>Primitives</TITLE>
<SUBSECTION>
cogl_rectangle
cogl_rectangles
cogl_rectangle_with_texture_coords
cogl_rectangles_with_texture_coords
cogl_rectangle_with_multitexture_coords
@ -141,6 +197,7 @@ cogl_texture_set_region
<SECTION>
<FILE>cogl-shaders</FILE>
<TITLE>Shaders and Programmable Pipeline</TITLE>
CoglShaderType
cogl_create_shader
cogl_shader_ref
cogl_shader_unref
@ -150,6 +207,7 @@ cogl_shader_compile
cogl_shader_get_info_log
cogl_shader_get_type
cogl_shader_is_compiled
<SUBSECTION>
cogl_create_program
cogl_program_ref
@ -174,8 +232,8 @@ cogl_offscreen_ref
cogl_offscreen_unref
cogl_is_offscreen
cogl_set_draw_buffer
<SUBSECTION Private>
cogl_offscreen_new_multisample
cogl_pop_draw_buffer
cogl_push_draw_buffer
</SECTION>
<SECTION>
@ -192,6 +250,7 @@ COGL_FIXED_FROM_FLOAT
COGL_FIXED_TO_FLOAT
COGL_FIXED_FROM_INT
COGL_FIXED_TO_INT
COGL_FIXED_FROM_DOUBLE
COGL_FIXED_TO_DOUBLE
COGL_FLOAT_TO_INT
COGL_FLOAT_TO_UINT
@ -306,8 +365,10 @@ cogl_vertex_buffer_submit
cogl_vertex_buffer_disable
cogl_vertex_buffer_enable
cogl_vertex_buffer_draw
<SUBSECTION>
CoglIndicesType
cogl_vertex_buffer_add_indices
cogl_vertex_buffer_indices_new
cogl_vertex_buffer_delete_indices
cogl_vertex_buffer_draw_elements
cogl_vertex_buffer_indices_get_for_quads
@ -321,7 +382,13 @@ COGL_VERTEX_BUFFER_ATTRIB_FLAG_TYPE_MASK
<FILE>cogl-matrix</FILE>
<TITLE>Matrices</TITLE>
CoglMatrix
CoglMatrixMode
CoglMatrixStack
cogl_matrix_init_identity
cogl_matrix_frustum
cogl_matrix_ortho
cogl_matrix_perspective
cogl_matrix_transform_point
cogl_matrix_multiply
cogl_matrix_rotate
cogl_matrix_translate
@ -354,7 +421,12 @@ cogl_material_set_shininess
cogl_material_get_shininess
CoglMaterialAlphaFunc
cogl_material_set_alpha_test_function
CoglMaterialBlendFactor
CoglBlendStringChannelMask
CoglBlendStringColorSourceType
CoglBlendStringContext
CoglBlendStringError
CoglBlendStringFunctionType
COGL_BLEND_STRING_ERROR
cogl_material_set_blend
cogl_material_set_blend_constant
cogl_material_set_layer
@ -372,6 +444,7 @@ cogl_material_layer_get_mag_filter
<SUBSECTION Private>
CoglMaterial
CoglMaterialFlags
CoglMaterialLayerFlags
CoglMaterialLayerPrivFlags
</SECTION>