diff --git a/clutter/clutter/cally/cally-actor.h b/clutter/clutter/cally/cally-actor.h
index 1f7d0491c..1392633dd 100644
--- a/clutter/clutter/cally/cally-actor.h
+++ b/clutter/clutter/cally/cally-actor.h
@@ -81,9 +81,6 @@ struct _CallyActor
* @notify_clutter: Signal handler for notify signal on Clutter actor
* @add_actor: Signal handler for child-added signal on Clutter actor
* @remove_actor: Signal handler for child-removed signal on Clutter actor
- *
- * The CallyActorClass structure contains
- * only private data
*/
struct _CallyActorClass
{
diff --git a/clutter/clutter/cally/cally-clone.h b/clutter/clutter/cally/cally-clone.h
index 80c5c8425..d6eadf12a 100644
--- a/clutter/clutter/cally/cally-clone.h
+++ b/clutter/clutter/cally/cally-clone.h
@@ -48,12 +48,6 @@ struct _CallyClone
CallyClonePrivate *priv;
};
-/**
- * CallyCloneClass:
- *
- * The CallyCloneClass structure contains only
- * private data
- */
struct _CallyCloneClass
{
/*< private >*/
diff --git a/clutter/clutter/cally/cally-root.h b/clutter/clutter/cally/cally-root.h
index 2bc39f996..649eaccac 100644
--- a/clutter/clutter/cally/cally-root.h
+++ b/clutter/clutter/cally/cally-root.h
@@ -49,12 +49,6 @@ struct _CallyRoot
CallyRootPrivate *priv;
};
-/**
- * CallyRootClass:
- *
- * The CallyRootClass structure contains only
- * private data
- */
struct _CallyRootClass
{
/*< private >*/
diff --git a/clutter/clutter/cally/cally-stage.h b/clutter/clutter/cally/cally-stage.h
index 935dfb095..4fe4e40b7 100644
--- a/clutter/clutter/cally/cally-stage.h
+++ b/clutter/clutter/cally/cally-stage.h
@@ -48,12 +48,6 @@ struct _CallyStage
CallyStagePrivate *priv;
};
-/**
- * CallyStageClass:
- *
- * The CallyStageClass structure contains only
- * private data
- */
struct _CallyStageClass
{
/*< private >*/
diff --git a/clutter/clutter/cally/cally-text.h b/clutter/clutter/cally/cally-text.h
index a566db659..b79a2b85d 100644
--- a/clutter/clutter/cally/cally-text.h
+++ b/clutter/clutter/cally/cally-text.h
@@ -48,12 +48,6 @@ struct _CallyText
CallyTextPrivate *priv;
};
-/**
- * CallyTextClass:
- *
- * The CallyTextClass structure contains only
- * private data
- */
struct _CallyTextClass
{
/*< private >*/
diff --git a/clutter/clutter/cally/cally-util.h b/clutter/clutter/cally/cally-util.h
index 2daac50d4..faaf6a6dc 100644
--- a/clutter/clutter/cally/cally-util.h
+++ b/clutter/clutter/cally/cally-util.h
@@ -48,12 +48,6 @@ struct _CallyUtil
CallyUtilPrivate *priv;
};
-/**
- * CallyUtilClass:
- *
- * The CallyUtilClass structure contains only
- * private data
- */
struct _CallyUtilClass
{
/*< private >*/
diff --git a/clutter/clutter/clutter-actor.c b/clutter/clutter/clutter-actor.c
index deecca55d..ba65dca5f 100644
--- a/clutter/clutter/clutter-actor.c
+++ b/clutter/clutter/clutter-actor.c
@@ -5429,8 +5429,7 @@ clutter_actor_finalize (GObject *object)
* implementation from the first ancestor class for which such an
* implementation is defined.
*
- * The documentation of the ATK
+ * The documentation of the [https://gnome.pages.gitlab.gnome.org/at-spi2-core/atk/](ATK)
* library contains more information about accessible objects and
* their uses.
*
diff --git a/clutter/clutter/clutter-color.c b/clutter/clutter/clutter-color.c
index 25cd8ce95..67df1602e 100644
--- a/clutter/clutter/clutter-color.c
+++ b/clutter/clutter/clutter-color.c
@@ -761,8 +761,7 @@ clutter_color_from_string (ClutterColor *color,
* @color: a #ClutterColor
*
* Returns a textual specification of @color in the hexadecimal form
- * #rrggbbaa, where r,
- * g, b and a are
+ * `#rrggbbaa`, where `r`, `g`, `b` and `a` are
* hexadecimal digits representing the red, green, blue and alpha components
* respectively.
*
diff --git a/cogl/cogl/cogl-atlas-texture.h b/cogl/cogl/cogl-atlas-texture.h
index e342b4258..3008e295b 100644
--- a/cogl/cogl/cogl-atlas-texture.h
+++ b/cogl/cogl/cogl-atlas-texture.h
@@ -60,9 +60,9 @@ G_BEGIN_DECLS
* shared texture atlases using a high-level #CoglAtlasTexture which
* represents a sub-region of one of these atlases.
*
- * A #CoglAtlasTexture is a high-level meta texture which has
+ * A #CoglAtlasTexture is a high-level meta texture which has
* some limitations to be aware of. Please see the documentation for
- * #CoglMetaTexture for more details.
+ * #CoglMetaTexture for more details.
*/
#define COGL_TYPE_ATLAS_TEXTURE (cogl_atlas_texture_get_type ())
#define COGL_ATLAS_TEXTURE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), COGL_TYPE_ATLAS_TEXTURE, CoglAtlasTexture))
@@ -100,13 +100,13 @@ GType cogl_atlas_texture_get_type (void) G_GNUC_CONST;
* using cogl_texture_set_components() and
* cogl_texture_set_premultiplied().
*
- * Allocate call can fail if Cogl considers the internal
+ * Allocate call can fail if Cogl considers the internal
* format to be incompatible with the format of its internal
- * atlases.
+ * atlases.
*
- * The returned #CoglAtlasTexture is a high-level meta-texture
+ * The returned #CoglAtlasTexture is a high-level meta-texture
* with some limitations. See the documentation for #CoglMetaTexture
- * for more details.
+ * for more details.
*
* Returns: (transfer full): A new #CoglAtlasTexture object.
*/
@@ -131,7 +131,7 @@ cogl_atlas_texture_new_with_size (CoglContext *ctx,
* memory. A #CoglAtlasTexture represents a sub-region within one of
* Cogl's shared texture atlases.
*
- * This api will always immediately allocate GPU memory for the
+ * This api will always immediately allocate GPU memory for the
* texture and upload the given data so that the @data pointer does
* not need to remain valid once this function returns. This means it
* is not possible to configure the texture before it is allocated. If
@@ -140,15 +140,15 @@ cogl_atlas_texture_new_with_size (CoglContext *ctx,
* instead create a #CoglBitmap for your data and use
* cogl_atlas_texture_new_from_bitmap() or use
* cogl_atlas_texture_new_with_size() and then upload data using
- * cogl_texture_set_data()
+ * cogl_texture_set_data()
*
- * Allocate call can fail if Cogl considers the internal
+ * Allocate call can fail if Cogl considers the internal
* format to be incompatible with the format of its internal
- * atlases.
+ * atlases.
*
- * The returned #CoglAtlasTexture is a high-level
+ * The returned #CoglAtlasTexture is a high-level
* meta-texture with some limitations. See the documentation for
- * #CoglMetaTexture for more details.
+ * #CoglMetaTexture for more details.
*
* Return value: (transfer full): A new #CoglAtlasTexture object or
* %NULL on failure and @error will be updated.
@@ -181,13 +181,13 @@ cogl_atlas_texture_new_from_data (CoglContext *ctx,
* using cogl_texture_set_components() and
* cogl_texture_set_premultiplied().
*
- * Allocate call can fail if Cogl considers the internal
+ * Allocate call can fail if Cogl considers the internal
* format to be incompatible with the format of its internal
- * atlases.
+ * atlases.
*
- * The returned #CoglAtlasTexture is a high-level meta-texture
+ * The returned #CoglAtlasTexture is a high-level meta-texture
* with some limitations. See the documentation for #CoglMetaTexture
- * for more details.
+ * for more details.
*
* Returns: (transfer full): A new #CoglAtlasTexture object.
*/
diff --git a/cogl/cogl/cogl-attribute-buffer.h b/cogl/cogl/cogl-attribute-buffer.h
index 5f3c52773..fa083a043 100644
--- a/cogl/cogl/cogl-attribute-buffer.h
+++ b/cogl/cogl/cogl-attribute-buffer.h
@@ -107,16 +107,16 @@ cogl_attribute_buffer_new_with_size (CoglContext *context,
*
* You should never pass a %NULL data pointer.
*
- * This function does not report out-of-memory errors back to
+ * This function does not report out-of-memory errors back to
* the caller by returning %NULL and so you can assume this function
- * always succeeds.
+ * always succeeds.
*
- * In the unlikely case that there is an out of memory problem
+ * In the unlikely case that there is an out of memory problem
* then Cogl will abort the application with a message. If your
* application needs to gracefully handle out-of-memory errors then
* you can use cogl_attribute_buffer_new_with_size() and then
* explicitly catch errors with cogl_buffer_set_data() or
- * cogl_buffer_map().
+ * cogl_buffer_map().
*
* Return value: (transfer full): A newly allocated #CoglAttributeBuffer (never %NULL)
*/
diff --git a/cogl/cogl/cogl-attribute.h b/cogl/cogl/cogl-attribute.h
index 91651d03f..7d3d2e966 100644
--- a/cogl/cogl/cogl-attribute.h
+++ b/cogl/cogl/cogl-attribute.h
@@ -65,10 +65,10 @@ G_DECLARE_FINAL_TYPE (CoglAttribute,
* @name: The name of the attribute (used to reference it from GLSL)
* @stride: The number of bytes to jump to get to the next attribute
* value for the next vertex. (Usually
- * sizeof (MyVertex))
+ * `sizeof (MyVertex)`)
* @offset: The byte offset from the start of @attribute_buffer for
* the first attribute value. (Usually
- * offsetof (MyVertex, component0)
+ * `offsetof (MyVertex, component0)`
* @components: The number of components (e.g. 4 for an rgba color or
* 3 for and (x,y,z) position)
* @type: FIXME
@@ -79,50 +79,48 @@ G_DECLARE_FINAL_TYPE (CoglAttribute,
* The @name is used to access the attribute inside a GLSL vertex
* shader and there are some special names you should use if they are
* applicable:
- *
- * "cogl_position_in" (used for vertex positions)
- * "cogl_color_in" (used for vertex colors)
- * "cogl_tex_coord0_in", "cogl_tex_coord1", ...
- * (used for vertex texture coordinates)
- * "cogl_normal_in" (used for vertex normals)
- * "cogl_point_size_in" (used to set the size of points
+ *
+ * - "cogl_position_in" (used for vertex positions)
+ * - "cogl_color_in" (used for vertex colors)
+ * - "cogl_tex_coord0_in", "cogl_tex_coord1", ...
+ * (used for vertex texture coordinates)
+ * - "cogl_normal_in" (used for vertex normals)
+ * - "cogl_point_size_in" (used to set the size of points
* per-vertex. Note this can only be used if
* %COGL_FEATURE_ID_POINT_SIZE_ATTRIBUTE is advertised and
* cogl_pipeline_set_per_vertex_point_size() is called on the pipeline.
- *
- *
*
* The attribute values corresponding to different vertices can either
* be tightly packed or interleaved with other attribute values. For
* example it's common to define a structure for a single vertex like:
- * |[
+ * ```c
* typedef struct
* {
* float x, y, z; /* position attribute */
* float s, t; /* texture coordinate attribute */
* } MyVertex;
- * ]|
+ * ```
*
* And then create an array of vertex data something like:
- * |[
+ * ```c
* MyVertex vertices[100] = { .... }
- * ]|
+ * ```
*
* In this case, to describe either the position or texture coordinate
- * attribute you have to move sizeof (MyVertex) bytes to
+ * attribute you have to move `sizeof (MyVertex)` bytes to
* move from one vertex to the next. This is called the attribute
* @stride. If you weren't interleving attributes and you instead had
* a packed array of float x, y pairs then the attribute stride would
- * be (2 * sizeof (float)). So the @stride is the number of
+ * be `(2 * sizeof (float))`. So the @stride is the number of
* bytes to move to find the attribute value of the next vertex.
*
* Normally a list of attributes starts at the beginning of an array.
- * So for the MyVertex example above the @offset is the
- * offset inside the MyVertex structure to the first
+ * So for the `MyVertex` example above the @offset is the
+ * offset inside the `MyVertex` structure to the first
* component of the attribute. For the texture coordinate attribute
- * the offset would be offsetof (MyVertex, s) or instead of
- * using the offsetof macro you could use sizeof (float) *
- * 3. If you've divided your @array into blocks of non-interleved
+ * the offset would be `offsetof (MyVertex, s)` or instead of
+ * using the offsetof macro you could use `sizeof (float) *
+ * 3`. If you've divided your @array into blocks of non-interleved
* attributes then you will need to calculate the @offset as the number of
* bytes in blocks preceding the attribute you're describing.
*
diff --git a/cogl/cogl/cogl-bitmap.h b/cogl/cogl/cogl-bitmap.h
index a11928267..80c1960f6 100644
--- a/cogl/cogl/cogl-bitmap.h
+++ b/cogl/cogl/cogl-bitmap.h
@@ -105,13 +105,13 @@ cogl_bitmap_new_from_buffer (CoglBuffer *buffer,
* cogl_bitmap_get_buffer(). The #CoglBuffer API can then be
* used to fill the bitmap with data.
*
- * Cogl will try its best to provide a hardware array you can
+ * Cogl will try its best to provide a hardware array you can
* map, write into and effectively do a zero copy upload when creating
* a texture from it with cogl_texture_new_from_bitmap(). For various
* reasons, such arrays are likely to have a stride larger than width
* * bytes_per_pixel. The user must take the stride into account when
* writing into it. The stride can be retrieved with
- * cogl_bitmap_get_rowstride().
+ * cogl_bitmap_get_rowstride().
*
* Return value: (transfer full): a #CoglPixelBuffer representing the
* newly created array or %NULL on failure
diff --git a/cogl/cogl/cogl-buffer.h b/cogl/cogl/cogl-buffer.h
index 1acbf36bd..261148fac 100644
--- a/cogl/cogl/cogl-buffer.h
+++ b/cogl/cogl/cogl-buffer.h
@@ -202,7 +202,7 @@ typedef enum /*< prefix=COGL_BUFFER_BIND_TARGET >*/
* cogl_buffer_map:
* @buffer: a buffer object
* @access: how the mapped buffer will be used by the application
- * @hints: A mask of #CoglBufferMapHints that tell Cogl how
+ * @hints: A mask of `CoglBufferMapHint`s that tell Cogl how
* the data will be modified once mapped.
*
* Maps the buffer into the application address space for direct
@@ -234,7 +234,7 @@ cogl_buffer_map (CoglBuffer *buffer,
* @offset: Offset within the buffer to start the mapping
* @size: The size of data to map
* @access: how the mapped buffer will be used by the application
- * @hints: A mask of #CoglBufferMapHints that tell Cogl how
+ * @hints: A mask of `CoglBufferMapHint`s that tell Cogl how
* the data will be modified once mapped.
* @error: A #GError for catching exceptional errors
*
diff --git a/cogl/cogl/cogl-color.h b/cogl/cogl/cogl-color.h
index de26b4d5d..153fcd24d 100644
--- a/cogl/cogl/cogl-color.h
+++ b/cogl/cogl/cogl-color.h
@@ -440,10 +440,10 @@ cogl_color_unpremultiply (CoglColor *color);
* @v1: a #CoglColor
* @v2: a #CoglColor
*
- * Compares two #CoglColors and checks if they are the same.
+ * Compares two `CoglColor`s and checks if they are the same.
*
* This function can be passed to g_hash_table_new() as the @key_equal_func
- * parameter, when using #CoglColors as keys in a #GHashTable.
+ * parameter, when using `CoglColor`s as keys in a #GHashTable.
*
* Return value: %TRUE if the two colors are the same.
*/
diff --git a/cogl/cogl/cogl-context.h b/cogl/cogl/cogl-context.h
index e760afafe..34d47cb03 100644
--- a/cogl/cogl/cogl-context.h
+++ b/cogl/cogl/cogl-context.h
@@ -73,7 +73,7 @@ G_BEGIN_DECLS
* that can all access the same GPU without having to worry about
* what state other components have left you with.
*
- * Cogl does not maintain internal references to the context for
+ * Cogl does not maintain internal references to the context for
* resources that depend on the context so applications. This is to
* help applications control the lifetime a context without us needing to
* introduce special api to handle the breakup of internal circular
@@ -90,7 +90,7 @@ G_BEGIN_DECLS
* times throughout their lifetime (such as Android applications) they
* should be careful to destroy all context dependent resources, such as
* framebuffers or textures etc before unrefing and destroying the
- * context.
+ * context.
*/
#define COGL_TYPE_CONTEXT (cogl_context_get_type ())
@@ -219,7 +219,7 @@ cogl_has_feature (CoglContext *context, CoglFeatureID feature);
/**
* cogl_has_features:
* @context: A #CoglContext pointer
- * @...: A 0 terminated list of CoglFeatureIDs
+ * @...: A 0 terminated list of `CoglFeatureID`s
*
* Checks if a list of features are all currently available.
*
diff --git a/cogl/cogl/cogl-display.h b/cogl/cogl/cogl-display.h
index 17db86332..fa6f9ec65 100644
--- a/cogl/cogl/cogl-display.h
+++ b/cogl/cogl/cogl-display.h
@@ -86,11 +86,6 @@ G_DECLARE_FINAL_TYPE (CoglDisplay,
* common state of the display pipeline that applies to the whole
* application.
*
- * Many applications don't need to explicitly use
- * cogl_display_new() and can just jump straight to cogl_context_new()
- * and pass a %NULL display argument so Cogl will automatically
- * connect and setup a renderer and display.
- *
* A @display can only be made for a specific choice of renderer which
* is why this takes the @renderer argument.
*
diff --git a/cogl/cogl/cogl-frame-info.h b/cogl/cogl/cogl-frame-info.h
index 1079be20b..2ead975aa 100644
--- a/cogl/cogl/cogl-frame-info.h
+++ b/cogl/cogl/cogl-frame-info.h
@@ -83,8 +83,8 @@ int64_t cogl_frame_info_get_frame_counter (CoglFrameInfo *info);
* The presentation time measured in microseconds, is based on
* CLOCK_MONOTONIC.
*
- * Some buggy Mesa drivers up to 9.0.1 may
- * incorrectly report non-monotonic timestamps.
+ * Some buggy Mesa drivers up to 9.0.1 may
+ * incorrectly report non-monotonic timestamps.
*
* Return value: the presentation time for the frame
*/
@@ -98,11 +98,11 @@ int64_t cogl_frame_info_get_presentation_time_us (CoglFrameInfo *info);
* Gets the refresh rate in Hertz for the output that the frame was on
* at the time the frame was presented.
*
- * Some platforms can't associate a #CoglOutput with a
+ * Some platforms can't associate a #CoglOutput with a
* #CoglFrameInfo object but are able to report a refresh rate via
* this api. Therefore if you need this information then this api is
* more reliable than using cogl_frame_info_get_output() followed by
- * cogl_output_get_refresh_rate().
+ * cogl_output_get_refresh_rate().
*
* Return value: the refresh rate in Hertz
*/
diff --git a/cogl/cogl/cogl-framebuffer.h b/cogl/cogl/cogl-framebuffer.h
index 6da8d26f5..3d9aee093 100644
--- a/cogl/cogl/cogl-framebuffer.h
+++ b/cogl/cogl/cogl-framebuffer.h
@@ -110,12 +110,12 @@ struct _CoglFramebufferClass
* check and handle any errors that might arise from an unsupported
* configuration so that fallback configurations may be tried.
*
- * Many applications don't support any fallback options at least when
+ * Many applications don't support any fallback options at least when
* they are initially developed and in that case the don't need to use this API
* since Cogl will automatically allocate a framebuffer when it first gets
* used. The disadvantage of relying on automatic allocation is that the
* program will abort with an error message if there is an error during
- * automatic allocation.
+ * automatic allocation.
*
* Return value: %TRUE if there were no error allocating the framebuffer, else %FALSE.
*/
@@ -167,9 +167,9 @@ cogl_framebuffer_get_height (CoglFramebuffer *framebuffer);
* contents down by specify and width and height that's half the real
* size of the framebuffer.
*
- * Although the function takes floating point arguments, existing
+ * Although the function takes floating point arguments, existing
* drivers only allow the use of integer values. In the future floating
- * point values will be exposed via a checkable feature.
+ * point values will be exposed via a checkable feature.
*
*/
COGL_EXPORT void
@@ -382,10 +382,10 @@ cogl_framebuffer_set_modelview_matrix (CoglFramebuffer *framebuffer,
* Replaces the current projection matrix with a perspective matrix
* based on the provided values.
*
- * You should be careful not to have to great a @z_far / @z_near
+ * 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 won't be enough precision to identify the depth of
- * objects near to each other.
+ * objects near to each other.
*/
COGL_EXPORT void
cogl_framebuffer_perspective (CoglFramebuffer *framebuffer,
@@ -428,11 +428,11 @@ cogl_framebuffer_frustum (CoglFramebuffer *framebuffer,
* @y_1: The y coordinate for the first horizontal clipping plane
* @x_2: The x coordinate for the second vertical clipping plane
* @y_2: The y coordinate for the second horizontal clipping plane
- * @near: The distance to the near clipping
- * plane (will be negative if the plane is
+ * @near: The *distance* to the near clipping
+ * plane (will be *negative* if the plane is
* behind the viewer)
- * @far: The distance to the far clipping
- * plane (will be negative if the plane is
+ * @far: The *distance* to the far clipping
+ * plane (will be *negative* if the plane is
* behind the viewer)
*
* Replaces the current projection matrix with an orthographic projection
@@ -622,9 +622,9 @@ cogl_framebuffer_get_is_stereo (CoglFramebuffer *framebuffer);
* Returns whether dithering has been requested for the given @framebuffer.
* See cogl_framebuffer_set_dither_enabled() for more details about dithering.
*
- * This may return %TRUE even when the underlying @framebuffer
+ * This may return %TRUE even when the underlying @framebuffer
* display pipeline does not support dithering. This value only represents
- * the user's request for dithering.
+ * the user's request for dithering.
*
* Return value: %TRUE if dithering has been requested or %FALSE if not.
*/
@@ -737,19 +737,19 @@ cogl_framebuffer_set_stereo_mode (CoglFramebuffer *framebuffer,
* as "single-sample" rendering. A value of 1 or greater is referred
* to as "multisample" rendering.
*
- * There are some semantic differences between single-sample
+ * There are some semantic differences between single-sample
* rendering and multisampling with just 1 point sample such as it
* being redundant to use the cogl_framebuffer_resolve_samples() and
* cogl_framebuffer_resolve_samples_region() apis with single-sample
- * rendering.
+ * rendering.
*
- * It's recommended that
+ * It's recommended that
* cogl_framebuffer_resolve_samples_region() be explicitly used at the
* end of rendering to a point sample buffer to minimize the number of
* samples that get resolved. By default Cogl will implicitly resolve
* all framebuffer samples but if only a small region of a
* framebuffer has changed this can lead to redundant work being
- * done.
+ * done.
*
*/
COGL_EXPORT void
@@ -865,7 +865,7 @@ cogl_framebuffer_get_context (CoglFramebuffer *framebuffer);
/**
* cogl_framebuffer_clear:
* @framebuffer: A #CoglFramebuffer
- * @buffers: A mask of #CoglBufferBit's identifying which auxiliary
+ * @buffers: A mask of `CoglBufferBit`s identifying which auxiliary
* buffers to clear
* @color: The color to clear the color buffer too if specified in
* @buffers.
@@ -882,7 +882,7 @@ cogl_framebuffer_clear (CoglFramebuffer *framebuffer,
/**
* cogl_framebuffer_clear4f:
* @framebuffer: A #CoglFramebuffer
- * @buffers: A mask of #CoglBufferBit's identifying which auxiliary
+ * @buffers: A mask of `CoglBufferBit`s identifying which auxiliary
* buffers to clear
* @red: The red component of color to clear the color buffer too if
* specified in @buffers.
@@ -918,13 +918,13 @@ cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer,
* and with the top left corner positioned at (@x_1, @y_1) and the
* bottom right corner positioned at (@x_2, @y_2).
*
- * The position is the position before the rectangle has been
+ * The position is the position before the rectangle has been
* transformed by the model-view matrix and the projection
- * matrix.
+ * matrix.
*
- * If you want to describe a rectangle with a texture mapped on
+ * If you want to describe a rectangle with a texture mapped on
* it then you can use
- * cogl_framebuffer_draw_textured_rectangle().
+ * cogl_framebuffer_draw_textured_rectangle().
*/
COGL_EXPORT void
cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer,
@@ -953,9 +953,9 @@ cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer,
* left corner will have texture coordinates of (@s_1, @t_1) and the
* bottom right corner will have texture coordinates of (@s_2, @t_2).
*
- * The position is the position before the rectangle has been
+ * The position is the position before the rectangle has been
* transformed by the model-view matrix and the projection
- * matrix.
+ * matrix.
*
* This is a high level drawing api that can handle any kind of
* #CoglMetaTexture texture such as #CoglTexture2DSliced textures
@@ -964,10 +964,10 @@ cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer,
* which only support low level texture types that are directly
* supported by GPUs such as #CoglTexture2D.
*
- * The given texture coordinates will only be used for the first
+ * The given texture coordinates will only be used for the first
* texture layer of the pipeline and if your pipeline has more than
* one layer then all other layers will have default texture
- * coordinates of @s_1=0.0 @t_1=0.0 @s_2=1.0 @t_2=1.0
+ * coordinates of @s_1=0.0 @t_1=0.0 @s_2=1.0 @t_2=1.0
*
* The given texture coordinates should always be normalized such that
* (0, 0) corresponds to the top left and (1, 1) corresponds to the
@@ -1009,9 +1009,9 @@ cogl_framebuffer_draw_textured_rectangle (CoglFramebuffer *framebuffer,
* contain multiple texture layers this interface lets you supply
* texture coordinates for each layer of the pipeline.
*
- * The position is the position before the rectangle has been
+ * The position is the position before the rectangle has been
* transformed by the model-view matrix and the projection
- * matrix.
+ * matrix.
*
* This is a high level drawing api that can handle any kind of
* #CoglMetaTexture texture for the first layer such as
@@ -1020,7 +1020,7 @@ cogl_framebuffer_draw_textured_rectangle (CoglFramebuffer *framebuffer,
* such as cogl_primitive_draw() which only support low level texture
* types that are directly supported by GPUs such as #CoglTexture2D.
*
- * This api can not currently handle multiple high-level meta
+ * This api can not currently handle multiple high-level meta
* texture layers. The first layer may be a high level meta texture
* such as #CoglTexture2DSliced but all other layers much be low
* level textures such as #CoglTexture2D.
@@ -1073,9 +1073,9 @@ cogl_framebuffer_draw_multitextured_rectangle (CoglFramebuffer *framebuffer,
* the second rectangle are (coordinates[4], coordinates[5]) and
* (coordinates[6], coordinates[7]) and so on...
*
- * The position is the position before the rectangle has been
+ * The position is the position before the rectangle has been
* transformed by the model-view matrix and the projection
- * matrix.
+ * matrix.
*
* As a general rule for better performance its recommended to use
* this this API instead of calling
@@ -1103,9 +1103,9 @@ cogl_framebuffer_draw_rectangles (CoglFramebuffer *framebuffer,
* @pipeline state in the same way that
* cogl_framebuffer_draw_textured_rectangle() does.
*
- * The position is the position before the rectangle has been
+ * The position is the position before the rectangle has been
* transformed by the model-view matrix and the projection
- * matrix.
+ * matrix.
*
* This is a high level drawing api that can handle any kind of
* #CoglMetaTexture texture such as #CoglTexture2DSliced textures
@@ -1240,7 +1240,7 @@ cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer,
*
* The implementation of the function looks like this:
*
- * |[
+ * ```c
* bitmap = cogl_bitmap_new_for_data (context,
* width, height,
* format,
@@ -1252,7 +1252,7 @@ cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer,
* COGL_READ_PIXELS_COLOR_BUFFER,
* bitmap);
* g_object_unref (bitmap);
- * ]|
+ * ```
*
* Return value: %TRUE if the read succeeded or %FALSE otherwise.
*/
diff --git a/cogl/cogl/cogl-glib-source.h b/cogl/cogl/cogl-glib-source.h
index 8d374a25d..01a0c2e1d 100644
--- a/cogl/cogl/cogl-glib-source.h
+++ b/cogl/cogl/cogl-glib-source.h
@@ -59,8 +59,8 @@ G_BEGIN_DECLS
* use this api in addition later, it is simply enough to use
* cogl_glib_renderer_source_new() instead.
*
- * This api is actually just a thin convenience wrapper around
- * cogl_glib_renderer_source_new()
+ * This api is actually just a thin convenience wrapper around
+ * cogl_glib_renderer_source_new()
*
* Return value: a new #GSource
*/
diff --git a/cogl/cogl/cogl-graphene.h b/cogl/cogl/cogl-graphene.h
index c16f95113..5f9ec3d06 100644
--- a/cogl/cogl/cogl-graphene.h
+++ b/cogl/cogl/cogl-graphene.h
@@ -78,7 +78,7 @@ cogl_graphene_matrix_project_point (const graphene_matrix_t *matrix,
* cogl_graphene_matrix_project_points().
*
* Here's an example with differing input/output strides:
- * |[
+ * ```c
* typedef struct {
* float x,y;
* uint8_t r,g,b,a;
@@ -102,7 +102,7 @@ cogl_graphene_matrix_project_point (const graphene_matrix_t *matrix,
* sizeof (MyOutVertex),
* &results[0].x,
* N_VERTICES);
- * ]|
+ * ```
*/
COGL_EXPORT void
cogl_graphene_matrix_transform_points (const graphene_matrix_t *matrix,
@@ -131,7 +131,7 @@ cogl_graphene_matrix_transform_points (const graphene_matrix_t *matrix,
* the input array to do the transform in-place.
*
* Here's an example with differing input/output strides:
- * |[
+ * ```c
* typedef struct {
* float x,y;
* uint8_t r,g,b,a;
@@ -155,7 +155,7 @@ cogl_graphene_matrix_transform_points (const graphene_matrix_t *matrix,
* sizeof (MyOutVertex),
* &results[0].x,
* N_VERTICES);
- * ]|
+ * ```
*/
COGL_EXPORT void
cogl_graphene_matrix_project_points (const graphene_matrix_t *matrix,
diff --git a/cogl/cogl/cogl-indices.h b/cogl/cogl/cogl-indices.h
index d0b748178..be91fbba6 100644
--- a/cogl/cogl/cogl-indices.h
+++ b/cogl/cogl/cogl-indices.h
@@ -75,7 +75,7 @@ G_BEGIN_DECLS
* index buffer that specifies the 6 vertices by indexing the shared
* vertices multiple times.
*
- * |[
+ * ```c
* CoglVertexP2 quad_vertices[] = {
* {x0, y0}, //0 = top left
* {x1, y1}, //1 = bottom left
@@ -84,7 +84,7 @@ G_BEGIN_DECLS
* };
* //tell the gpu how to interpret the quad as 2 triangles...
* unsigned char indices[] = {0, 1, 2, 0, 2, 3};
- * ]|
+ * ```
*
* Even in the above illustration we see a saving of 10bytes for one
* quad compared to having data for 6 vertices and no indices but if
diff --git a/cogl/cogl/cogl-matrix-stack.h b/cogl/cogl/cogl-matrix-stack.h
index 5b56611e0..a679da227 100644
--- a/cogl/cogl/cogl-matrix-stack.h
+++ b/cogl/cogl/cogl-matrix-stack.h
@@ -71,14 +71,12 @@
* Compared to using the #graphene_matrix_t api directly to track many
* related transforms, these can be some advantages to using a
* #CoglMatrixStack:
- *
- * Faster equality comparisons of transformations
- * Efficient comparisons of the differences between arbitrary
- * transformations
- * Avoid redundant arithmetic related to common transforms
- *
- * Can be more space efficient (not always though)
- *
+ *
+ * - Faster equality comparisons of transformations
+ * - Efficient comparisons of the differences between arbitrary
+ * transformations
+ * - Avoid redundant arithmetic related to common transforms
+ * - Can be more space efficient (not always though)
*
* For reference (to give an idea of when a #CoglMatrixStack can
* provide a space saving) a #graphene_matrix_t can be expected to take 72
@@ -172,9 +170,9 @@ G_DECLARE_FINAL_TYPE (CoglMatrixStack,
* comparison but often these false negatives are unlikely and
* don't matter anyway so this enables extremely cheap comparisons.
*
- * #CoglMatrixEntrys are reference counted using
+ * `CoglMatrixEntry`s are reference counted using
* cogl_matrix_entry_ref() and cogl_matrix_entry_unref() not with
- * g_object_ref() and g_object_unref().
+ * g_object_ref() and g_object_unref().
*/
typedef struct _CoglMatrixEntry CoglMatrixEntry;
@@ -370,10 +368,10 @@ cogl_matrix_stack_frustum (CoglMatrixStack *stack,
* Replaces the current matrix with a perspective matrix based on the
* provided values.
*
- * You should be careful not to have too great a @z_far / @z_near
+ * You should be careful not to have too great a @z_far / @z_near
* ratio since that will reduce the effectiveness of depth testing
* since there won't be enough precision to identify the depth of
- * objects near to each other.
+ * objects near to each other.
*/
COGL_EXPORT void
cogl_matrix_stack_perspective (CoglMatrixStack *stack,
@@ -389,11 +387,11 @@ cogl_matrix_stack_perspective (CoglMatrixStack *stack,
* @y_1: The y coordinate for the first horizontal clipping plane
* @x_2: The x coordinate for the second vertical clipping plane
* @y_2: The y coordinate for the second horizontal clipping plane
- * @near: The distance to the near clipping
- * plane (will be negative if the plane is
+ * @near: The *distance* to the near clipping
+ * plane (will be *negative* if the plane is
* behind the viewer)
- * @far: The distance to the far clipping
- * plane (will be negative if the plane is
+ * @far: The *distance* to the far clipping
+ * plane (will be *negative* if the plane is
* behind the viewer)
*
* Replaces the current matrix with an orthographic projection matrix.
@@ -430,13 +428,13 @@ cogl_matrix_stack_get_inverse (CoglMatrixStack *stack,
* Gets a reference to the current transform represented by a
* #CoglMatrixEntry pointer.
*
- * The transform represented by a #CoglMatrixEntry is
- * immutable.
+ * The transform represented by a #CoglMatrixEntry is
+ * immutable.
*
- * #CoglMatrixEntrys are reference counted using
+ * `CoglMatrixEntry`s are reference counted using
* cogl_matrix_entry_ref() and cogl_matrix_entry_unref() and you
* should call cogl_matrix_entry_unref() when you are finished with
- * and entry you get via cogl_matrix_stack_get_entry().
+ * and entry you get via cogl_matrix_stack_get_entry().
*
* Return value: (transfer none): A pointer to the #CoglMatrixEntry
* representing the current matrix stack transform.
@@ -463,8 +461,8 @@ cogl_matrix_stack_get_entry (CoglMatrixStack *stack);
* if the function returns %NULL then @matrix will be initialized
* to match the current transform of @stack.
*
- * @matrix will be left untouched if a direct pointer is
- * returned.
+ * @matrix will be left untouched if a direct pointer is
+ * returned.
*
* Return value: A direct pointer to the current transform or %NULL
* and in that case @matrix will be initialized with
@@ -494,8 +492,8 @@ cogl_matrix_stack_get (CoglMatrixStack *stack,
* if the function returns %NULL then @matrix will be initialized
* to match the transform of @entry.
*
- * @matrix will be left untouched if a direct pointer is
- * returned.
+ * @matrix will be left untouched if a direct pointer is
+ * returned.
*
* Return value: A direct pointer to a #graphene_matrix_t transform or %NULL
* and in that case @matrix will be initialized with
@@ -570,9 +568,9 @@ cogl_matrix_entry_is_identity (CoglMatrixEntry *entry);
* Compares two arbitrary #CoglMatrixEntry transforms for equality
* returning %TRUE if they are equal or %FALSE otherwise.
*
- * In many cases it is unnecessary to use this api and instead
+ * In many cases it is unnecessary to use this api and instead
* direct pointer comparisons of entries are good enough and much
- * cheaper too.
+ * cheaper too.
*
* Return value: %TRUE if @entry0 represents the same transform as
* @entry1, otherwise %FALSE.
diff --git a/cogl/cogl/cogl-meta-texture.h b/cogl/cogl/cogl-meta-texture.h
index ec86ea61b..0d4421379 100644
--- a/cogl/cogl/cogl-meta-texture.h
+++ b/cogl/cogl/cogl-meta-texture.h
@@ -44,12 +44,12 @@ G_BEGIN_DECLS
* low-level textures like #CoglTexture2D.
*
* Cogl helps to make it easy to deal with high level textures such
- * as #CoglAtlasTextures, #CoglSubTextures,
+ * as `CoglAtlasTexture`s, `CoglSubTexture`s,
* #CoglTexturePixmapX11 textures and #CoglTexture2DSliced textures
* consistently.
*
* A #CoglMetaTexture is a texture that might internally be
- * represented by one or more low-level #CoglTextures
+ * represented by one or more low-level `CoglTexture`s
* such as #CoglTexture2D. These low-level textures are the only ones
* that a GPU really understands but because applications often want
* more high-level texture abstractions (such as storing multiple
@@ -76,17 +76,17 @@ G_BEGIN_DECLS
*
* If you want to develop custom primitive APIs like
* cogl_framebuffer_draw_rectangle() and you want to support drawing
- * with #CoglAtlasTextures or #CoglSubTextures for
+ * with `CoglAtlasTexture`s or `CoglSubTexture`s for
* example, then you will need to use this #CoglMetaTexture interface
* to be able to resolve high-level textures into low-level textures
* before drawing with Cogl's low-level drawing APIs such as
* cogl_primitive_draw().
*
- * Most developers won't need to use this interface directly
+ * Most developers won't need to use this interface directly
* but still it is worth understanding the distinction between
* low-level and meta textures because you may find other references
* in the documentation that detail limitations of using
- * meta-textures.
+ * meta-textures.
*/
/**
@@ -110,7 +110,7 @@ G_BEGIN_DECLS
* cogl_meta_texture_foreach_in_region().
*
* A callback used with cogl_meta_texture_foreach_in_region() to
- * retrieve details of all the low-level #CoglTextures that
+ * retrieve details of all the low-level `CoglTexture`s that
* make up a given #CoglMetaTexture.
*/
typedef void (*CoglMetaTextureCallback) (CoglTexture *sub_texture,
@@ -150,10 +150,10 @@ typedef void (*CoglMetaTextureCallback) (CoglTexture *sub_texture,
* internally use this API to resolve the low level textures of any
* meta textures you have associated with CoglPipeline layers.
*
- * The low level drawing APIs such as cogl_primitive_draw()
+ * The low level drawing APIs such as cogl_primitive_draw()
* don't understand the #CoglMetaTexture interface and so it is your
* responsibility to use this API to resolve all CoglPipeline textures
- * into low-level textures before drawing.
+ * into low-level textures before drawing.
*
* For each low-level texture that makes up part of the given region
* of the @meta_texture, @callback is called specifying how the
diff --git a/cogl/cogl/cogl-offscreen.h b/cogl/cogl/cogl-offscreen.h
index 9be635439..277acb615 100644
--- a/cogl/cogl/cogl-offscreen.h
+++ b/cogl/cogl/cogl-offscreen.h
@@ -68,9 +68,9 @@ G_DECLARE_FINAL_TYPE (CoglOffscreen, cogl_offscreen,
* updates the contents of the given texture. You don't need to
* destroy the offscreen buffer before you can use the @texture again.
*
- * This api only works with low-level #CoglTexture types such as
+ * This api only works with low-level #CoglTexture types such as
* #CoglTexture2D and not with meta-texture types such as
- * #CoglTexture2DSliced.
+ * #CoglTexture2DSliced.
*
* The storage for the framebuffer is actually allocated lazily
* so this function will never return %NULL to indicate a runtime
diff --git a/cogl/cogl/cogl-onscreen-template.h b/cogl/cogl/cogl-onscreen-template.h
index 1d632b8f8..40d83e527 100644
--- a/cogl/cogl/cogl-onscreen-template.h
+++ b/cogl/cogl/cogl-onscreen-template.h
@@ -67,11 +67,11 @@ cogl_onscreen_template_new (CoglSwapChain *swap_chain);
* as "single-sample" rendering. A value of 1 or greater is referred
* to as "multisample" rendering.
*
- * There are some semantic differences between single-sample
+ * There are some semantic differences between single-sample
* rendering and multisampling with just 1 point sample such as it
* being redundant to use the cogl_framebuffer_resolve_samples() and
* cogl_framebuffer_resolve_samples_region() apis with single-sample
- * rendering.
+ * rendering.
*/
COGL_EXPORT void
cogl_onscreen_template_set_samples_per_pixel (
diff --git a/cogl/cogl/cogl-onscreen.h b/cogl/cogl/cogl-onscreen.h
index 6e2c9ef85..1dea0860d 100644
--- a/cogl/cogl/cogl-onscreen.h
+++ b/cogl/cogl/cogl-onscreen.h
@@ -113,11 +113,11 @@ typedef enum _CoglScanoutError
* cogl_onscreen_show() and set its own type directly with the Wayland
* client API via cogl_wayland_onscreen_get_surface().
*
- * Since Cogl doesn't explicitly track the visibility status of
+ * Since Cogl doesn't explicitly track the visibility status of
* onscreen framebuffers it won't try to avoid redundant window system
* requests e.g. to show an already visible window. This also means
* that it's acceptable to alternatively use native APIs to show and
- * hide windows without confusing Cogl.
+ * hide windows without confusing Cogl.
*/
COGL_EXPORT void
cogl_onscreen_show (CoglOnscreen *onscreen);
@@ -135,11 +135,11 @@ cogl_onscreen_show (CoglOnscreen *onscreen);
* This function does not implicitly allocate the given @onscreen
* framebuffer before hiding it.
*
- * Since Cogl doesn't explicitly track the visibility status of
+ * Since Cogl doesn't explicitly track the visibility status of
* onscreen framebuffers it won't try to avoid redundant window system
* requests e.g. to show an already visible window. This also means
* that it's acceptable to alternatively use native APIs to show and
- * hide windows without confusing Cogl.
+ * hide windows without confusing Cogl.
*/
COGL_EXPORT void
cogl_onscreen_hide (CoglOnscreen *onscreen);
@@ -156,11 +156,11 @@ cogl_onscreen_hide (CoglOnscreen *onscreen);
* start a new frame that incrementally builds on the contents of the previous
* frame.
*
- * It is highly recommended that applications use
+ * It is highly recommended that applications use
* cogl_onscreen_swap_buffers_with_damage() instead whenever possible
* and also use the cogl_onscreen_get_buffer_age() api so they can
* perform incremental updates to older buffers instead of having to
- * render a full buffer for every frame.
+ * render a full buffer for every frame.
*/
COGL_EXPORT void
cogl_onscreen_swap_buffers (CoglOnscreen *onscreen,
@@ -189,10 +189,10 @@ cogl_onscreen_swap_buffers (CoglOnscreen *onscreen,
*
* The queried value remains valid until the next buffer swap.
*
- * One caveat is that under X11 the buffer age does not reflect
+ * One caveat is that under X11 the buffer age does not reflect
* changes to buffer contents caused by the window systems. X11
* applications must track Expose events to determine what buffer
- * regions need to additionally be repaired each frame.
+ * regions need to additionally be repaired each frame.
*
* The recommended way to take advantage of this buffer age api is to
* build up a circular buffer of length 3 for tracking damage regions
@@ -202,14 +202,14 @@ cogl_onscreen_swap_buffers (CoglOnscreen *onscreen,
* everything that must be redrawn to update the old contents for the
* new frame.
*
- * If the system doesn't not support being able to track the age
+ * If the system doesn't not support being able to track the age
* of back buffers then this function will always return 0 which
- * implies that the contents are undefined.
+ * implies that the contents are undefined.
*
- * The %COGL_FEATURE_ID_BUFFER_AGE feature can optionally be
+ * The %COGL_FEATURE_ID_BUFFER_AGE feature can optionally be
* explicitly checked to determine if Cogl is currently tracking the
* age of #CoglOnscreen back buffer contents. If this feature is
- * missing then this function will always return 0.
+ * missing then this function will always return 0.
*
* Return value: The age of the buffer contents or 0 when the buffer
* contents are undefined.
@@ -278,9 +278,9 @@ cogl_onscreen_queue_damage_region (CoglOnscreen *onscreen,
* function instead of cogl_onscreen_swap_buffers() to improve
* performance when running under a compositor.
*
- * It is highly recommended to use this API in conjunction with
+ * It is highly recommended to use this API in conjunction with
* the cogl_onscreen_get_buffer_age() api so that your application can
- * perform incremental rendering based on old back buffers.
+ * perform incremental rendering based on old back buffers.
*/
COGL_EXPORT void
cogl_onscreen_swap_buffers_with_damage (CoglOnscreen *onscreen,
@@ -354,9 +354,9 @@ cogl_onscreen_swap_region (CoglOnscreen *onscreen,
* opportunity to collect statistics about a frame since the
* #CoglFrameInfo should hold the most data at this point.
*
- * A frame may not be completed before the next frame can start
+ * A frame may not be completed before the next frame can start
* so applications should avoid needing to collect all statistics for
- * a particular frame before they can start a new frame.
+ * a particular frame before they can start a new frame.
*/
typedef enum _CoglFrameEvent
{
diff --git a/cogl/cogl/cogl-pipeline-layer-state.h b/cogl/cogl/cogl-pipeline-layer-state.h
index 9ba238423..71d7a6928 100644
--- a/cogl/cogl/cogl-pipeline-layer-state.h
+++ b/cogl/cogl/cogl-pipeline-layer-state.h
@@ -140,8 +140,8 @@ typedef enum
* explicitly specify the type of default texture required, use
* cogl_pipeline_set_layer_null_texture() instead.
*
- * In the future, we may define other types of pipeline layers, such
- * as purely GLSL based layers.
+ * In the future, we may define other types of pipeline layers, such
+ * as purely GLSL based layers.
*/
COGL_EXPORT void
cogl_pipeline_set_layer_texture (CoglPipeline *pipeline,
@@ -193,88 +193,64 @@ cogl_pipeline_remove_layer (CoglPipeline *pipeline,
* cogl_pipeline_set_layer_combine:
* @pipeline: A #CoglPipeline object
* @layer_index: Specifies the layer you want define a combine function for
- * @blend_string: A Cogl blend string
- * describing the desired texture combine function.
+ * @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. May be %NULL, in which case a warning will be printed out if an
* error is encountered.
*
- * If not already familiar; you can refer
- * here for an overview of what blend
- * strings are and there syntax.
*
* These are all the functions available for texture combining:
- *
- * REPLACE(arg0) = arg0
- * MODULATE(arg0, arg1) = arg0 x arg1
- * ADD(arg0, arg1) = arg0 + arg1
- * ADD_SIGNED(arg0, arg1) = arg0 + arg1 - 0.5
- * INTERPOLATE(arg0, arg1, arg2) = arg0 x arg2 + arg1 x (1 - arg2)
- * SUBTRACT(arg0, arg1) = arg0 - arg1
- *
- *
+ *
+ * - `REPLACE(arg0) = arg0`
+ * - `MODULATE(arg0, arg1) = arg0 x arg1`
+ * - `ADD(arg0, arg1) = arg0 + arg1`
+ * - `ADD_SIGNED(arg0, arg1) = arg0 + arg1 - 0.5`
+ * - `INTERPOLATE(arg0, arg1, arg2) = arg0 x arg2 + arg1 x (1 - arg2)`
+ * - `SUBTRACT(arg0, arg1) = arg0 - arg1`
+ * -
+ * ```
* DOT3_RGB(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) +
* (arg0[G] - 0.5)) * (arg1[G] - 0.5) +
* (arg0[B] - 0.5)) * (arg1[B] - 0.5))
- *
- *
- *
- *
+ * ```
+ * -
+ * ```
* DOT3_RGBA(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) +
* (arg0[G] - 0.5)) * (arg1[G] - 0.5) +
* (arg0[B] - 0.5)) * (arg1[B] - 0.5))
- *
- *
- *
+ * ```
*
- * Refer to the
- * color-source syntax for
- * describing the arguments. The valid source names for texture combining
- * are:
- *
- *
- * TEXTURE
- * Use the color from the current texture layer
- *
- *
- * TEXTURE_0, TEXTURE_1, etc
- * Use the color from the specified texture layer
- *
- *
- * CONSTANT
- * Use the color from the constant given with
- * cogl_pipeline_set_layer_combine_constant()
- *
- *
- * PRIMARY
- * Use the color of the pipeline as set with
- * cogl_pipeline_set_color()
- *
- *
- * PREVIOUS
- * Either use the texture color from the previous layer, or
+ * The valid source names for texture combining are:
+ *
+ * - `TEXTURE`: Use the color from the current texture layer
+ * - `TEXTURE_0, TEXTURE_1, etc`: Use the color from the specified texture layer
+ * - `CONSTANT`: Use the color from the constant given with
+ * [method@Cogl.Pipeline.set_layer_combine_constant]
+ * - `PRIMARY`: Use the color of the pipeline as set with
+ * [method@Cogl.Pipeline.set_color]
+ * - `PREVIOUS`: Either use the texture color from the previous layer, or
* if this is layer 0, use the color of the pipeline as set with
- * cogl_pipeline_set_color()
- *
- *
+ * [method@Cogl.Pipeline.set_color]
+ *
+ * Layer Combine Examples:
+ *
+ * This is effectively what the default blending is:
+ *
+ * ```
+ * 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 [method@Cogl.Pipeline.set_layer_combine_constant].
+ *
+ * ```
+ * RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])
+ * ```
*
- *
- * Layer Combine Examples
- * This is effectively what the default blending is:
- *
- * 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_pipeline_set_layer_combine_constant().
- *
- * RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])
- *
- *
- *
- * You can't give a multiplication factor for arguments as you can
- * with blending.
+ * You can't give a multiplication factor for arguments as you can
+ * with blending.
*
* Return value: %TRUE if the blend string was successfully parsed, and the
* described texture combining is supported by the underlying driver and
@@ -352,10 +328,10 @@ cogl_pipeline_get_layer_filters (CoglPipeline *pipeline,
* Changes the decimation and interpolation filters used when a texture is
* drawn at other scales than 100%.
*
- * It is an error to pass anything other than
+ * It is an error to pass anything other than
* %COGL_PIPELINE_FILTER_NEAREST or %COGL_PIPELINE_FILTER_LINEAR as
* magnification filters since magnification doesn't ever need to
- * reference values stored in the mipmap chain.
+ * reference values stored in the mipmap chain.
*/
COGL_EXPORT void
cogl_pipeline_set_layer_filters (CoglPipeline *pipeline,
diff --git a/cogl/cogl/cogl-pipeline-private.h b/cogl/cogl/cogl-pipeline-private.h
index 1bc994287..ad256909d 100644
--- a/cogl/cogl/cogl-pipeline-private.h
+++ b/cogl/cogl/cogl-pipeline-private.h
@@ -570,7 +570,7 @@ _cogl_get_n_args_for_combine_func (CoglPipelineCombineFunc func);
* To understand this better its good to know a bit about the internal
* design of #CoglPipeline...
*
- * Internally #CoglPipelines are represented as a graph of
+ * Internally `CoglPipeline`s are represented as a graph of
* property diff's, where each node is a diff of properties that gets
* applied on top of its parent. Copying a pipeline creates an empty
* diff and a child->parent relationship between the empty diff and
@@ -617,7 +617,7 @@ _cogl_get_n_args_for_combine_func (CoglPipelineCombineFunc func);
*
* This is the recommended coding pattern for validating an input
* pipeline and caching a derived result:
- * |[
+ * ```c
* static GQuark _cogl_my_cache_key = 0;
*
* typedef struct {
@@ -673,7 +673,7 @@ _cogl_get_n_args_for_combine_func (CoglPipelineCombineFunc func);
*
* return cache->validated_source;
* }
- * ]|
+ * ```
*/
CoglPipeline *
_cogl_pipeline_weak_copy (CoglPipeline *pipeline,
diff --git a/cogl/cogl/cogl-pipeline-state.h b/cogl/cogl/cogl-pipeline-state.h
index 52f7fa824..9b7334d80 100644
--- a/cogl/cogl/cogl-pipeline-state.h
+++ b/cogl/cogl/cogl-pipeline-state.h
@@ -184,7 +184,7 @@ cogl_pipeline_get_alpha_test_reference (CoglPipeline *pipeline);
/**
* cogl_pipeline_set_blend:
* @pipeline: A #CoglPipeline object
- * @blend_string: A Cogl blend string
+ * @blend_string: A Cogl blend string
* describing the desired blend function.
* @error: return location for a #GError that may report lack of driver
* support if you give separate blend string statements for the alpha
@@ -193,64 +193,50 @@ cogl_pipeline_get_alpha_test_reference (CoglPipeline *pipeline);
* warning will be printed out using GLib's logging facilities if an
* error is encountered.
*
- * If not already familiar; please refer here
- * for an overview of what blend strings are, and their syntax.
- *
* Blending occurs after the alpha test function, and combines fragments with
* the framebuffer.
* Currently the only blend function Cogl exposes is ADD(). So any valid
* blend statements will be of the form:
*
- * |[
+ * ```
* <channel-mask>=ADD(SRC_COLOR*(<factor>), DST_COLOR*(<factor>))
- * ]|
+ * ```
*
* This is the list of source-names usable as blend factors:
- *
- * SRC_COLOR: The color of the incoming fragment
- * DST_COLOR: The color of the framebuffer
- * CONSTANT: The constant set via cogl_pipeline_set_blend_constant()
- *
- *
- * The source names can be used according to the
- * color-source and factor syntax,
- * so for example "(1-SRC_COLOR[A])" would be a valid factor, as would
- * "(CONSTANT[RGB])"
+ *
+ * - `SRC_COLOR`: The color of the incoming fragment
+ * - `DST_COLOR`: The color of the framebuffer
+ * - `CONSTANT`: The constant set via cogl_pipeline_set_blend_constant()
*
* These can also be used as factors:
- *
- * 0: (0, 0, 0, 0)
- * 1: (1, 1, 1, 1)
- * SRC_ALPHA_SATURATE_FACTOR: (f,f,f,1) where f = MIN(SRC_COLOR[A],1-DST_COLOR[A])
- *
+ *
+ * - `0`: (0, 0, 0, 0)
+ * - `1`: (1, 1, 1, 1)
+ * - `SRC_ALPHA_SATURATE_FACTOR`: (f,f,f,1) where `f = MIN(SRC_COLOR[A],1-DST_COLOR[A])`
*
- * Remember; all color components are normalized to the range [0, 1]
- * before computing the result of blending.
+ * Remember; all color components are normalized to the range [0, 1]
+ * before computing the result of blending.
*
- *
- * Blend Strings/1
- * Blend a non-premultiplied source over a destination with
- * premultiplied alpha:
- *
+ * - Blend Strings/1:
+ * Blend a non-premultiplied source over a destination with
+ * premultiplied alpha:
+ * ```
* "RGB = ADD(SRC_COLOR*(SRC_COLOR[A]), DST_COLOR*(1-SRC_COLOR[A]))"
* "A = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
- *
- *
+ * ```
*
- *
- * Blend Strings/2
- * Blend a premultiplied source over a destination with
- * premultiplied alpha
- *
+ * Blend Strings/2:
+ * Blend a premultiplied source over a destination with
+ * premultiplied alpha
+ * ```
* "RGBA = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
- *
- *
+ * ```
*
* The default blend string is:
- * |[
+ * ```
* RGBA = ADD (SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))
- * ]|
+ * ```
*
* That gives normal alpha-blending when the calculated color for the pipeline
* is in premultiplied form.
@@ -366,7 +352,7 @@ cogl_pipeline_get_user_program (CoglPipeline *pipeline);
*
* This is an example of how it can be used to associate an ARBfp
* program with a #CoglPipeline:
- * |[
+ * ```c
* CoglShader *shader;
* CoglProgram *program;
* CoglPipeline *pipeline;
@@ -386,7 +372,7 @@ cogl_pipeline_get_user_program (CoglPipeline *pipeline);
*
* cogl_set_source_color4ub (0xff, 0x00, 0x00, 0xff);
* cogl_rectangle (0, 0, 100, 100);
- * ]|
+ * ```
*
* It is possibly worth keeping in mind that this API is not part of
* the long term design for how we want to expose shaders to Cogl
diff --git a/cogl/cogl/cogl-poll.h b/cogl/cogl/cogl-poll.h
index 19f701e97..652b2146c 100644
--- a/cogl/cogl/cogl-poll.h
+++ b/cogl/cogl/cogl-poll.h
@@ -97,9 +97,9 @@ typedef enum
*
* A struct for describing the state of a file descriptor that Cogl
* needs to block on. The @events field contains a bitmask of
- * #CoglPollFDEvents that should cause the application to wake
+ * `CoglPollFDEvent`s that should cause the application to wake
* up. After the application is woken up from idle it should pass back
- * an array of #CoglPollFDs to Cogl and update the @revents
+ * an array of `CoglPollFD`s to Cogl and update the @revents
* mask to the actual events that occurred on the file descriptor.
*
* Note that CoglPollFD is deliberately exactly the same as struct
@@ -115,7 +115,7 @@ typedef struct {
* cogl_poll_renderer_get_info:
* @renderer: A #CoglRenderer
* @poll_fds: A return location for a pointer to an array
- * of #CoglPollFDs
+ * of `CoglPollFD`s
* @n_poll_fds: A return location for the number of entries in *@poll_fds
* @timeout: A return location for the maximum length of time to wait
* in microseconds, or -1 to wait indefinitely.
@@ -126,9 +126,9 @@ typedef struct {
* that Cogl has a chance to describe what file descriptor events it
* needs to be woken up for.
*
- * If your application is using the Glib mainloop then you
+ * If your application is using the Glib mainloop then you
* should jump to the cogl_glib_source_new() api as a more convenient
- * way of integrating Cogl with the mainloop.
+ * way of integrating Cogl with the mainloop.
*
* After the function is called *@poll_fds will contain a pointer to
* an array of #CoglPollFD structs describing the file descriptors
@@ -140,7 +140,7 @@ typedef struct {
*
* When the application mainloop returns from calling poll(2) (or its
* equivalent) then it should call cogl_poll_renderer_dispatch()
- * passing a pointer the array of CoglPollFDs with updated
+ * passing a pointer the array of `CoglPollFD`s with updated
* revent values.
*
* @timeout will contain a maximum amount of time to wait in
@@ -165,7 +165,7 @@ cogl_poll_renderer_get_info (CoglRenderer *renderer,
/**
* cogl_poll_renderer_dispatch:
* @renderer: A #CoglRenderer
- * @poll_fds: An array of #CoglPollFDs describing the events
+ * @poll_fds: An array of `CoglPollFD`s describing the events
* that have occurred since the application went idle.
* @n_poll_fds: The length of the @poll_fds array.
*
@@ -176,10 +176,6 @@ cogl_poll_renderer_get_info (CoglRenderer *renderer,
* file descriptors that Cogl didn't request when calling
* cogl_poll_renderer_get_info() or a shorter array missing some file
* descriptors that Cogl requested.
- *
- * If your application didn't originally create a #CoglRenderer
- * manually then you can easily get a #CoglRenderer pointer by calling
- * cogl_get_renderer().
*/
COGL_EXPORT void
cogl_poll_renderer_dispatch (CoglRenderer *renderer,
diff --git a/cogl/cogl/cogl-primitive.h b/cogl/cogl/cogl-primitive.h
index ff3e0090d..e98cc7d3c 100644
--- a/cogl/cogl/cogl-primitive.h
+++ b/cogl/cogl/cogl-primitive.h
@@ -203,12 +203,12 @@ typedef struct {
* @n_vertices: The number of vertices to process when drawing
* @...: A %NULL terminated list of attributes
*
- * Combines a set of #CoglAttributes with a specific draw @mode
+ * Combines a set of `CoglAttribute`s with a specific draw @mode
* and defines a vertex count so a #CoglPrimitive object can be retained and
* drawn later with no addition information required.
*
* The value passed as @n_vertices will simply update the
- * #CoglPrimitive n_vertices property as if
+ * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
*
@@ -226,12 +226,12 @@ cogl_primitive_new (CoglVerticesMode mode,
* @attributes: An array of CoglAttribute
* @n_attributes: The number of attributes
*
- * Combines a set of #CoglAttributes with a specific draw @mode
+ * Combines a set of `CoglAttribute`s with a specific draw @mode
* and defines a vertex count so a #CoglPrimitive object can be retained and
* drawn later with no addition information required.
*
* The value passed as @n_vertices will simply update the
- * #CoglPrimitive n_vertices property as if
+ * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
*
@@ -258,7 +258,7 @@ cogl_primitive_new_with_attributes (CoglVerticesMode mode,
* attribute with a #CoglAttribute and upload your data.
*
* For example to draw a convex polygon you can do:
- * |[
+ * ```c
* CoglVertexP2 triangle[] =
* {
* { 0, 300 },
@@ -268,21 +268,21 @@ cogl_primitive_new_with_attributes (CoglVerticesMode mode,
* prim = cogl_primitive_new_p2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
- * ]|
+ * ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
- * #CoglPrimitive n_vertices property as if
+ * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
- * The primitive API doesn't support drawing with sliced
+ * The primitive API doesn't support drawing with sliced
* textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
- *
+ *
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@@ -308,7 +308,7 @@ cogl_primitive_new_p2 (CoglContext *context,
* attribute with a #CoglAttribute and upload your data.
*
* For example to draw a convex polygon you can do:
- * |[
+ * ```c
* CoglVertexP3 triangle[] =
* {
* { 0, 300, 0 },
@@ -318,21 +318,21 @@ cogl_primitive_new_p2 (CoglContext *context,
* prim = cogl_primitive_new_p3 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
- * ]|
+ * ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
- * #CoglPrimitive n_vertices property as if
+ * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
- * The primitive API doesn't support drawing with sliced
+ * The primitive API doesn't support drawing with sliced
* textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
- *
+ *
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@@ -355,12 +355,12 @@ cogl_primitive_new_p3 (CoglContext *context,
* Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position
- * and color attributes with #CoglAttributes and upload
+ * and color attributes with `CoglAttribute`s and upload
* your data.
*
* For example to draw a convex polygon with a linear gradient you
* can do:
- * |[
+ * ```c
* CoglVertexP2C4 triangle[] =
* {
* { 0, 300, 0xff, 0x00, 0x00, 0xff },
@@ -370,21 +370,21 @@ cogl_primitive_new_p3 (CoglContext *context,
* prim = cogl_primitive_new_p2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
- * ]|
+ * ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
- * #CoglPrimitive n_vertices property as if
+ * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
- * The primitive API doesn't support drawing with sliced
+ * The primitive API doesn't support drawing with sliced
* textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
- *
+ *
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@@ -407,12 +407,12 @@ cogl_primitive_new_p2c4 (CoglContext *context,
* Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position
- * and color attributes with #CoglAttributes and upload
+ * and color attributes with `CoglAttribute`s and upload
* your data.
*
* For example to draw a convex polygon with a linear gradient you
* can do:
- * |[
+ * ```c
* CoglVertexP3C4 triangle[] =
* {
* { 0, 300, 0, 0xff, 0x00, 0x00, 0xff },
@@ -422,21 +422,21 @@ cogl_primitive_new_p2c4 (CoglContext *context,
* prim = cogl_primitive_new_p3c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
- * ]|
+ * ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
- * #CoglPrimitive n_vertices property as if
+ * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
- * The primitive API doesn't support drawing with sliced
+ * The primitive API doesn't support drawing with sliced
* textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
- *
+ *
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@@ -459,12 +459,12 @@ cogl_primitive_new_p3c4 (CoglContext *context,
* Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position and
- * texture coordinate attributes with #CoglAttributes and
+ * texture coordinate attributes with `CoglAttribute`s and
* upload your data.
*
* For example to draw a convex polygon with texture mapping you can
* do:
- * |[
+ * ```c
* CoglVertexP2T2 triangle[] =
* {
* { 0, 300, 0.0, 1.0},
@@ -474,21 +474,21 @@ cogl_primitive_new_p3c4 (CoglContext *context,
* prim = cogl_primitive_new_p2t2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
- * ]|
+ * ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
- * #CoglPrimitive n_vertices property as if
+ * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
- * The primitive API doesn't support drawing with sliced
+ * The primitive API doesn't support drawing with sliced
* textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
- *
+ *
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@@ -511,12 +511,12 @@ cogl_primitive_new_p2t2 (CoglContext *context,
* Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position and
- * texture coordinate attributes with #CoglAttributes and
+ * texture coordinate attributes with `CoglAttribute`s and
* upload your data.
*
* For example to draw a convex polygon with texture mapping you can
* do:
- * |[
+ * ```c
* CoglVertexP3T2 triangle[] =
* {
* { 0, 300, 0, 0.0, 1.0},
@@ -526,21 +526,21 @@ cogl_primitive_new_p2t2 (CoglContext *context,
* prim = cogl_primitive_new_p3t2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
- * ]|
+ * ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
- * #CoglPrimitive n_vertices property as if
+ * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
- * The primitive API doesn't support drawing with sliced
+ * The primitive API doesn't support drawing with sliced
* textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
- *
+ *
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@@ -563,12 +563,12 @@ cogl_primitive_new_p3t2 (CoglContext *context,
* Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position, texture
- * coordinate and color attributes with #CoglAttributes and
+ * coordinate and color attributes with `CoglAttribute`s and
* upload your data.
*
* For example to draw a convex polygon with texture mapping and a
* linear gradient you can do:
- * |[
+ * ```c
* CoglVertexP2T2C4 triangle[] =
* {
* { 0, 300, 0.0, 1.0, 0xff, 0x00, 0x00, 0xff},
@@ -578,21 +578,21 @@ cogl_primitive_new_p3t2 (CoglContext *context,
* prim = cogl_primitive_new_p2t2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
- * ]|
+ * ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
- * #CoglPrimitive n_vertices property as if
+ * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
- * The primitive API doesn't support drawing with sliced
+ * The primitive API doesn't support drawing with sliced
* textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
- *
+ *
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@@ -615,12 +615,12 @@ cogl_primitive_new_p2t2c4 (CoglContext *context,
* Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position, texture
- * coordinate and color attributes with #CoglAttributes and
+ * coordinate and color attributes with `CoglAttribute`s and
* upload your data.
*
* For example to draw a convex polygon with texture mapping and a
* linear gradient you can do:
- * |[
+ * ```c
* CoglVertexP3T2C4 triangle[] =
* {
* { 0, 300, 0, 0.0, 1.0, 0xff, 0x00, 0x00, 0xff},
@@ -630,21 +630,21 @@ cogl_primitive_new_p2t2c4 (CoglContext *context,
* prim = cogl_primitive_new_p3t2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
- * ]|
+ * ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
- * #CoglPrimitive n_vertices property as if
+ * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
- * The primitive API doesn't support drawing with sliced
+ * The primitive API doesn't support drawing with sliced
* textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
- *
+ *
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@@ -674,9 +674,9 @@ cogl_primitive_set_first_vertex (CoglPrimitive *primitive,
* number of vertices to read can also be phrased as the number
* of indices to read.
*
- * To be clear; it doesn't refer to the number of vertices - in
+ * To be clear; it doesn't refer to the number of vertices - in
* terms of data - associated with the primitive it's just the number
- * of vertices to read and draw.
+ * of vertices to read and draw.
*
* Returns: The number of vertices to read when drawing.
*/
@@ -694,9 +694,9 @@ cogl_primitive_get_n_vertices (CoglPrimitive *primitive);
* Usually this value is set implicitly when associating vertex data
* or indices with a #CoglPrimitive.
*
- * To be clear; it doesn't refer to the number of vertices - in
+ * To be clear; it doesn't refer to the number of vertices - in
* terms of data - associated with the primitive it's just the number
- * of vertices to read and draw.
+ * of vertices to read and draw.
*/
COGL_EXPORT void
cogl_primitive_set_n_vertices (CoglPrimitive *primitive,
@@ -725,14 +725,14 @@ cogl_primitive_set_mode (CoglPrimitive *primitive,
* shared data multiple times instead of duplicating the data.
*
* The value passed as @n_indices will simply update the
- * #CoglPrimitive n_vertices property as if
+ * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to draw or, put another way, how many
* indices should be read from @indices when drawing.
*
- * The #CoglPrimitive first_vertex property
+ * The #CoglPrimitive `first_vertex` property
* also affects drawing with indices by defining the first entry of the
- * indices to start drawing from.
+ * indices to start drawing from.
*/
COGL_EXPORT void
cogl_primitive_set_indices (CoglPrimitive *primitive,
diff --git a/cogl/cogl/cogl-renderer.h b/cogl/cogl/cogl-renderer.h
index e75e00f54..a14b70bc4 100644
--- a/cogl/cogl/cogl-renderer.h
+++ b/cogl/cogl/cogl-renderer.h
@@ -65,12 +65,6 @@ G_BEGIN_DECLS
*
* Once you have a configured #CoglRenderer it can be used to create a
* #CoglDisplay object using cogl_display_new().
- *
- * Many applications don't need to explicitly use
- * cogl_renderer_new() or cogl_display_new() and can just jump
- * straight to cogl_context_new() and pass a %NULL display argument so
- * Cogl will automatically connect and setup a renderer and
- * display.
*/
@@ -125,12 +119,6 @@ G_DECLARE_FINAL_TYPE (CoglRenderer,
* Once you have setup your renderer then the next step is to create a
* #CoglDisplay using cogl_display_new().
*
- * Many applications don't need to explicitly use
- * cogl_renderer_new() or cogl_display_new() and can just jump
- * straight to cogl_context_new() and pass a %NULL display argument
- * so Cogl will automatically connect and setup a renderer and
- * display.
- *
* Return value: (transfer full): A newly created #CoglRenderer.
*/
COGL_EXPORT CoglRenderer *
diff --git a/cogl/cogl/cogl-snippet.h b/cogl/cogl/cogl-snippet.h
index cfeb4d1e9..03b0f92e9 100644
--- a/cogl/cogl/cogl-snippet.h
+++ b/cogl/cogl/cogl-snippet.h
@@ -44,7 +44,7 @@ G_BEGIN_DECLS
*
* Functions for creating and manipulating shader snippets
*
- * #CoglSnippets are used to modify or replace parts of a
+ * `CoglSnippet`s are used to modify or replace parts of a
* #CoglPipeline using GLSL. GLSL is a programming language supported
* by OpenGL on programmable hardware to provide a more flexible
* description of what should be rendered. A description of GLSL
@@ -61,38 +61,20 @@ G_BEGIN_DECLS
* the pipeline at a particular point. The code is split into four
* separate strings (all of which are optional):
*
- *
- *
- * declarations
- *
+ * - `declarations`
* The code in this string will be inserted outside of any function in
* the global scope of the shader. This can be used to declare
* uniforms, attributes, varyings and functions to be used by the
* snippet.
- *
- *
- *
- * pre
- *
+ * - `pre`
* The code in this string will be inserted before the hook point.
- *
- *
- *
- * post
- *
+ * - `post`
* The code in this string will be inserted after the hook point. This
* can be used to modify the results of the builtin generated code for
* that hook point.
- *
- *
- *
- * replace
- *
+ * - `replace
* If present the code in this string will replace the generated code
* for the hook point.
- *
- *
- *
*
* All of the strings apart from the declarations string of a pipeline
* are generated in a single function so they can share variables
@@ -120,174 +102,76 @@ G_BEGIN_DECLS
* names under the cogl_* namespace which can be used instead. These
* are:
*
- *
- *
- * uniform mat4
- * cogl_modelview_matrix
- *
+ * - `uniform mat4 cogl_modelview_matrix
* The current modelview matrix. This is equivalent to
* #gl_ModelViewMatrix.
- *
- *
- *
- * uniform mat4
- * cogl_projection_matrix
- *
+ * - `uniform mat4 cogl_projection_matrix
* The current projection matrix. This is equivalent to
* #gl_ProjectionMatrix.
- *
- *
- *
- * uniform mat4
- * cogl_modelview_projection_matrix
- *
+ * - `uniform mat4 cogl_modelview_projection_matrix
* The combined modelview and projection matrix. A vertex shader
* would typically use this to transform the incoming vertex
* position. The separate modelview and projection matrices are
* usually only needed for lighting calculations. This is
* equivalent to #gl_ModelViewProjectionMatrix.
- *
- *
- *
- * uniform mat4
- * cogl_texture_matrix[]
- *
+ * - `uniform mat4 cogl_texture_matrix[]
* An array of matrices for transforming the texture
* coordinates. This is equivalent to #gl_TextureMatrix.
- *
- *
- *
*
* In a vertex shader, the following are also available:
*
- *
- *
- * attribute vec4
- * cogl_position_in
- *
+ * - `attribute vec4 cogl_position_in
* The incoming vertex position. This is equivalent to #gl_Vertex.
- *
- *
- *
- * attribute vec4
- * cogl_color_in
- *
+ * - `attribute vec4 cogl_color_in`
* The incoming vertex color. This is equivalent to #gl_Color.
- *
- *
- *
- * attribute vec4
- * cogl_tex_coord_in
- *
+ * - `attribute vec4 cogl_tex_coord_in`
* The texture coordinate for layer 0. This is an alternative name
* for #cogl_tex_coord0_in.
- *
- *
- *
- * attribute vec4
- * cogl_tex_coord0_in
- *
+ * - `attribute vec4 cogl_tex_coord0_in
* The texture coordinate for the layer 0. This is equivalent to
* #gl_MultiTexCoord0. There will also be #cogl_tex_coord1_in and
* so on if more layers are added to the pipeline.
- *
- *
- *
- * attribute vec3
- * cogl_normal_in
- *
+ * - `attribute vec3 cogl_normal_in`
* The normal of the vertex. This is equivalent to #gl_Normal.
- *
- *
- *
- * vec4
- * cogl_position_out
- *
+ * - `vec4 cogl_position_out
* The calculated position of the vertex. This must be written to
* in all vertex shaders. This is equivalent to #gl_Position.
- *
- *
- *
- * float
- * cogl_point_size_in
- *
+ * - `float cogl_point_size_in
* The incoming point size from the cogl_point_size_in attribute.
* This is only available if
* cogl_pipeline_set_per_vertex_point_size() is set on the
* pipeline.
- *
- *
- *
- * float
- * cogl_point_size_out
- *
+ * - `float cogl_point_size_out`
* The calculated size of a point. This is equivalent to #gl_PointSize.
- *
- *
- *
- * varying vec4
- * cogl_color_out
- *
+ * - `varying vec4 cogl_color_out`
* The calculated color of a vertex. This is equivalent to #gl_FrontColor.
- *
- *
- *
- * varying vec4
- * cogl_tex_coord0_out
- *
+ * - `varying vec4 cogl_tex_coord0_out`
* The calculated texture coordinate for layer 0 of the pipeline.
* This is equivalent to #gl_TexCoord[0]. There will also be
* #cogl_tex_coord1_out and so on if more layers are added to the
* pipeline. In the fragment shader, this varying is called
* #cogl_tex_coord0_in.
- *
- *
- *
*
* In a fragment shader, the following are also available:
*
- *
- *
- * varying vec4 cogl_color_in
- *
+ * - `varying vec4 cogl_color_in`
* The calculated color of a vertex. This is equivalent to #gl_FrontColor.
- *
- *
- *
- * varying vec4
- * cogl_tex_coord0_in
- *
+ * - `varying vec4 cogl_tex_coord0_in`
* The texture coordinate for layer 0. This is equivalent to
* #gl_TexCoord[0]. There will also be #cogl_tex_coord1_in and so
* on if more layers are added to the pipeline.
- *
- *
- *
- * vec4 cogl_color_out
- *
+ * - `vec4 cogl_color_out`
* The final calculated color of the fragment. All fragment shaders
* must write to this variable. This is equivalent to
* #gl_FrontColor.
- *
- *
- *
- * float cogl_depth_out
- *
+ * - `float cogl_depth_out`
* An optional output variable specifying the depth value to use
* for this fragment. This is equivalent to #gl_FragDepth.
- *
- *
- *
- * bool cogl_front_facing
- *
+ * - `bool cogl_front_facing`
* A readonly variable that will be true if the current primitive
* is front facing. This can be used to implement two-sided
* coloring algorithms. This is equivalent to #gl_FrontFacing.
- *
- *
- *
- * vec2 cogl_point_coord
- *
+ * - `vec2 cogl_point_coord`
* When rendering points, this will contain a vec2 which represents
* the position within the point of the current fragment.
* vec2(0.0,0.0) will be the topleft of the point and vec2(1.0,1.0)
@@ -295,9 +179,6 @@ G_BEGIN_DECLS
* Cogl where when rendering to an offscreen buffer these
* coordinates will be upside-down. The value is undefined when not
* rendering points.
- *
- *
- *
*
* Here is an example of using a snippet to add a desaturate effect to the
* generated color on a pipeline.
@@ -377,97 +258,70 @@ G_DECLARE_FINAL_TYPE (CoglSnippet,
* #CoglPipeline where the code of the snippet should be used when it
* is attached to a pipeline.
*
- *
- *
- * %COGL_SNIPPET_HOOK_VERTEX_GLOBALS
- *
- *
+ * - `COGL_SNIPPET_HOOK_VERTEX_GLOBALS`
+ *
* Adds a shader snippet at the beginning of the global section of the
* shader for the vertex processing. Any declarations here can be
* shared with all other snippets that are attached to a vertex hook.
* Only the ‘declarations’ string is used and the other strings are
* ignored.
- *
- *
- *
- *
- * %COGL_SNIPPET_HOOK_FRAGMENT_GLOBALS
- *
- *
+ *
+ * - `COGL_SNIPPET_HOOK_FRAGMENT_GLOBALS`
+ *
* Adds a shader snippet at the beginning of the global section of the
* shader for the fragment processing. Any declarations here can be
* shared with all other snippets that are attached to a fragment
* hook. Only the ‘declarations’ string is used and the other strings
* are ignored.
- *
- *
- *
- *
- * %COGL_SNIPPET_HOOK_VERTEX
- *
- *
+ *
+ * - `COGL_SNIPPET_HOOK_VERTEX`
+ *
* Adds a shader snippet that will hook on to the vertex processing
* stage of the pipeline. This gives a chance for the application to
* modify the vertex attributes generated by the shader. Typically the
* snippet will modify cogl_color_out or cogl_position_out builtins.
- *
- *
+ *
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
- *
- *
+ *
* The ‘pre’ string in @snippet will be inserted at the top of the
* main() function before any vertex processing is done.
- *
- *
+ *
* The ‘replace’ string in @snippet will be used instead of the
* generated vertex processing if it is present. This can be used if
* the application wants to provide a complete vertex shader and
* doesn't need the generated output from Cogl.
- *
- *
+ *
* The ‘post’ string in @snippet will be inserted after all of the
* standard vertex processing is done. This can be used to modify the
* outputs.
- *
- *
- *
- *
- * %COGL_SNIPPET_HOOK_VERTEX_TRANSFORM
- *
- *
+ *
+ * - `COGL_SNIPPET_HOOK_VERTEX_TRANSFORM`
+ *
* Adds a shader snippet that will hook on to the vertex transform stage.
* Typically the snippet will use the cogl_modelview_matrix,
* cogl_projection_matrix and cogl_modelview_projection_matrix matrices and the
* cogl_position_in attribute. The hook must write to cogl_position_out.
* The default processing for this hook will multiply cogl_position_in by
* the combined modelview-projection matrix and store it on cogl_position_out.
- *
- *
+ *
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
- *
- *
+ *
* The ‘pre’ string in @snippet will be inserted at the top of the
* main() function before the vertex transform is done.
- *
- *
+ *
* The ‘replace’ string in @snippet will be used instead of the
* generated vertex transform if it is present.
- *
- *
+ *
* The ‘post’ string in @snippet will be inserted after all of the
* standard vertex transformation is done. This can be used to modify the
* cogl_position_out in addition to the default processing.
- *
- *
- *
- *
- * %COGL_SNIPPET_HOOK_POINT_SIZE
- *
- *
+ *
+ * - `COGL_SNIPPET_HOOK_POINT_SIZE`
+ *
* Adds a shader snippet that will hook on to the point size
* calculation step within the vertex shader stage. The snippet should
* write to the builtin cogl_point_size_out with the new point size.
@@ -476,69 +330,52 @@ G_DECLARE_FINAL_TYPE (CoglSnippet,
* that would be set by a previous snippet. Note that this hook is
* only used if cogl_pipeline_set_per_vertex_point_size() is enabled
* on the pipeline.
- *
- *
+ *
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
- *
- *
+ *
* The ‘pre’ string in @snippet will be inserted just before
* calculating the point size.
- *
- *
+ *
* The ‘replace’ string in @snippet will be used instead of the
* generated point size calculation if it is present.
- *
- *
+ *
* The ‘post’ string in @snippet will be inserted after the
* standard point size calculation is done. This can be used to modify
* cogl_point_size_out in addition to the default processing.
- *
- *
- *
- *
- * %COGL_SNIPPET_HOOK_FRAGMENT
- *
- *
+ *
+ * - `COGL_SNIPPET_HOOK_FRAGMENT`
+ *
* Adds a shader snippet that will hook on to the fragment processing
* stage of the pipeline. This gives a chance for the application to
* modify the fragment color generated by the shader. Typically the
* snippet will modify cogl_color_out.
- *
- *
+ *
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
- *
- *
+ *
* The ‘pre’ string in @snippet will be inserted at the top of the
* main() function before any fragment processing is done.
- *
- *
+ *
* The ‘replace’ string in @snippet will be used instead of the
* generated fragment processing if it is present. This can be used if
* the application wants to provide a complete fragment shader and
* doesn't need the generated output from Cogl.
- *
- *
+ *
* The ‘post’ string in @snippet will be inserted after all of the
* standard fragment processing is done. At this point the generated
* value for the rest of the pipeline state will already be in
* cogl_color_out so the application can modify the result by altering
* this variable.
- *
- *
- *
- *
- * %COGL_SNIPPET_HOOK_TEXTURE_COORD_TRANSFORM
- *
- *
+ *
+ * - `COGL_SNIPPET_HOOK_TEXTURE_COORD_TRANSFORM`
+ *
* Adds a shader snippet that will hook on to the texture coordinate
* transformation of a particular layer. This can be used to replace
* the processing for a layer or to modify the results.
- *
- *
+ *
* Within the snippet code for this hook there are two extra
* variables. The first is a mat4 called cogl_matrix which represents
* the user matrix for this layer. The second is called cogl_tex_coord
@@ -549,76 +386,57 @@ G_DECLARE_FINAL_TYPE (CoglSnippet,
* varying to the fragment processing stage. The default code will
* just multiply cogl_matrix by cogl_tex_coord and store the result in
* cogl_tex_coord.
- *
- *
+ *
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
- *
- *
+ *
* The ‘pre’ string in @snippet will be inserted just before the
* fragment processing for this layer. At this point cogl_tex_coord
* still contains the value of the texture coordinate attribute.
- *
- *
* If a ‘replace’ string is given then this will be used instead of
* the default fragment processing for this layer. The snippet can
* modify cogl_tex_coord or leave it as is to apply no transformation.
- *
- *
+ *
* The ‘post’ string in @snippet will be inserted just after the
* transformation. At this point cogl_tex_coord will contain the
* results of the transformation but it can be further modified by the
* snippet.
- *
- *
- *
- *
- * %COGL_SNIPPET_HOOK_LAYER_FRAGMENT
- *
- *
+ *
+ * - `COGL_SNIPPET_HOOK_LAYER_FRAGMENT`
+ *
* Adds a shader snippet that will hook on to the fragment processing
* of a particular layer. This can be used to replace the processing
* for a layer or to modify the results.
- *
- *
+ *
* Within the snippet code for this hook there is an extra vec4
* variable called ‘cogl_layer’. This contains the resulting color
* that will be used for the layer. This can be modified in the ‘post’
* section or it the default processing can be replaced entirely using
* the ‘replace’ section.
- *
- *
+ *
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
- *
- *
+ *
* The ‘pre’ string in @snippet will be inserted just before the
* fragment processing for this layer.
- *
- *
+ *
* If a ‘replace’ string is given then this will be used instead of
* the default fragment processing for this layer. The snippet must write to
* the ‘cogl_layer’ variable in that case.
- *
- *
+ *
* The ‘post’ string in @snippet will be inserted just after the
* fragment processing for the layer. The results can be modified by changing
* the value of the ‘cogl_layer’ variable.
- *
- *
- *
- *
- * %COGL_SNIPPET_HOOK_TEXTURE_LOOKUP
- *
- *
+ *
+ * - `COGL_SNIPPET_HOOK_TEXTURE_LOOKUP`
+ *
* Adds a shader snippet that will hook on to the texture lookup part
* of a given layer. This gives a chance for the application to modify
* the coordinates that will be used for the texture lookup or to
* alter the returned texel.
- *
- *
+ *
* Within the snippet code for this hook there are three extra
* variables available. ‘cogl_sampler’ is a sampler object
* representing the sampler for the layer where the snippet is
@@ -626,30 +444,22 @@ G_DECLARE_FINAL_TYPE (CoglSnippet,
* coordinates that will be used for the texture lookup. This can be
* modified. ‘cogl_texel’ will contain the result of the texture
* lookup. This can also be modified.
- *
- *
+ *
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
- *
- *
+ *
* The ‘pre’ string in @snippet will be inserted at the top of the
* main() function before any fragment processing is done. This is a
* good place to modify the cogl_tex_coord variable.
- *
- *
+ *
* If a ‘replace’ string is given then this will be used instead of a
* the default texture lookup. The snippet would typically use its own
* sampler in this case.
- *
- *
+ *
* The ‘post’ string in @snippet will be inserted after texture lookup
* has been performed. Here the snippet can modify the cogl_texel
* variable to alter the returned texel.
- *
- *
- *
- *
*/
typedef enum
{
diff --git a/cogl/cogl/cogl-sub-texture.h b/cogl/cogl/cogl-sub-texture.h
index f3451608a..b207ef35a 100644
--- a/cogl/cogl/cogl-sub-texture.h
+++ b/cogl/cogl/cogl-sub-texture.h
@@ -80,11 +80,11 @@ GType cogl_sub_texture_get_type (void) G_GNUC_CONST;
* #CoglMetaTexture interface because it's not a low level texture
* that hardware can understand natively.
*
- * Remember: Unless you are using high level drawing APIs such
+ * Remember: Unless you are using high level drawing APIs such
* as cogl_rectangle() or other APIs documented to understand the
* #CoglMetaTexture interface then you need to use the
* #CoglMetaTexture interface to resolve a #CoglSubTexture into a
- * low-level texture before drawing.
+ * low-level texture before drawing.
*
* Return value: (transfer full): A newly allocated #CoglSubTexture
* representing a sub-region of @parent_texture.
diff --git a/cogl/cogl/cogl-texture-2d-sliced.h b/cogl/cogl/cogl-texture-2d-sliced.h
index bb13f0113..79abfae2e 100644
--- a/cogl/cogl/cogl-texture-2d-sliced.h
+++ b/cogl/cogl/cogl-texture-2d-sliced.h
@@ -111,11 +111,11 @@ GType cogl_texture_2d_sliced_get_type (void) G_GNUC_CONST;
* allocate the underlying storage or let Cogl automatically allocate
* storage lazily.
*
- * It's possible for the allocation of a sliced texture to fail
+ * It's possible for the allocation of a sliced texture to fail
* later due to impossible slicing constraints if a negative
* @max_waste value is given. If the given virtual texture size size
* is larger than is supported by the hardware but slicing is disabled
- * the texture size would be too large to handle.
+ * the texture size would be too large to handle.
*
* Returns: (transfer full): A new #CoglTexture2DSliced object with no storage
* allocated yet.
@@ -159,7 +159,7 @@ cogl_texture_2d_sliced_new_with_size (CoglContext *ctx,
* wasted padding at the bottom and right of the textures is less than
* specified. A negative @max_waste will disable slicing.
*
- * This api will always immediately allocate GPU memory for all
+ * This api will always immediately allocate GPU memory for all
* the required texture slices and upload the given data so that the
* @data pointer does not need to remain valid once this function
* returns. This means it is not possible to configure the texture
@@ -168,13 +168,13 @@ cogl_texture_2d_sliced_new_with_size (CoglContext *ctx,
* for example) then you can instead create a #CoglBitmap for your
* data and use cogl_texture_2d_sliced_new_from_bitmap() or use
* cogl_texture_2d_sliced_new_with_size() and then upload data using
- * cogl_texture_set_data()
+ * cogl_texture_set_data()
*
- * It's possible for the allocation of a sliced texture to fail
+ * It's possible for the allocation of a sliced texture to fail
* due to impossible slicing constraints if a negative @max_waste
* value is given. If the given virtual texture size is larger than is
* supported by the hardware but slicing is disabled the texture size
- * would be too large to handle.
+ * would be too large to handle.
*
* Return value: (transfer full): A newly created #CoglTexture2DSliced
* or %NULL on failure and @error will be updated.
@@ -219,11 +219,11 @@ cogl_texture_2d_sliced_new_from_data (CoglContext *ctx,
* allocate the underlying storage or let Cogl automatically allocate
* storage lazily.
*
- * It's possible for the allocation of a sliced texture to fail
+ * It's possible for the allocation of a sliced texture to fail
* later due to impossible slicing constraints if a negative
* @max_waste value is given. If the given virtual texture size is
* larger than is supported by the hardware but slicing is disabled
- * the texture size would be too large to handle.
+ * the texture size would be too large to handle.
*
* Return value: (transfer full): A newly created #CoglTexture2DSliced
* or %NULL on failure and @error will be updated.
diff --git a/cogl/cogl/cogl-texture-2d.h b/cogl/cogl/cogl-texture-2d.h
index 080f55a55..467db2985 100644
--- a/cogl/cogl/cogl-texture-2d.h
+++ b/cogl/cogl/cogl-texture-2d.h
@@ -152,7 +152,7 @@ cogl_texture_2d_new_with_size (CoglContext *ctx,
* Creates a low-level #CoglTexture2D texture based on data residing
* in memory.
*
- * This api will always immediately allocate GPU memory for the
+ * This api will always immediately allocate GPU memory for the
* texture and upload the given data so that the @data pointer does
* not need to remain valid once this function returns. This means it
* is not possible to configure the texture before it is allocated. If
@@ -161,7 +161,7 @@ cogl_texture_2d_new_with_size (CoglContext *ctx,
* instead create a #CoglBitmap for your data and use
* cogl_texture_2d_new_from_bitmap() or use
* cogl_texture_2d_new_with_size() and then upload data using
- * cogl_texture_set_data()
+ * cogl_texture_set_data()
*
* Returns: (transfer full): A newly allocated #CoglTexture2D, or if
* the size is not supported (because it is too large or a
diff --git a/cogl/cogl/cogl-texture.h b/cogl/cogl/cogl-texture.h
index 2d409d041..998ae22e8 100644
--- a/cogl/cogl/cogl-texture.h
+++ b/cogl/cogl/cogl-texture.h
@@ -294,10 +294,10 @@ cogl_texture_get_gl_texture (CoglTexture *texture,
*
* Copies the pixel data from a cogl texture to system memory.
*
- * Don't pass the value of cogl_texture_get_rowstride() as the
+ * Don't pass the value of cogl_texture_get_rowstride() as the
* @rowstride argument, the rowstride should be the rowstride you
* want for the destination @data buffer not the rowstride of the
- * source texture
+ * source texture
*
* Return value: the size of the texture data in bytes
*/
@@ -328,7 +328,7 @@ cogl_texture_get_data (CoglTexture *texture,
* Sets the pixels in a rectangular subregion of @texture from an in-memory
* buffer containing pixel data.
*
- * The region set can't be larger than the source @data
+ * The region set can't be larger than the source @data
*
* Return value: %TRUE if the subregion upload was successful, and
* %FALSE otherwise
@@ -374,16 +374,16 @@ cogl_texture_set_region (CoglTexture *texture,
* fraction then round the number down (floor()), but clamp to 1
* something like this:
*
- * |[
+ * ```
* next_width = MAX (1, floor (prev_width));
- * ]|
+ * ```
*
* You can determine the number of mipmap levels for a given texture
* like this:
*
- * |[
+ * ```
* n_levels = 1 + floor (log2 (max_dimension));
- * ]|
+ * ```
*
* Where %max_dimension is the larger of cogl_texture_get_width() and
* cogl_texture_get_height().
@@ -391,10 +391,10 @@ cogl_texture_set_region (CoglTexture *texture,
* It is an error to pass a @level number >= the number of levels that
* @texture can have according to the above calculation.
*
- * Since the storage for a #CoglTexture is allocated lazily then
+ * Since the storage for a #CoglTexture is allocated lazily then
* if the given @texture has not previously been allocated then this
* api can return %FALSE and throw an exceptional @error if there is
- * not enough memory to allocate storage for @texture.
+ * not enough memory to allocate storage for @texture.
*
* Return value: %TRUE if the data upload was successful, and
* %FALSE otherwise
@@ -423,8 +423,8 @@ cogl_texture_set_data (CoglTexture *texture,
* Copies a specified source region from @bitmap to the position
* (@src_x, @src_y) of the given destination texture @handle.
*
- * The region updated can't be larger than the source
- * bitmap
+ * The region updated can't be larger than the source
+ * bitmap
*
* Return value: %TRUE if the subregion upload was successful, and
* %FALSE otherwise
@@ -448,10 +448,10 @@ cogl_texture_set_region_from_bitmap (CoglTexture *texture,
* allows you to be sure that there is enough memory for the
* texture and if not then the error can be handled gracefully.
*
- * Normally applications don't need to use this api directly
+ * Normally applications don't need to use this api directly
* since the texture will be implicitly allocated when data is set on
* the texture, or if the texture is attached to a #CoglOffscreen
- * framebuffer and rendered too.
+ * framebuffer and rendered too.
*
* Return value: %TRUE if the texture was successfully allocated,
* otherwise %FALSE and @error will be updated if it
diff --git a/cogl/cogl/cogl-types.h b/cogl/cogl/cogl-types.h
index 221598187..042eae901 100644
--- a/cogl/cogl/cogl-types.h
+++ b/cogl/cogl/cogl-types.h
@@ -186,15 +186,12 @@ cogl_blend_string_error_quark (void);
* The @COGL_SYSTEM_ERROR_UNSUPPORTED error can be thrown for a
* variety of reasons. For example:
*
- *
- * You've tried to use a feature that is not
- * advertised by cogl_has_feature().
- * The GPU can not handle the configuration you have
- * requested. An example might be if you try to use too many texture
- * layers in a single #CoglPipeline
- * The driver does not support some
- * configuration.
- *
+ * - You've tried to use a feature that is not advertised by
+ * [func@Cogl.has_feature].
+ * - The GPU can not handle the configuration you have requested.
+ * An example might be if you try to use too many texture
+ * layers in a single #CoglPipeline
+ * - The driver does not support some configuration.
*
* Currently this is only used by Cogl API marked as experimental so
* this enum should also be considered experimental.
@@ -254,19 +251,14 @@ typedef enum
/**
* CoglVerticesMode:
- * @COGL_VERTICES_MODE_POINTS: FIXME, equivalent to
- * GL_POINTS
- * @COGL_VERTICES_MODE_LINES: FIXME, equivalent to GL_LINES
- * @COGL_VERTICES_MODE_LINE_LOOP: FIXME, equivalent to
- * GL_LINE_LOOP
- * @COGL_VERTICES_MODE_LINE_STRIP: FIXME, equivalent to
- * GL_LINE_STRIP
- * @COGL_VERTICES_MODE_TRIANGLES: FIXME, equivalent to
- * GL_TRIANGLES
- * @COGL_VERTICES_MODE_TRIANGLE_STRIP: FIXME, equivalent to
- * GL_TRIANGLE_STRIP
- * @COGL_VERTICES_MODE_TRIANGLE_FAN: FIXME, equivalent to GL_TRIANGLE_FAN
- *
+ * @COGL_VERTICES_MODE_POINTS: FIXME, equivalent to `GL_POINTS`
+ * @COGL_VERTICES_MODE_LINES: FIXME, equivalent to `GL_LINES`
+ * @COGL_VERTICES_MODE_LINE_LOOP: FIXME, equivalent to `GL_LINE_LOOP`
+ * @COGL_VERTICES_MODE_LINE_STRIP: FIXME, equivalent to `GL_LINE_STRIP`
+ * @COGL_VERTICES_MODE_TRIANGLES: FIXME, equivalent to `GL_TRIANGLES`
+ * @COGL_VERTICES_MODE_TRIANGLE_STRIP: FIXME, equivalent to `GL_TRIANGLE_STRIP`
+ * @COGL_VERTICES_MODE_TRIANGLE_FAN: FIXME, equivalent to `GL_TRIANGLE_FAN`
+ *
* Different ways of interpreting vertices when drawing.
*/
typedef enum
diff --git a/cogl/cogl/cogl1-context.h b/cogl/cogl/cogl1-context.h
index 182d98e7b..9164ea7fe 100644
--- a/cogl/cogl/cogl1-context.h
+++ b/cogl/cogl/cogl1-context.h
@@ -52,9 +52,9 @@ G_BEGIN_DECLS
* as a wrapper around glXGetProcAddress() or whatever is the
* appropriate function for the current backend.
*
- * This function should not be used to query core opengl API
+ * This function should not be used to query core opengl API
* symbols since eglGetProcAddress for example doesn't allow this and
- * and may return a junk pointer if you do.
+ * and may return a junk pointer if you do.
*
* Return value: a pointer to the requested function or %NULL if the
* function is not available.
diff --git a/cogl/cogl/deprecated/cogl-shader.h b/cogl/cogl/deprecated/cogl-shader.h
index d880886cd..4c74b743f 100644
--- a/cogl/cogl/deprecated/cogl-shader.h
+++ b/cogl/cogl/deprecated/cogl-shader.h
@@ -57,164 +57,66 @@ G_BEGIN_DECLS
*
* For use in all GLSL shaders, the Cogl builtins are as follows:
*
- *
- *
- *
- * uniform mat4
- * cogl_modelview_matrix
- *
+ * - `uniform mat4 cogl_modelview_matrix`
* The current modelview matrix. This is equivalent to
* #gl_ModelViewMatrix.
- *
- *
- *
- * uniform mat4
- * cogl_projection_matrix
- *
+ * - `uniform mat4 cogl_projection_matrix`
* The current projection matrix. This is equivalent to
* #gl_ProjectionMatrix.
- *
- *
- *
- * uniform mat4
- * cogl_modelview_projection_matrix
- *
+* - `uniform mat4 cogl_modelview_projection_matrix`
* The combined modelview and projection matrix. A vertex shader
* would typically use this to transform the incoming vertex
* position. The separate modelview and projection matrices are
* usually only needed for lighting calculations. This is
* equivalent to #gl_ModelViewProjectionMatrix.
- *
- *
- *
- * uniform mat4
- * cogl_texture_matrix[]
- *
+ * - `uniform mat4 cogl_texture_matrix[]`
* An array of matrices for transforming the texture
* coordinates. This is equivalent to #gl_TextureMatrix.
- *
- *
- *
- *
*
* In a vertex shader, the following are also available:
*
- *
- *
- *
- * attribute vec4
- * cogl_position_in
- *
+ * - `attribute vec4 cogl_position_in`
* The incoming vertex position. This is equivalent to #gl_Vertex.
- *
- *
- *
- * attribute vec4
- * cogl_color_in
- *
+ * - `attribute vec4 cogl_color_in`
* The incoming vertex color. This is equivalent to #gl_Color.
- *
- *
- *
- * attribute vec4
- * cogl_tex_coord_in
- *
+ * - `attribute vec4 cogl_tex_coord_in`
* The texture coordinate for the first texture unit. This is
* equivalent to #gl_MultiTexCoord0.
- *
- *
- *
- * attribute vec4
- * cogl_tex_coord0_in
- *
+ * - `attribute vec4 cogl_tex_coord0_in`
* The texture coordinate for the first texture unit. This is
* equivalent to #gl_MultiTexCoord0. There is also
* #cogl_tex_coord1_in and so on.
- *
- *
- *
- * attribute vec3
- * cogl_normal_in
- *
+ * - `attribute vec3 cogl_normal_in`
* The normal of the vertex. This is equivalent to #gl_Normal.
- *
- *
- *
- * vec4
- * cogl_position_out
- *
+ * - `vec4 cogl_position_out`
* The calculated position of the vertex. This must be written to
* in all vertex shaders. This is equivalent to #gl_Position.
- *
- *
- *
- * float
- * cogl_point_size_out
- *
+ * - `float cogl_point_size_out`
* The calculated size of a point. This is equivalent to #gl_PointSize.
- *
- *
- *
- * varying vec4
- * cogl_color_out
- *
+ * - `varying vec4 cogl_color_out`
* The calculated color of a vertex. This is equivalent to #gl_FrontColor.
- *
- *
- *
- * varying vec4
- * cogl_tex_coord_out[]
- *
+ * - `varying vec4 cogl_tex_coord_out[]`
* An array of calculated texture coordinates for a vertex. This is
* equivalent to #gl_TexCoord.
- *
- *
- *
- *
*
* In a fragment shader, the following are also available:
*
- *
- *
- *
- * varying vec4 cogl_color_in
- *
+ * - `varying vec4 cogl_color_in`
* The calculated color of a vertex. This is equivalent to #gl_FrontColor.
- *
- *
- *
- * varying vec4
- * cogl_tex_coord_in[]
- *
+ * - `varying vec4 cogl_tex_coord_in[]`
* An array of calculated texture coordinates for a vertex. This is
* equivalent to #gl_TexCoord.
- *
- *
- *
- * vec4 cogl_color_out
- *
+ * - `vec4 cogl_color_out`
* The final calculated color of the fragment. All fragment shaders
* must write to this variable. This is equivalent to
* #gl_FrontColor.
- *
- *
- *
- * float cogl_depth_out
- *
+ * - `float cogl_depth_out`
* An optional output variable specifying the depth value to use
* for this fragment. This is equivalent to #gl_FragDepth.
- *
- *
- *
- * bool cogl_front_facing
- *
+ * - `bool cogl_front_facing`
* A readonly variable that will be true if the current primitive
* is front facing. This can be used to implement two-sided
* coloring algorithms. This is equivalent to #gl_FrontFacing.
- *
- *
- *
- *
*
* It's worth nothing that this API isn't what Cogl would like to have
* in the long term and it may be removed in Cogl 2.0. The
@@ -264,10 +166,7 @@ cogl_create_shader (CoglShaderType shader_type);
*
* Replaces the current source associated with a shader with a new
* one.
- *
- * Please see above
- * for a description of the recommended format for the shader code.
+ *
* Deprecated: 1.16: Use #CoglSnippet api
*/
COGL_DEPRECATED_FOR (cogl_snippet_)
diff --git a/src/compositor/meta-multi-texture.c b/src/compositor/meta-multi-texture.c
index bb17a03a4..793d48d7a 100644
--- a/src/compositor/meta-multi-texture.c
+++ b/src/compositor/meta-multi-texture.c
@@ -198,7 +198,7 @@ meta_multi_texture_class_init (MetaMultiTextureClass *klass)
* @n_planes: The number of planes
*
* Creates a #MetaMultiTexture with the given @format. Each of the
- * #CoglTextures represents a plane.
+ * `CoglTexture`s represents a plane.
*
* Returns: (transfer full): A new #MetaMultiTexture. Use g_object_unref() when
* you're done with it.
diff --git a/src/tests/clutter-test-utils.c b/src/tests/clutter-test-utils.c
index 2745b683e..9e4e9366d 100644
--- a/src/tests/clutter-test-utils.c
+++ b/src/tests/clutter-test-utils.c
@@ -233,7 +233,7 @@ clutter_test_add_data_full (const char *test_path,
* The typical test suite is composed of a list of functions
* called by clutter_test_run(), for instance:
*
- * |[
+ * ```c
* static void unit_foo (void) { ... }
*
* static void unit_bar (void) { ... }
@@ -251,7 +251,7 @@ clutter_test_add_data_full (const char *test_path,
*
* return clutter_test_run ();
* }
- * ]|
+ * ```
*
* Return value: the exit code for the test suite
*/
diff --git a/src/tests/clutter-test-utils.h b/src/tests/clutter-test-utils.h
index fc0ad8d8e..0d70d54b5 100644
--- a/src/tests/clutter-test-utils.h
+++ b/src/tests/clutter-test-utils.h
@@ -51,16 +51,16 @@ G_BEGIN_DECLS
*
* Defines the entry point and initializes a Clutter test unit, e.g.:
*
- * |[
+ * ```
* CLUTTER_TEST_SUITE (
* CLUTTER_TEST_UNIT ("/foobarize", foobarize)
* CLUTTER_TEST_UNIT ("/bar-enabled", bar_enabled)
* )
- * ]|
+ * ```
*
* Expands to:
*
- * |[
+ * ```c
* int
* main (int argc,
* char *argv[])
@@ -72,7 +72,7 @@ G_BEGIN_DECLS
*
* return clutter_test_run ();
* }
- * ]|
+ * ```
*/
#define CLUTTER_TEST_SUITE(units) \
int \