From e7a920f94d64b11ee96d557a97d23c6329ec23a1 Mon Sep 17 00:00:00 2001 From: Bilal Elmoussaoui Date: Thu, 4 Jan 2024 13:14:20 +0100 Subject: [PATCH] docs: Migrate remaining content to markdown By stopping using gtk-doc annotations Part-of: --- clutter/clutter/cally/cally-actor.h | 3 - clutter/clutter/cally/cally-clone.h | 6 - clutter/clutter/cally/cally-root.h | 6 - clutter/clutter/cally/cally-stage.h | 6 - clutter/clutter/cally/cally-text.h | 6 - clutter/clutter/cally/cally-util.h | 6 - clutter/clutter/clutter-actor.c | 3 +- clutter/clutter/clutter-color.c | 3 +- cogl/cogl/cogl-atlas-texture.h | 32 +-- cogl/cogl/cogl-attribute-buffer.h | 8 +- cogl/cogl/cogl-attribute.h | 42 ++- cogl/cogl/cogl-bitmap.h | 4 +- cogl/cogl/cogl-buffer.h | 4 +- cogl/cogl/cogl-color.h | 4 +- cogl/cogl/cogl-context.h | 6 +- cogl/cogl/cogl-display.h | 5 - cogl/cogl/cogl-frame-info.h | 8 +- cogl/cogl/cogl-framebuffer.h | 70 ++--- cogl/cogl/cogl-glib-source.h | 4 +- cogl/cogl/cogl-graphene.h | 8 +- cogl/cogl/cogl-indices.h | 4 +- cogl/cogl/cogl-matrix-stack.h | 50 ++-- cogl/cogl/cogl-meta-texture.h | 16 +- cogl/cogl/cogl-offscreen.h | 4 +- cogl/cogl/cogl-onscreen-template.h | 4 +- cogl/cogl/cogl-onscreen.h | 32 +-- cogl/cogl/cogl-pipeline-layer-state.h | 118 ++++----- cogl/cogl/cogl-pipeline-private.h | 6 +- cogl/cogl/cogl-pipeline-state.h | 68 ++--- cogl/cogl/cogl-poll.h | 18 +- cogl/cogl/cogl-primitive.h | 114 ++++----- cogl/cogl/cogl-renderer.h | 12 - cogl/cogl/cogl-snippet.h | 352 ++++++-------------------- cogl/cogl/cogl-sub-texture.h | 4 +- cogl/cogl/cogl-texture-2d-sliced.h | 16 +- cogl/cogl/cogl-texture-2d.h | 4 +- cogl/cogl/cogl-texture.h | 26 +- cogl/cogl/cogl-types.h | 36 +-- cogl/cogl/cogl1-context.h | 4 +- cogl/cogl/deprecated/cogl-shader.h | 139 ++-------- src/compositor/meta-multi-texture.c | 2 +- src/tests/clutter-test-utils.c | 4 +- src/tests/clutter-test-utils.h | 8 +- 43 files changed, 439 insertions(+), 836 deletions(-) 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 \