brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Migrate remaining content to markdown

Browse Source 
By stopping using gtk-doc annotations

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/3489>
This commit is contained in:
Bilal Elmoussaoui 2024-01-04 13:14:20 +01:00 committed by Marge Bot
parent a0a1d102a0
commit e7a920f94d
43 changed files with 439 additions and 836 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
clutter/clutter/cally/cally-actor.h
View File

@ -81,9 +81,6 @@ struct _CallyActor
* @notify_clutter: Signal handler for notify signal on Clutter actor * @notify_clutter: Signal handler for notify signal on Clutter actor
* @add_actor: Signal handler for child-added 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 * @remove_actor: Signal handler for child-removed signal on Clutter actor
*
* The <structname>CallyActorClass</structname> structure contains
* only private data
*/ */
struct _CallyActorClass struct _CallyActorClass
{ {

6
clutter/clutter/cally/cally-clone.h
View File

@ -48,12 +48,6 @@ struct _CallyClone
CallyClonePrivate *priv; CallyClonePrivate *priv;
}; };
/**
* CallyCloneClass:
*
* The <structname>CallyCloneClass</structname> structure contains only
* private data
*/
struct _CallyCloneClass struct _CallyCloneClass
{ {
/*< private >*/ /*< private >*/

6
clutter/clutter/cally/cally-root.h
View File

@ -49,12 +49,6 @@ struct _CallyRoot
CallyRootPrivate *priv; CallyRootPrivate *priv;
}; };
/**
* CallyRootClass:
*
* The <structname>CallyRootClass</structname> structure contains only
* private data
*/
struct _CallyRootClass struct _CallyRootClass
{ {
/*< private >*/ /*< private >*/

6
clutter/clutter/cally/cally-stage.h
View File

@ -48,12 +48,6 @@ struct _CallyStage
CallyStagePrivate *priv; CallyStagePrivate *priv;
}; };
/**
* CallyStageClass:
*
* The <structname>CallyStageClass</structname> structure contains only
* private data
*/
struct _CallyStageClass struct _CallyStageClass
{ {
/*< private >*/ /*< private >*/

6
clutter/clutter/cally/cally-text.h
View File

@ -48,12 +48,6 @@ struct _CallyText
CallyTextPrivate *priv; CallyTextPrivate *priv;
}; };
/**
* CallyTextClass:
*
* The <structname>CallyTextClass</structname> structure contains only
* private data
*/
struct _CallyTextClass struct _CallyTextClass
{ {
/*< private >*/ /*< private >*/

6
clutter/clutter/cally/cally-util.h
View File

@ -48,12 +48,6 @@ struct _CallyUtil
CallyUtilPrivate *priv; CallyUtilPrivate *priv;
}; };
/**
* CallyUtilClass:
*
* The <structname>CallyUtilClass</structname> structure contains only
* private data
*/
struct _CallyUtilClass struct _CallyUtilClass
{ {
/*< private >*/ /*< private >*/

3
clutter/clutter/clutter-actor.c
View File

@ -5429,8 +5429,7 @@ clutter_actor_finalize (GObject *object)
* implementation from the first ancestor class for which such an * implementation from the first ancestor class for which such an
* implementation is defined. * implementation is defined.
* *
* The documentation of the <ulink * The documentation of the [https://gnome.pages.gitlab.gnome.org/at-spi2-core/atk/](ATK)
* url="http://developer.gnome.org/doc/API/2.0/atk/index.html">ATK</ulink>
* library contains more information about accessible objects and * library contains more information about accessible objects and
* their uses. * their uses.
* *

3
clutter/clutter/clutter-color.c
View File

@ -761,8 +761,7 @@ clutter_color_from_string (ClutterColor *color,
* @color: a #ClutterColor * @color: a #ClutterColor
* *
* Returns a textual specification of @color in the hexadecimal form * Returns a textual specification of @color in the hexadecimal form
* <literal>&num;rrggbbaa</literal>, where <literal>r</literal>, * `&num;rrggbbaa`, where `r`, `g`, `b` and `a` are
* <literal>g</literal>, <literal>b</literal> and <literal>a</literal> are
* hexadecimal digits representing the red, green, blue and alpha components * hexadecimal digits representing the red, green, blue and alpha components
* respectively. * respectively.
* *

32
cogl/cogl/cogl-atlas-texture.h
View File

@ -60,9 +60,9 @@ G_BEGIN_DECLS
* shared texture atlases using a high-level #CoglAtlasTexture which * shared texture atlases using a high-level #CoglAtlasTexture which
* represents a sub-region of one of these atlases. * represents a sub-region of one of these atlases.
* *
* <note>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 * some limitations to be aware of. Please see the documentation for
* #CoglMetaTexture for more details.</note> * #CoglMetaTexture for more details.
*/ */
#define COGL_TYPE_ATLAS_TEXTURE (cogl_atlas_texture_get_type ()) #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)) #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 * using cogl_texture_set_components() and
* cogl_texture_set_premultiplied(). * cogl_texture_set_premultiplied().
* *
* <note>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 * format to be incompatible with the format of its internal
* atlases.</note> * atlases.
* *
* <note>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 * with some limitations. See the documentation for #CoglMetaTexture
* for more details.</note> * for more details.
* *
* Returns: (transfer full): A new #CoglAtlasTexture object. * 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 * memory. A #CoglAtlasTexture represents a sub-region within one of
* Cogl's shared texture atlases. * Cogl's shared texture atlases.
* *
* <note>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 * texture and upload the given data so that the @data pointer does
* not need to remain valid once this function returns. This means it * not need to remain valid once this function returns. This means it
* is not possible to configure the texture before it is allocated. If * 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 * instead create a #CoglBitmap for your data and use
* cogl_atlas_texture_new_from_bitmap() or use * cogl_atlas_texture_new_from_bitmap() or use
* cogl_atlas_texture_new_with_size() and then upload data using * cogl_atlas_texture_new_with_size() and then upload data using
* cogl_texture_set_data()</note> * cogl_texture_set_data()
* *
* <note>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 * format to be incompatible with the format of its internal
* atlases.</note> * atlases.
* *
* <note>The returned #CoglAtlasTexture is a high-level * The returned #CoglAtlasTexture is a high-level
* meta-texture with some limitations. See the documentation for * meta-texture with some limitations. See the documentation for
* #CoglMetaTexture for more details.</note> * #CoglMetaTexture for more details.
* *
* Return value: (transfer full): A new #CoglAtlasTexture object or * Return value: (transfer full): A new #CoglAtlasTexture object or
* %NULL on failure and @error will be updated. * %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 * using cogl_texture_set_components() and
* cogl_texture_set_premultiplied(). * cogl_texture_set_premultiplied().
* *
* <note>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 * format to be incompatible with the format of its internal
* atlases.</note> * atlases.
* *
* <note>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 * with some limitations. See the documentation for #CoglMetaTexture
* for more details.</note> * for more details.
* *
* Returns: (transfer full): A new #CoglAtlasTexture object. * Returns: (transfer full): A new #CoglAtlasTexture object.
*/ */

8
cogl/cogl/cogl-attribute-buffer.h
View File

@ -107,16 +107,16 @@ cogl_attribute_buffer_new_with_size (CoglContext *context,
* *
* You should never pass a %NULL data pointer. * You should never pass a %NULL data pointer.
* *
* <note>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 * the caller by returning %NULL and so you can assume this function
* always succeeds.</note> * always succeeds.
* *
* <note>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 * then Cogl will abort the application with a message. If your
* application needs to gracefully handle out-of-memory errors then * application needs to gracefully handle out-of-memory errors then
* you can use cogl_attribute_buffer_new_with_size() and then * you can use cogl_attribute_buffer_new_with_size() and then
* explicitly catch errors with cogl_buffer_set_data() or * explicitly catch errors with cogl_buffer_set_data() or
* cogl_buffer_map().</note> * cogl_buffer_map().
* *
* Return value: (transfer full): A newly allocated #CoglAttributeBuffer (never %NULL) * Return value: (transfer full): A newly allocated #CoglAttributeBuffer (never %NULL)
*/ */

42
cogl/cogl/cogl-attribute.h
View File

@ -65,10 +65,10 @@ G_DECLARE_FINAL_TYPE (CoglAttribute,
* @name: The name of the attribute (used to reference it from GLSL) * @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 * @stride: The number of bytes to jump to get to the next attribute
* value for the next vertex. (Usually * value for the next vertex. (Usually
* <literal>sizeof (MyVertex)</literal>) * `sizeof (MyVertex)`)
* @offset: The byte offset from the start of @attribute_buffer for * @offset: The byte offset from the start of @attribute_buffer for
* the first attribute value. (Usually * the first attribute value. (Usually
* <literal>offsetof (MyVertex, component0)</literal> * `offsetof (MyVertex, component0)`
* @components: The number of components (e.g. 4 for an rgba color or * @components: The number of components (e.g. 4 for an rgba color or
* 3 for and (x,y,z) position) * 3 for and (x,y,z) position)
* @type: FIXME * @type: FIXME
@ -79,50 +79,48 @@ G_DECLARE_FINAL_TYPE (CoglAttribute,
* The @name is used to access the attribute inside a GLSL vertex * 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 * shader and there are some special names you should use if they are
* applicable: * applicable:
* <itemizedlist> *
* <listitem>"cogl_position_in" (used for vertex positions)</listitem> * - "cogl_position_in" (used for vertex positions)
* <listitem>"cogl_color_in" (used for vertex colors)</listitem> * - "cogl_color_in" (used for vertex colors)
* <listitem>"cogl_tex_coord0_in", "cogl_tex_coord1", ... * - "cogl_tex_coord0_in", "cogl_tex_coord1", ...
* (used for vertex texture coordinates)</listitem> * (used for vertex texture coordinates)
* <listitem>"cogl_normal_in" (used for vertex normals)</listitem> * - "cogl_normal_in" (used for vertex normals)
* <listitem>"cogl_point_size_in" (used to set the size of points * - "cogl_point_size_in" (used to set the size of points
* per-vertex. Note this can only be used if * per-vertex. Note this can only be used if
* %COGL_FEATURE_ID_POINT_SIZE_ATTRIBUTE is advertised and * %COGL_FEATURE_ID_POINT_SIZE_ATTRIBUTE is advertised and
* cogl_pipeline_set_per_vertex_point_size() is called on the pipeline. * cogl_pipeline_set_per_vertex_point_size() is called on the pipeline.
* </listitem>
* </itemizedlist>
* *
* The attribute values corresponding to different vertices can either * The attribute values corresponding to different vertices can either
* be tightly packed or interleaved with other attribute values. For * be tightly packed or interleaved with other attribute values. For
* example it's common to define a structure for a single vertex like: * example it's common to define a structure for a single vertex like:
* |[ * ```c
* typedef struct * typedef struct
* { * {
* float x, y, z; /<!-- -->* position attribute *<!-- -->/ * float x, y, z; /<!-- -->* position attribute *<!-- -->/
* float s, t; /<!-- -->* texture coordinate attribute *<!-- -->/ * float s, t; /<!-- -->* texture coordinate attribute *<!-- -->/
* } MyVertex; * } MyVertex;
* ]| * ```
* *
* And then create an array of vertex data something like: * And then create an array of vertex data something like:
* |[ * ```c
* MyVertex vertices[100] = { .... } * MyVertex vertices[100] = { .... }
* ]| * ```
* *
* In this case, to describe either the position or texture coordinate * In this case, to describe either the position or texture coordinate
* attribute you have to move <literal>sizeof (MyVertex)</literal> bytes to * attribute you have to move `sizeof (MyVertex)` bytes to
* move from one vertex to the next. This is called the attribute * move from one vertex to the next. This is called the attribute
* @stride. If you weren't interleving attributes and you instead had * @stride. If you weren't interleving attributes and you instead had
* a packed array of float x, y pairs then the attribute stride would * a packed array of float x, y pairs then the attribute stride would
* be <literal>(2 * sizeof (float))</literal>. 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. * bytes to move to find the attribute value of the next vertex.
* *
* Normally a list of attributes starts at the beginning of an array. * Normally a list of attributes starts at the beginning of an array.
* So for the <literal>MyVertex</literal> example above the @offset is the * So for the `MyVertex` example above the @offset is the
* offset inside the <literal>MyVertex</literal> structure to the first * offset inside the `MyVertex` structure to the first
* component of the attribute. For the texture coordinate attribute * component of the attribute. For the texture coordinate attribute
* the offset would be <literal>offsetof (MyVertex, s)</literal> or instead of * the offset would be `offsetof (MyVertex, s)` or instead of
* using the offsetof macro you could use <literal>sizeof (float) * * using the offsetof macro you could use `sizeof (float) *
* 3</literal>. If you've divided your @array into blocks of non-interleved * 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 * attributes then you will need to calculate the @offset as the number of
* bytes in blocks preceding the attribute you're describing. * bytes in blocks preceding the attribute you're describing.
* *

4
cogl/cogl/cogl-bitmap.h
View File

@ -105,13 +105,13 @@ cogl_bitmap_new_from_buffer (CoglBuffer *buffer,
* cogl_bitmap_get_buffer(). The #CoglBuffer API can then be * cogl_bitmap_get_buffer(). The #CoglBuffer API can then be
* used to fill the bitmap with data. * used to fill the bitmap with data.
* *
* <note>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 * map, write into and effectively do a zero copy upload when creating
* a texture from it with cogl_texture_new_from_bitmap(). For various * a texture from it with cogl_texture_new_from_bitmap(). For various
* reasons, such arrays are likely to have a stride larger than width * reasons, such arrays are likely to have a stride larger than width
* * bytes_per_pixel. The user must take the stride into account when * * bytes_per_pixel. The user must take the stride into account when
* writing into it. The stride can be retrieved with * writing into it. The stride can be retrieved with
* cogl_bitmap_get_rowstride().</note> * cogl_bitmap_get_rowstride().
* *
* Return value: (transfer full): a #CoglPixelBuffer representing the * Return value: (transfer full): a #CoglPixelBuffer representing the
* newly created array or %NULL on failure * newly created array or %NULL on failure

4
cogl/cogl/cogl-buffer.h
View File

@ -202,7 +202,7 @@ typedef enum /*< prefix=COGL_BUFFER_BIND_TARGET >*/
* cogl_buffer_map: * cogl_buffer_map:
* @buffer: a buffer object * @buffer: a buffer object
* @access: how the mapped buffer will be used by the application * @access: how the mapped buffer will be used by the application
* @hints: A mask of #CoglBufferMapHint<!-- -->s that tell Cogl how * @hints: A mask of `CoglBufferMapHint`s that tell Cogl how
* the data will be modified once mapped. * the data will be modified once mapped.
* *
* Maps the buffer into the application address space for direct * 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 * @offset: Offset within the buffer to start the mapping
* @size: The size of data to map * @size: The size of data to map
* @access: how the mapped buffer will be used by the application * @access: how the mapped buffer will be used by the application
* @hints: A mask of #CoglBufferMapHint<!-- -->s that tell Cogl how * @hints: A mask of `CoglBufferMapHint`s that tell Cogl how
* the data will be modified once mapped. * the data will be modified once mapped.
* @error: A #GError for catching exceptional errors * @error: A #GError for catching exceptional errors
* *

4
cogl/cogl/cogl-color.h
View File

@ -440,10 +440,10 @@ cogl_color_unpremultiply (CoglColor *color);
* @v1: a #CoglColor * @v1: a #CoglColor
* @v2: a #CoglColor * @v2: a #CoglColor
* *
* Compares two #CoglColor<!-- -->s 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 * This function can be passed to g_hash_table_new() as the @key_equal_func
* parameter, when using #CoglColor<!-- -->s 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. * Return value: %TRUE if the two colors are the same.
*/ */

6
cogl/cogl/cogl-context.h
View File

@ -73,7 +73,7 @@ G_BEGIN_DECLS
* that can all access the same GPU without having to worry about * that can all access the same GPU without having to worry about
* what state other components have left you with. * what state other components have left you with.
* *
* <note><para>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 * resources that depend on the context so applications. This is to
* help applications control the lifetime a context without us needing to * help applications control the lifetime a context without us needing to
* introduce special api to handle the breakup of internal circular * 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 * times throughout their lifetime (such as Android applications) they
* should be careful to destroy all context dependent resources, such as * should be careful to destroy all context dependent resources, such as
* framebuffers or textures etc before unrefing and destroying the * framebuffers or textures etc before unrefing and destroying the
* context.</para></note> * context.
*/ */
#define COGL_TYPE_CONTEXT (cogl_context_get_type ()) #define COGL_TYPE_CONTEXT (cogl_context_get_type ())
@ -219,7 +219,7 @@ cogl_has_feature (CoglContext *context, CoglFeatureID feature);
/** /**
* cogl_has_features: * cogl_has_features:
* @context: A #CoglContext pointer * @context: A #CoglContext pointer
* @...: A 0 terminated list of CoglFeatureID<!-- -->s * @...: A 0 terminated list of `CoglFeatureID`s
* *
* Checks if a list of features are all currently available. * Checks if a list of features are all currently available.
* *

5
cogl/cogl/cogl-display.h
View File

@ -86,11 +86,6 @@ G_DECLARE_FINAL_TYPE (CoglDisplay,
* common state of the display pipeline that applies to the whole * common state of the display pipeline that applies to the whole
* application. * application.
* *
* <note>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.</note>
*
* A @display can only be made for a specific choice of renderer which * A @display can only be made for a specific choice of renderer which
* is why this takes the @renderer argument. * is why this takes the @renderer argument.
* *

8
cogl/cogl/cogl-frame-info.h
View File

@ -83,8 +83,8 @@ int64_t cogl_frame_info_get_frame_counter (CoglFrameInfo *info);
* The presentation time measured in microseconds, is based on * The presentation time measured in microseconds, is based on
* CLOCK_MONOTONIC. * CLOCK_MONOTONIC.
* *
* <note>Some buggy Mesa drivers up to 9.0.1 may * Some buggy Mesa drivers up to 9.0.1 may
* incorrectly report non-monotonic timestamps.</note> * incorrectly report non-monotonic timestamps.
* *
* Return value: the presentation time for the frame * 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 * Gets the refresh rate in Hertz for the output that the frame was on
* at the time the frame was presented. * at the time the frame was presented.
* *
* <note>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 * #CoglFrameInfo object but are able to report a refresh rate via
* this api. Therefore if you need this information then this api is * this api. Therefore if you need this information then this api is
* more reliable than using cogl_frame_info_get_output() followed by * more reliable than using cogl_frame_info_get_output() followed by
* cogl_output_get_refresh_rate().</note> * cogl_output_get_refresh_rate().
* *
* Return value: the refresh rate in Hertz * Return value: the refresh rate in Hertz
*/ */

70
cogl/cogl/cogl-framebuffer.h
View File

@ -110,12 +110,12 @@ struct _CoglFramebufferClass
* check and handle any errors that might arise from an unsupported * check and handle any errors that might arise from an unsupported
* configuration so that fallback configurations may be tried. * configuration so that fallback configurations may be tried.
* *
* <note>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 * 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 * since Cogl will automatically allocate a framebuffer when it first gets
* used. The disadvantage of relying on automatic allocation is that the * used. The disadvantage of relying on automatic allocation is that the
* program will abort with an error message if there is an error during * program will abort with an error message if there is an error during
* automatic allocation.</note> * automatic allocation.
* *
* Return value: %TRUE if there were no error allocating the framebuffer, else %FALSE. * 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 * contents down by specify and width and height that's half the real
* size of the framebuffer. * size of the framebuffer.
* *
* <note>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 * drivers only allow the use of integer values. In the future floating
* point values will be exposed via a checkable feature.</note> * point values will be exposed via a checkable feature.
* *
*/ */
COGL_EXPORT void COGL_EXPORT void
@ -382,10 +382,10 @@ cogl_framebuffer_set_modelview_matrix (CoglFramebuffer *framebuffer,
* Replaces the current projection matrix with a perspective matrix * Replaces the current projection matrix with a perspective matrix
* based on the provided values. * based on the provided values.
* *
* <note>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 * ratio since that will reduce the effectiveness of depth testing
* since there won't be enough precision to identify the depth of * since there won't be enough precision to identify the depth of
* objects near to each other.</note> * objects near to each other.
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_framebuffer_perspective (CoglFramebuffer *framebuffer, 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 * @y_1: The y coordinate for the first horizontal clipping plane
* @x_2: The x coordinate for the second vertical clipping plane * @x_2: The x coordinate for the second vertical clipping plane
* @y_2: The y coordinate for the second horizontal clipping plane * @y_2: The y coordinate for the second horizontal clipping plane
* @near: The <emphasis>distance</emphasis> to the near clipping * @near: The *distance* to the near clipping
* plane (will be <emphasis>negative</emphasis> if the plane is * plane (will be *negative* if the plane is
* behind the viewer) * behind the viewer)
* @far: The <emphasis>distance</emphasis> to the far clipping * @far: The *distance* to the far clipping
* plane (will be <emphasis>negative</emphasis> if the plane is * plane (will be *negative* if the plane is
* behind the viewer) * behind the viewer)
* *
* Replaces the current projection matrix with an orthographic projection * 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. * Returns whether dithering has been requested for the given @framebuffer.
* See cogl_framebuffer_set_dither_enabled() for more details about dithering. * See cogl_framebuffer_set_dither_enabled() for more details about dithering.
* *
* <note>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 * display pipeline does not support dithering. This value only represents
* the user's request for dithering.</note> * the user's request for dithering.
* *
* Return value: %TRUE if dithering has been requested or %FALSE if not. * 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 * as "single-sample" rendering. A value of 1 or greater is referred
* to as "multisample" rendering. * to as "multisample" rendering.
* *
* <note>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 * rendering and multisampling with just 1 point sample such as it
* being redundant to use the cogl_framebuffer_resolve_samples() and * being redundant to use the cogl_framebuffer_resolve_samples() and
* cogl_framebuffer_resolve_samples_region() apis with single-sample * cogl_framebuffer_resolve_samples_region() apis with single-sample
* rendering.</note> * rendering.
* *
* <note>It's recommended that * It's recommended that
* cogl_framebuffer_resolve_samples_region() be explicitly used at the * cogl_framebuffer_resolve_samples_region() be explicitly used at the
* end of rendering to a point sample buffer to minimize the number of * end of rendering to a point sample buffer to minimize the number of
* samples that get resolved. By default Cogl will implicitly resolve * samples that get resolved. By default Cogl will implicitly resolve
* all framebuffer samples but if only a small region of a * all framebuffer samples but if only a small region of a
* framebuffer has changed this can lead to redundant work being * framebuffer has changed this can lead to redundant work being
* done.</note> * done.
* *
*/ */
COGL_EXPORT void COGL_EXPORT void
@ -865,7 +865,7 @@ cogl_framebuffer_get_context (CoglFramebuffer *framebuffer);
/** /**
* cogl_framebuffer_clear: * cogl_framebuffer_clear:
* @framebuffer: A #CoglFramebuffer * @framebuffer: A #CoglFramebuffer
* @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary * @buffers: A mask of `CoglBufferBit`s identifying which auxiliary
* buffers to clear * buffers to clear
* @color: The color to clear the color buffer too if specified in * @color: The color to clear the color buffer too if specified in
* @buffers. * @buffers.
@ -882,7 +882,7 @@ cogl_framebuffer_clear (CoglFramebuffer *framebuffer,
/** /**
* cogl_framebuffer_clear4f: * cogl_framebuffer_clear4f:
* @framebuffer: A #CoglFramebuffer * @framebuffer: A #CoglFramebuffer
* @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary * @buffers: A mask of `CoglBufferBit`s identifying which auxiliary
* buffers to clear * buffers to clear
* @red: The red component of color to clear the color buffer too if * @red: The red component of color to clear the color buffer too if
* specified in @buffers. * 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 * and with the top left corner positioned at (@x_1, @y_1) and the
* bottom right corner positioned at (@x_2, @y_2). * bottom right corner positioned at (@x_2, @y_2).
* *
* <note>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 * transformed by the model-view matrix and the projection
* matrix.</note> * matrix.
* *
* <note>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 * it then you can use
* cogl_framebuffer_draw_textured_rectangle().</note> * cogl_framebuffer_draw_textured_rectangle().
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer, 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 * 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). * bottom right corner will have texture coordinates of (@s_2, @t_2).
* *
* <note>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 * transformed by the model-view matrix and the projection
* matrix.</note> * matrix.
* *
* This is a high level drawing api that can handle any kind of * This is a high level drawing api that can handle any kind of
* #CoglMetaTexture texture such as #CoglTexture2DSliced textures * #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 * which only support low level texture types that are directly
* supported by GPUs such as #CoglTexture2D. * supported by GPUs such as #CoglTexture2D.
* *
* <note>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 * texture layer of the pipeline and if your pipeline has more than
* one layer then all other layers will have default texture * 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 </note> * 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 * The given texture coordinates should always be normalized such that
* (0, 0) corresponds to the top left and (1, 1) corresponds to the * (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 * contain multiple texture layers this interface lets you supply
* texture coordinates for each layer of the pipeline. * texture coordinates for each layer of the pipeline.
* *
* <note>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 * transformed by the model-view matrix and the projection
* matrix.</note> * matrix.
* *
* This is a high level drawing api that can handle any kind of * This is a high level drawing api that can handle any kind of
* #CoglMetaTexture texture for the first layer such as * #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 * such as cogl_primitive_draw() which only support low level texture
* types that are directly supported by GPUs such as #CoglTexture2D. * types that are directly supported by GPUs such as #CoglTexture2D.
* *
* <note>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 * texture layers. The first layer may be a high level meta texture
* such as #CoglTexture2DSliced but all other layers much be low * such as #CoglTexture2DSliced but all other layers much be low
* level textures such as #CoglTexture2D. * 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 * the second rectangle are (coordinates[4], coordinates[5]) and
* (coordinates[6], coordinates[7]) and so on... * (coordinates[6], coordinates[7]) and so on...
* *
* <note>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 * transformed by the model-view matrix and the projection
* matrix.</note> * matrix.
* *
* As a general rule for better performance its recommended to use * As a general rule for better performance its recommended to use
* this this API instead of calling * this this API instead of calling
@ -1103,9 +1103,9 @@ cogl_framebuffer_draw_rectangles (CoglFramebuffer *framebuffer,
* @pipeline state in the same way that * @pipeline state in the same way that
* cogl_framebuffer_draw_textured_rectangle() does. * cogl_framebuffer_draw_textured_rectangle() does.
* *
* <note>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 * transformed by the model-view matrix and the projection
* matrix.</note> * matrix.
* *
* This is a high level drawing api that can handle any kind of * This is a high level drawing api that can handle any kind of
* #CoglMetaTexture texture such as #CoglTexture2DSliced textures * #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: * The implementation of the function looks like this:
* *
* |[ * ```c
* bitmap = cogl_bitmap_new_for_data (context, * bitmap = cogl_bitmap_new_for_data (context,
* width, height, * width, height,
* format, * format,
@ -1252,7 +1252,7 @@ cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer,
* COGL_READ_PIXELS_COLOR_BUFFER, * COGL_READ_PIXELS_COLOR_BUFFER,
* bitmap); * bitmap);
* g_object_unref (bitmap); * g_object_unref (bitmap);
* ]| * ```
* *
* Return value: %TRUE if the read succeeded or %FALSE otherwise. * Return value: %TRUE if the read succeeded or %FALSE otherwise.
*/ */

4
cogl/cogl/cogl-glib-source.h
View File

@ -59,8 +59,8 @@ G_BEGIN_DECLS
* use this api in addition later, it is simply enough to use * use this api in addition later, it is simply enough to use
* cogl_glib_renderer_source_new() instead. * cogl_glib_renderer_source_new() instead.
* *
* <note>This api is actually just a thin convenience wrapper around * This api is actually just a thin convenience wrapper around
* cogl_glib_renderer_source_new()</note> * cogl_glib_renderer_source_new()
* *
* Return value: a new #GSource * Return value: a new #GSource
*/ */

8
cogl/cogl/cogl-graphene.h
View File

@ -78,7 +78,7 @@ cogl_graphene_matrix_project_point (const graphene_matrix_t *matrix,
* cogl_graphene_matrix_project_points(). * cogl_graphene_matrix_project_points().
* *
* Here's an example with differing input/output strides: * Here's an example with differing input/output strides:
* |[ * ```c
* typedef struct { * typedef struct {
* float x,y; * float x,y;
* uint8_t r,g,b,a; * uint8_t r,g,b,a;
@ -102,7 +102,7 @@ cogl_graphene_matrix_project_point (const graphene_matrix_t *matrix,
* sizeof (MyOutVertex), * sizeof (MyOutVertex),
* &results[0].x, * &results[0].x,
* N_VERTICES); * N_VERTICES);
* ]| * ```
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_graphene_matrix_transform_points (const graphene_matrix_t *matrix, 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. * the input array to do the transform in-place.
* *
* Here's an example with differing input/output strides: * Here's an example with differing input/output strides:
* |[ * ```c
* typedef struct { * typedef struct {
* float x,y; * float x,y;
* uint8_t r,g,b,a; * uint8_t r,g,b,a;
@ -155,7 +155,7 @@ cogl_graphene_matrix_transform_points (const graphene_matrix_t *matrix,
* sizeof (MyOutVertex), * sizeof (MyOutVertex),
* &results[0].x, * &results[0].x,
* N_VERTICES); * N_VERTICES);
* ]| * ```
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_graphene_matrix_project_points (const graphene_matrix_t *matrix, cogl_graphene_matrix_project_points (const graphene_matrix_t *matrix,

4
cogl/cogl/cogl-indices.h
View File

@ -75,7 +75,7 @@ G_BEGIN_DECLS
* index buffer that specifies the 6 vertices by indexing the shared * index buffer that specifies the 6 vertices by indexing the shared
* vertices multiple times. * vertices multiple times.
* *
* |[ * ```c
* CoglVertexP2 quad_vertices[] = { * CoglVertexP2 quad_vertices[] = {
* {x0, y0}, //0 = top left * {x0, y0}, //0 = top left
* {x1, y1}, //1 = bottom left * {x1, y1}, //1 = bottom left
@ -84,7 +84,7 @@ G_BEGIN_DECLS
* }; * };
* //tell the gpu how to interpret the quad as 2 triangles... * //tell the gpu how to interpret the quad as 2 triangles...
* unsigned char indices[] = {0, 1, 2, 0, 2, 3}; * unsigned char indices[] = {0, 1, 2, 0, 2, 3};
* ]| * ```
* *
* Even in the above illustration we see a saving of 10bytes for one * 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 * quad compared to having data for 6 vertices and no indices but if

50
cogl/cogl/cogl-matrix-stack.h
View File

@ -71,14 +71,12 @@
* Compared to using the #graphene_matrix_t api directly to track many * Compared to using the #graphene_matrix_t api directly to track many
* related transforms, these can be some advantages to using a * related transforms, these can be some advantages to using a
* #CoglMatrixStack: * #CoglMatrixStack:
* <itemizedlist> *
* <listitem>Faster equality comparisons of transformations</listitem> * - Faster equality comparisons of transformations
* <listitem>Efficient comparisons of the differences between arbitrary * - Efficient comparisons of the differences between arbitrary
* transformations</listitem> * transformations
* <listitem>Avoid redundant arithmetic related to common transforms * - Avoid redundant arithmetic related to common transforms
* </listitem> * - Can be more space efficient (not always though)
* <listitem>Can be more space efficient (not always though)</listitem>
* </itemizedlist>
* *
* For reference (to give an idea of when a #CoglMatrixStack can * 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 * 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 * comparison but often these false negatives are unlikely and
* don't matter anyway so this enables extremely cheap comparisons. * don't matter anyway so this enables extremely cheap comparisons.
* *
* <note>#CoglMatrixEntry<!-- -->s are reference counted using * `CoglMatrixEntry`s are reference counted using
* cogl_matrix_entry_ref() and cogl_matrix_entry_unref() not with * cogl_matrix_entry_ref() and cogl_matrix_entry_unref() not with
* g_object_ref() and g_object_unref().</note> * g_object_ref() and g_object_unref().
*/ */
typedef struct _CoglMatrixEntry CoglMatrixEntry; 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 * Replaces the current matrix with a perspective matrix based on the
* provided values. * provided values.
* *
* <note>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 * ratio since that will reduce the effectiveness of depth testing
* since there won't be enough precision to identify the depth of * since there won't be enough precision to identify the depth of
* objects near to each other.</note> * objects near to each other.
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_matrix_stack_perspective (CoglMatrixStack *stack, 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 * @y_1: The y coordinate for the first horizontal clipping plane
* @x_2: The x coordinate for the second vertical clipping plane * @x_2: The x coordinate for the second vertical clipping plane
* @y_2: The y coordinate for the second horizontal clipping plane * @y_2: The y coordinate for the second horizontal clipping plane
* @near: The <emphasis>distance</emphasis> to the near clipping * @near: The *distance* to the near clipping
* plane (will be <emphasis>negative</emphasis> if the plane is * plane (will be *negative* if the plane is
* behind the viewer) * behind the viewer)
* @far: The <emphasis>distance</emphasis> to the far clipping * @far: The *distance* to the far clipping
* plane (will be <emphasis>negative</emphasis> if the plane is * plane (will be *negative* if the plane is
* behind the viewer) * behind the viewer)
* *
* Replaces the current matrix with an orthographic projection matrix. * 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 * Gets a reference to the current transform represented by a
* #CoglMatrixEntry pointer. * #CoglMatrixEntry pointer.
* *
* <note>The transform represented by a #CoglMatrixEntry is * The transform represented by a #CoglMatrixEntry is
* immutable.</note> * immutable.
* *
* <note>#CoglMatrixEntry<!-- -->s are reference counted using * `CoglMatrixEntry`s are reference counted using
* cogl_matrix_entry_ref() and cogl_matrix_entry_unref() and you * cogl_matrix_entry_ref() and cogl_matrix_entry_unref() and you
* should call cogl_matrix_entry_unref() when you are finished with * should call cogl_matrix_entry_unref() when you are finished with
* and entry you get via cogl_matrix_stack_get_entry().</note> * and entry you get via cogl_matrix_stack_get_entry().
* *
* Return value: (transfer none): A pointer to the #CoglMatrixEntry * Return value: (transfer none): A pointer to the #CoglMatrixEntry
* representing the current matrix stack transform. * 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 * if the function returns %NULL then @matrix will be initialized
* to match the current transform of @stack. * to match the current transform of @stack.
* *
* <note>@matrix will be left untouched if a direct pointer is * @matrix will be left untouched if a direct pointer is
* returned.</note> * returned.
* *
* Return value: A direct pointer to the current transform or %NULL * Return value: A direct pointer to the current transform or %NULL
* and in that case @matrix will be initialized with * 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 * if the function returns %NULL then @matrix will be initialized
* to match the transform of @entry. * to match the transform of @entry.
* *
* <note>@matrix will be left untouched if a direct pointer is * @matrix will be left untouched if a direct pointer is
* returned.</note> * returned.
* *
* Return value: A direct pointer to a #graphene_matrix_t transform or %NULL * Return value: A direct pointer to a #graphene_matrix_t transform or %NULL
* and in that case @matrix will be initialized with * 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 * Compares two arbitrary #CoglMatrixEntry transforms for equality
* returning %TRUE if they are equal or %FALSE otherwise. * returning %TRUE if they are equal or %FALSE otherwise.
* *
* <note>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 * direct pointer comparisons of entries are good enough and much
* cheaper too.</note> * cheaper too.
* *
* Return value: %TRUE if @entry0 represents the same transform as * Return value: %TRUE if @entry0 represents the same transform as
* @entry1, otherwise %FALSE. * @entry1, otherwise %FALSE.

16
cogl/cogl/cogl-meta-texture.h
View File

@ -44,12 +44,12 @@ G_BEGIN_DECLS
* low-level textures like #CoglTexture2D. * low-level textures like #CoglTexture2D.
* *
* Cogl helps to make it easy to deal with high level textures such * Cogl helps to make it easy to deal with high level textures such
* as #CoglAtlasTexture<!-- -->s, #CoglSubTexture<!-- -->s, * as `CoglAtlasTexture`s, `CoglSubTexture`s,
* #CoglTexturePixmapX11 textures and #CoglTexture2DSliced textures * #CoglTexturePixmapX11 textures and #CoglTexture2DSliced textures
* consistently. * consistently.
* *
* A #CoglMetaTexture is a texture that might internally be * A #CoglMetaTexture is a texture that might internally be
* represented by one or more low-level #CoglTexture<!-- -->s * represented by one or more low-level `CoglTexture`s
* such as #CoglTexture2D. These low-level textures are the only ones * such as #CoglTexture2D. These low-level textures are the only ones
* that a GPU really understands but because applications often want * that a GPU really understands but because applications often want
* more high-level texture abstractions (such as storing multiple * 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 * If you want to develop custom primitive APIs like
* cogl_framebuffer_draw_rectangle() and you want to support drawing * cogl_framebuffer_draw_rectangle() and you want to support drawing
* with #CoglAtlasTexture<!-- -->s or #CoglSubTexture<!-- -->s for * with `CoglAtlasTexture`s or `CoglSubTexture`s for
* example, then you will need to use this #CoglMetaTexture interface * example, then you will need to use this #CoglMetaTexture interface
* to be able to resolve high-level textures into low-level textures * to be able to resolve high-level textures into low-level textures
* before drawing with Cogl's low-level drawing APIs such as * before drawing with Cogl's low-level drawing APIs such as
* cogl_primitive_draw(). * cogl_primitive_draw().
* *
* <note>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 * but still it is worth understanding the distinction between
* low-level and meta textures because you may find other references * low-level and meta textures because you may find other references
* in the documentation that detail limitations of using * in the documentation that detail limitations of using
* meta-textures.</note> * meta-textures.
*/ */
/** /**
@ -110,7 +110,7 @@ G_BEGIN_DECLS
* cogl_meta_texture_foreach_in_region(). * cogl_meta_texture_foreach_in_region().
* *
* A callback used with cogl_meta_texture_foreach_in_region() to * A callback used with cogl_meta_texture_foreach_in_region() to
* retrieve details of all the low-level #CoglTexture<!-- -->s that * retrieve details of all the low-level `CoglTexture`s that
* make up a given #CoglMetaTexture. * make up a given #CoglMetaTexture.
*/ */
typedef void (*CoglMetaTextureCallback) (CoglTexture *sub_texture, 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 * internally use this API to resolve the low level textures of any
* meta textures you have associated with CoglPipeline layers. * meta textures you have associated with CoglPipeline layers.
* *
* <note>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 * don't understand the #CoglMetaTexture interface and so it is your
* responsibility to use this API to resolve all CoglPipeline textures * responsibility to use this API to resolve all CoglPipeline textures
* into low-level textures before drawing.</note> * into low-level textures before drawing.
* *
* For each low-level texture that makes up part of the given region * For each low-level texture that makes up part of the given region
* of the @meta_texture, @callback is called specifying how the * of the @meta_texture, @callback is called specifying how the

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

@ -68,9 +68,9 @@ G_DECLARE_FINAL_TYPE (CoglOffscreen, cogl_offscreen,
* updates the contents of the given texture. You don't need to * updates the contents of the given texture. You don't need to
* destroy the offscreen buffer before you can use the @texture again. * destroy the offscreen buffer before you can use the @texture again.
* *
* <note>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 * #CoglTexture2D and not with meta-texture types such as
* #CoglTexture2DSliced.</note> * #CoglTexture2DSliced.
* *
* The storage for the framebuffer is actually allocated lazily * The storage for the framebuffer is actually allocated lazily
* so this function will never return %NULL to indicate a runtime * so this function will never return %NULL to indicate a runtime

4
cogl/cogl/cogl-onscreen-template.h
View File

@ -67,11 +67,11 @@ cogl_onscreen_template_new (CoglSwapChain *swap_chain);
* as "single-sample" rendering. A value of 1 or greater is referred * as "single-sample" rendering. A value of 1 or greater is referred
* to as "multisample" rendering. * to as "multisample" rendering.
* *
* <note>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 * rendering and multisampling with just 1 point sample such as it
* being redundant to use the cogl_framebuffer_resolve_samples() and * being redundant to use the cogl_framebuffer_resolve_samples() and
* cogl_framebuffer_resolve_samples_region() apis with single-sample * cogl_framebuffer_resolve_samples_region() apis with single-sample
* rendering.</note> * rendering.
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_onscreen_template_set_samples_per_pixel ( cogl_onscreen_template_set_samples_per_pixel (

32
cogl/cogl/cogl-onscreen.h
View File

@ -113,11 +113,11 @@ typedef enum _CoglScanoutError
* cogl_onscreen_show() and set its own type directly with the Wayland * cogl_onscreen_show() and set its own type directly with the Wayland
* client API via cogl_wayland_onscreen_get_surface(). * client API via cogl_wayland_onscreen_get_surface().
* *
* <note>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 * onscreen framebuffers it won't try to avoid redundant window system
* requests e.g. to show an already visible window. This also means * requests e.g. to show an already visible window. This also means
* that it's acceptable to alternatively use native APIs to show and * that it's acceptable to alternatively use native APIs to show and
* hide windows without confusing Cogl.</note> * hide windows without confusing Cogl.
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_onscreen_show (CoglOnscreen *onscreen); cogl_onscreen_show (CoglOnscreen *onscreen);
@ -135,11 +135,11 @@ cogl_onscreen_show (CoglOnscreen *onscreen);
* This function does not implicitly allocate the given @onscreen * This function does not implicitly allocate the given @onscreen
* framebuffer before hiding it. * framebuffer before hiding it.
* *
* <note>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 * onscreen framebuffers it won't try to avoid redundant window system
* requests e.g. to show an already visible window. This also means * requests e.g. to show an already visible window. This also means
* that it's acceptable to alternatively use native APIs to show and * that it's acceptable to alternatively use native APIs to show and
* hide windows without confusing Cogl.</note> * hide windows without confusing Cogl.
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_onscreen_hide (CoglOnscreen *onscreen); 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 * start a new frame that incrementally builds on the contents of the previous
* frame. * frame.
* *
* <note>It is highly recommended that applications use * It is highly recommended that applications use
* cogl_onscreen_swap_buffers_with_damage() instead whenever possible * cogl_onscreen_swap_buffers_with_damage() instead whenever possible
* and also use the cogl_onscreen_get_buffer_age() api so they can * and also use the cogl_onscreen_get_buffer_age() api so they can
* perform incremental updates to older buffers instead of having to * perform incremental updates to older buffers instead of having to
* render a full buffer for every frame.</note> * render a full buffer for every frame.
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_onscreen_swap_buffers (CoglOnscreen *onscreen, 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. * The queried value remains valid until the next buffer swap.
* *
* <note>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 * changes to buffer contents caused by the window systems. X11
* applications must track Expose events to determine what buffer * applications must track Expose events to determine what buffer
* regions need to additionally be repaired each frame.</note> * regions need to additionally be repaired each frame.
* *
* The recommended way to take advantage of this buffer age api is to * 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 * 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 * everything that must be redrawn to update the old contents for the
* new frame. * new frame.
* *
* <note>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 * of back buffers then this function will always return 0 which
* implies that the contents are undefined.</note> * implies that the contents are undefined.
* *
* <note>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 * explicitly checked to determine if Cogl is currently tracking the
* age of #CoglOnscreen back buffer contents. If this feature is * age of #CoglOnscreen back buffer contents. If this feature is
* missing then this function will always return 0.</note> * missing then this function will always return 0.
* *
* Return value: The age of the buffer contents or 0 when the buffer * Return value: The age of the buffer contents or 0 when the buffer
* contents are undefined. * contents are undefined.
@ -278,9 +278,9 @@ cogl_onscreen_queue_damage_region (CoglOnscreen *onscreen,
* function instead of cogl_onscreen_swap_buffers() to improve * function instead of cogl_onscreen_swap_buffers() to improve
* performance when running under a compositor. * performance when running under a compositor.
* *
* <note>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 * the cogl_onscreen_get_buffer_age() api so that your application can
* perform incremental rendering based on old back buffers.</note> * perform incremental rendering based on old back buffers.
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_onscreen_swap_buffers_with_damage (CoglOnscreen *onscreen, 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 * opportunity to collect statistics about a frame since the
* #CoglFrameInfo should hold the most data at this point. * #CoglFrameInfo should hold the most data at this point.
* *
* <note>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 * so applications should avoid needing to collect all statistics for
* a particular frame before they can start a new frame.</note> * a particular frame before they can start a new frame.
*/ */
typedef enum _CoglFrameEvent typedef enum _CoglFrameEvent
{ {

116
cogl/cogl/cogl-pipeline-layer-state.h
View File

@ -140,8 +140,8 @@ typedef enum
* explicitly specify the type of default texture required, use * explicitly specify the type of default texture required, use
* cogl_pipeline_set_layer_null_texture() instead. * cogl_pipeline_set_layer_null_texture() instead.
* *
* <note>In the future, we may define other types of pipeline layers, such * In the future, we may define other types of pipeline layers, such
* as purely GLSL based layers.</note> * as purely GLSL based layers.
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_pipeline_set_layer_texture (CoglPipeline *pipeline, cogl_pipeline_set_layer_texture (CoglPipeline *pipeline,
@ -193,88 +193,64 @@ cogl_pipeline_remove_layer (CoglPipeline *pipeline,
* cogl_pipeline_set_layer_combine: * cogl_pipeline_set_layer_combine:
* @pipeline: A #CoglPipeline object * @pipeline: A #CoglPipeline object
* @layer_index: Specifies the layer you want define a combine function for * @layer_index: Specifies the layer you want define a combine function for
* @blend_string: A <link linkend="cogl-Blend-Strings">Cogl blend string</link> * @blend_string: A Cogl blend string describing the desired
* describing the desired texture combine function. * texture combine function.
* @error: A #GError that may report parse errors or lack of GPU/driver * @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 * support. May be %NULL, in which case a warning will be printed out if an
* error is encountered. * error is encountered.
* *
* If not already familiar; you can refer
* <link linkend="cogl-Blend-Strings">here</link> for an overview of what blend
* strings are and there syntax.
* *
* These are all the functions available for texture combining: * These are all the functions available for texture combining:
* <itemizedlist> *
* <listitem>REPLACE(arg0) = arg0</listitem> * - `REPLACE(arg0) = arg0`
* <listitem>MODULATE(arg0, arg1) = arg0 x arg1</listitem> * - `MODULATE(arg0, arg1) = arg0 x arg1`
* <listitem>ADD(arg0, arg1) = arg0 + arg1</listitem> * - `ADD(arg0, arg1) = arg0 + arg1`
* <listitem>ADD_SIGNED(arg0, arg1) = arg0 + arg1 - 0.5</listitem> * - `ADD_SIGNED(arg0, arg1) = arg0 + arg1 - 0.5`
* <listitem>INTERPOLATE(arg0, arg1, arg2) = arg0 x arg2 + arg1 x (1 - arg2)</listitem> * - `INTERPOLATE(arg0, arg1, arg2) = arg0 x arg2 + arg1 x (1 - arg2)`
* <listitem>SUBTRACT(arg0, arg1) = arg0 - arg1</listitem> * - `SUBTRACT(arg0, arg1) = arg0 - arg1`
* <listitem> * -
* <programlisting> * ```
* DOT3_RGB(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) + * DOT3_RGB(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) +
* (arg0[G] - 0.5)) * (arg1[G] - 0.5) + * (arg0[G] - 0.5)) * (arg1[G] - 0.5) +
* (arg0[B] - 0.5)) * (arg1[B] - 0.5)) * (arg0[B] - 0.5)) * (arg1[B] - 0.5))
* </programlisting> * ```
* </listitem> * -
* <listitem> * ```
* <programlisting>
* DOT3_RGBA(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 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[G] - 0.5)) * (arg1[G] - 0.5) +
* (arg0[B] - 0.5)) * (arg1[B] - 0.5)) * (arg0[B] - 0.5)) * (arg1[B] - 0.5))
* </programlisting> * ```
* </listitem>
* </itemizedlist>
* *
* Refer to the * The valid source names for texture combining are:
* <link linkend="cogl-Blend-String-syntax">color-source syntax</link> for *
* describing the arguments. The valid source names for texture combining * - `TEXTURE`: Use the color from the current texture layer
* are: * - `TEXTURE_0, TEXTURE_1, etc`: Use the color from the specified texture layer
* <variablelist> * - `CONSTANT`: Use the color from the constant given with
* <varlistentry> * [method@Cogl.Pipeline.set_layer_combine_constant]
* <term>TEXTURE</term> * - `PRIMARY`: Use the color of the pipeline as set with
* <listitem>Use the color from the current texture layer</listitem> * [method@Cogl.Pipeline.set_color]
* </varlistentry> * - `PREVIOUS`: Either use the texture color from the previous layer, or
* <varlistentry>
* <term>TEXTURE_0, TEXTURE_1, etc</term>
* <listitem>Use the color from the specified texture layer</listitem>
* </varlistentry>
* <varlistentry>
* <term>CONSTANT</term>
* <listitem>Use the color from the constant given with
* cogl_pipeline_set_layer_combine_constant()</listitem>
* </varlistentry>
* <varlistentry>
* <term>PRIMARY</term>
* <listitem>Use the color of the pipeline as set with
* cogl_pipeline_set_color()</listitem>
* </varlistentry>
* <varlistentry>
* <term>PREVIOUS</term>
* <listitem>Either use the texture color from the previous layer, or
* if this is layer 0, use the color of the pipeline as set with * if this is layer 0, use the color of the pipeline as set with
* cogl_pipeline_set_color()</listitem> * [method@Cogl.Pipeline.set_color]
* </varlistentry>
* </variablelist>
* *
* <refsect2 id="cogl-Layer-Combine-Examples"> * Layer Combine Examples:
* <title>Layer Combine Examples</title>
* <para>This is effectively what the default blending is:</para>
* <informalexample><programlisting>
* RGBA = MODULATE (PREVIOUS, TEXTURE)
* </programlisting></informalexample>
* <para>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().</para>
* <informalexample><programlisting>
* RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])
* </programlisting></informalexample>
* </refsect2>
* *
* <note>You can't give a multiplication factor for arguments as you can * This is effectively what the default blending is:
* with blending.</note> *
* ```
* 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])
* ```
*
* 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 * Return value: %TRUE if the blend string was successfully parsed, and the
* described texture combining is supported by the underlying driver and * 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 * Changes the decimation and interpolation filters used when a texture is
* drawn at other scales than 100%. * drawn at other scales than 100%.
* *
* <note>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 * %COGL_PIPELINE_FILTER_NEAREST or %COGL_PIPELINE_FILTER_LINEAR as
* magnification filters since magnification doesn't ever need to * magnification filters since magnification doesn't ever need to
* reference values stored in the mipmap chain.</note> * reference values stored in the mipmap chain.
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_pipeline_set_layer_filters (CoglPipeline *pipeline, cogl_pipeline_set_layer_filters (CoglPipeline *pipeline,

6
cogl/cogl/cogl-pipeline-private.h
View File

@ -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 * To understand this better its good to know a bit about the internal
* design of #CoglPipeline... * design of #CoglPipeline...
* *
* Internally #CoglPipeline<!-- -->s 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 * 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 * applied on top of its parent. Copying a pipeline creates an empty
* diff and a child->parent relationship between the empty diff and * 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 * This is the recommended coding pattern for validating an input
* pipeline and caching a derived result: * pipeline and caching a derived result:
* |[ * ```c
* static GQuark _cogl_my_cache_key = 0; * static GQuark _cogl_my_cache_key = 0;
* *
* typedef struct { * typedef struct {
@ -673,7 +673,7 @@ _cogl_get_n_args_for_combine_func (CoglPipelineCombineFunc func);
* *
* return cache->validated_source; * return cache->validated_source;
* } * }
* ]| * ```
*/ */
CoglPipeline * CoglPipeline *
_cogl_pipeline_weak_copy (CoglPipeline *pipeline, _cogl_pipeline_weak_copy (CoglPipeline *pipeline,

66
cogl/cogl/cogl-pipeline-state.h
View File

@ -184,7 +184,7 @@ cogl_pipeline_get_alpha_test_reference (CoglPipeline *pipeline);
/** /**
* cogl_pipeline_set_blend: * cogl_pipeline_set_blend:
* @pipeline: A #CoglPipeline object * @pipeline: A #CoglPipeline object
* @blend_string: A <link linkend="cogl-Blend-Strings">Cogl blend string</link> * @blend_string: A Cogl blend string
* describing the desired blend function. * describing the desired blend function.
* @error: return location for a #GError that may report lack of driver * @error: return location for a #GError that may report lack of driver
* support if you give separate blend string statements for the alpha * 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 * warning will be printed out using GLib's logging facilities if an
* error is encountered. * error is encountered.
* *
* If not already familiar; please refer <link linkend="cogl-Blend-Strings">here</link>
* for an overview of what blend strings are, and their syntax.
*
* Blending occurs after the alpha test function, and combines fragments with * Blending occurs after the alpha test function, and combines fragments with
* the framebuffer. * the framebuffer.
* Currently the only blend function Cogl exposes is ADD(). So any valid * Currently the only blend function Cogl exposes is ADD(). So any valid
* blend statements will be of the form: * blend statements will be of the form:
* *
* |[ * ```
* &lt;channel-mask&gt;=ADD(SRC_COLOR*(&lt;factor&gt;), DST_COLOR*(&lt;factor&gt;)) * &lt;channel-mask&gt;=ADD(SRC_COLOR*(&lt;factor&gt;), DST_COLOR*(&lt;factor&gt;))
* ]| * ```
* *
* This is the list of source-names usable as blend factors: * This is the list of source-names usable as blend factors:
* <itemizedlist>
* <listitem><para>SRC_COLOR: The color of the incoming fragment</para></listitem>
* <listitem><para>DST_COLOR: The color of the framebuffer</para></listitem>
* <listitem><para>CONSTANT: The constant set via cogl_pipeline_set_blend_constant()</para></listitem>
* </itemizedlist>
* *
* The source names can be used according to the * - `SRC_COLOR`: The color of the incoming fragment
* <link linkend="cogl-Blend-String-syntax">color-source and factor syntax</link>, * - `DST_COLOR`: The color of the framebuffer
* so for example "(1-SRC_COLOR[A])" would be a valid factor, as would * - `CONSTANT`: The constant set via cogl_pipeline_set_blend_constant()
* "(CONSTANT[RGB])"
* *
* These can also be used as factors: * These can also be used as factors:
* <itemizedlist>
* <listitem>0: (0, 0, 0, 0)</listitem>
* <listitem>1: (1, 1, 1, 1)</listitem>
* <listitem>SRC_ALPHA_SATURATE_FACTOR: (f,f,f,1) where f = MIN(SRC_COLOR[A],1-DST_COLOR[A])</listitem>
* </itemizedlist>
* *
* <note>Remember; all color components are normalized to the range [0, 1] * - `0`: (0, 0, 0, 0)
* before computing the result of blending.</note> * - `1`: (1, 1, 1, 1)
* - `SRC_ALPHA_SATURATE_FACTOR`: (f,f,f,1) where `f = MIN(SRC_COLOR[A],1-DST_COLOR[A])`
* *
* <example id="cogl-Blend-Strings-blend-unpremul"> * Remember; all color components are normalized to the range [0, 1]
* <title>Blend Strings/1</title> * before computing the result of blending.
* <para>Blend a non-premultiplied source over a destination with *
* premultiplied alpha:</para> * - Blend Strings/1:
* <programlisting> * Blend a non-premultiplied source over a destination with
* premultiplied alpha:
* ```
* "RGB = ADD(SRC_COLOR*(SRC_COLOR[A]), DST_COLOR*(1-SRC_COLOR[A]))" * "RGB = ADD(SRC_COLOR*(SRC_COLOR[A]), DST_COLOR*(1-SRC_COLOR[A]))"
* "A = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))" * "A = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
* </programlisting> * ```
* </example>
* *
* <example id="cogl-Blend-Strings-blend-premul"> * Blend Strings/2:
* <title>Blend Strings/2</title> * Blend a premultiplied source over a destination with
* <para>Blend a premultiplied source over a destination with * premultiplied alpha
* premultiplied alpha</para> * ```
* <programlisting>
* "RGBA = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))" * "RGBA = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
* </programlisting> * ```
* </example>
* *
* The default blend string is: * The default blend string is:
* |[ * ```
* RGBA = ADD (SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A])) * RGBA = ADD (SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))
* ]| * ```
* *
* That gives normal alpha-blending when the calculated color for the pipeline * That gives normal alpha-blending when the calculated color for the pipeline
* is in premultiplied form. * 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 * This is an example of how it can be used to associate an ARBfp
* program with a #CoglPipeline: * program with a #CoglPipeline:
* |[ * ```c
* CoglShader *shader; * CoglShader *shader;
* CoglProgram *program; * CoglProgram *program;
* CoglPipeline *pipeline; * CoglPipeline *pipeline;
@ -386,7 +372,7 @@ cogl_pipeline_get_user_program (CoglPipeline *pipeline);
* *
* cogl_set_source_color4ub (0xff, 0x00, 0x00, 0xff); * cogl_set_source_color4ub (0xff, 0x00, 0x00, 0xff);
* cogl_rectangle (0, 0, 100, 100); * cogl_rectangle (0, 0, 100, 100);
* ]| * ```
* *
* It is possibly worth keeping in mind that this API is not part of * 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 * the long term design for how we want to expose shaders to Cogl

18
cogl/cogl/cogl-poll.h
View File

@ -97,9 +97,9 @@ typedef enum
* *
* A struct for describing the state of a file descriptor that Cogl * A struct for describing the state of a file descriptor that Cogl
* needs to block on. The @events field contains a bitmask of * needs to block on. The @events field contains a bitmask of
* #CoglPollFDEvent<!-- -->s 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 * up. After the application is woken up from idle it should pass back
* an array of #CoglPollFD<!-- -->s 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. * mask to the actual events that occurred on the file descriptor.
* *
* Note that CoglPollFD is deliberately exactly the same as struct * Note that CoglPollFD is deliberately exactly the same as struct
@ -115,7 +115,7 @@ typedef struct {
* cogl_poll_renderer_get_info: * cogl_poll_renderer_get_info:
* @renderer: A #CoglRenderer * @renderer: A #CoglRenderer
* @poll_fds: A return location for a pointer to an array * @poll_fds: A return location for a pointer to an array
* of #CoglPollFD<!-- -->s * of `CoglPollFD`s
* @n_poll_fds: A return location for the number of entries in *@poll_fds * @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 * @timeout: A return location for the maximum length of time to wait
* in microseconds, or -1 to wait indefinitely. * 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 * that Cogl has a chance to describe what file descriptor events it
* needs to be woken up for. * needs to be woken up for.
* *
* <note>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 * should jump to the cogl_glib_source_new() api as a more convenient
* way of integrating Cogl with the mainloop.</note> * way of integrating Cogl with the mainloop.
* *
* After the function is called *@poll_fds will contain a pointer to * After the function is called *@poll_fds will contain a pointer to
* an array of #CoglPollFD structs describing the file descriptors * 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 * When the application mainloop returns from calling poll(2) (or its
* equivalent) then it should call cogl_poll_renderer_dispatch() * equivalent) then it should call cogl_poll_renderer_dispatch()
* passing a pointer the array of CoglPollFD<!-- -->s with updated * passing a pointer the array of `CoglPollFD`s with updated
* revent values. * revent values.
* *
* @timeout will contain a maximum amount of time to wait in * @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: * cogl_poll_renderer_dispatch:
* @renderer: A #CoglRenderer * @renderer: A #CoglRenderer
* @poll_fds: An array of #CoglPollFD<!-- -->s describing the events * @poll_fds: An array of `CoglPollFD`s describing the events
* that have occurred since the application went idle. * that have occurred since the application went idle.
* @n_poll_fds: The length of the @poll_fds array. * @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 * file descriptors that Cogl didn't request when calling
* cogl_poll_renderer_get_info() or a shorter array missing some file * cogl_poll_renderer_get_info() or a shorter array missing some file
* descriptors that Cogl requested. * descriptors that Cogl requested.
*
* <note>If your application didn't originally create a #CoglRenderer
* manually then you can easily get a #CoglRenderer pointer by calling
* cogl_get_renderer().</note>
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_poll_renderer_dispatch (CoglRenderer *renderer, cogl_poll_renderer_dispatch (CoglRenderer *renderer,

114
cogl/cogl/cogl-primitive.h
View File

@ -203,12 +203,12 @@ typedef struct {
* @n_vertices: The number of vertices to process when drawing * @n_vertices: The number of vertices to process when drawing
* @...: A %NULL terminated list of attributes * @...: A %NULL terminated list of attributes
* *
* Combines a set of #CoglAttribute<!-- -->s 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 * and defines a vertex count so a #CoglPrimitive object can be retained and
* drawn later with no addition information required. * drawn later with no addition information required.
* *
* The value passed as @n_vertices will simply update the * The value passed as @n_vertices will simply update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines * cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing. * the number of vertices to read when drawing.
* *
@ -226,12 +226,12 @@ cogl_primitive_new (CoglVerticesMode mode,
* @attributes: An array of CoglAttribute * @attributes: An array of CoglAttribute
* @n_attributes: The number of attributes * @n_attributes: The number of attributes
* *
* Combines a set of #CoglAttribute<!-- -->s 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 * and defines a vertex count so a #CoglPrimitive object can be retained and
* drawn later with no addition information required. * drawn later with no addition information required.
* *
* The value passed as @n_vertices will simply update the * The value passed as @n_vertices will simply update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines * cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing. * 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. * attribute with a #CoglAttribute and upload your data.
* *
* For example to draw a convex polygon you can do: * For example to draw a convex polygon you can do:
* |[ * ```c
* CoglVertexP2 triangle[] = * CoglVertexP2 triangle[] =
* { * {
* { 0, 300 }, * { 0, 300 },
@ -268,21 +268,21 @@ cogl_primitive_new_with_attributes (CoglVerticesMode mode,
* prim = cogl_primitive_new_p2 (COGL_VERTICES_MODE_TRIANGLE_FAN, * prim = cogl_primitive_new_p2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle); * 3, triangle);
* cogl_primitive_draw (prim); * cogl_primitive_draw (prim);
* ]| * ```
* *
* The value passed as @n_vertices is initially used to determine how * 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 * much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines * cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing. * the number of vertices to read when drawing.
* <note>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 * textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your * so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you * 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 * 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) * resized to a power-of-two size (though they don't have to be square)
* </note> *
* *
* Return value: (transfer full): A newly allocated #CoglPrimitive * Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref(). * 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. * attribute with a #CoglAttribute and upload your data.
* *
* For example to draw a convex polygon you can do: * For example to draw a convex polygon you can do:
* |[ * ```c
* CoglVertexP3 triangle[] = * CoglVertexP3 triangle[] =
* { * {
* { 0, 300, 0 }, * { 0, 300, 0 },
@ -318,21 +318,21 @@ cogl_primitive_new_p2 (CoglContext *context,
* prim = cogl_primitive_new_p3 (COGL_VERTICES_MODE_TRIANGLE_FAN, * prim = cogl_primitive_new_p3 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle); * 3, triangle);
* cogl_primitive_draw (prim); * cogl_primitive_draw (prim);
* ]| * ```
* *
* The value passed as @n_vertices is initially used to determine how * 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 * much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines * cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing. * the number of vertices to read when drawing.
* <note>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 * textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your * so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you * 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 * 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) * resized to a power-of-two size (though they don't have to be square)
* </note> *
* *
* Return value: (transfer full): A newly allocated #CoglPrimitive * Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref(). * 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 * Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the * triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position * necessary #CoglAttributeBuffer storage, describe the position
* and color attributes with #CoglAttribute<!-- -->s and upload * and color attributes with `CoglAttribute`s and upload
* your data. * your data.
* *
* For example to draw a convex polygon with a linear gradient you * For example to draw a convex polygon with a linear gradient you
* can do: * can do:
* |[ * ```c
* CoglVertexP2C4 triangle[] = * CoglVertexP2C4 triangle[] =
* { * {
* { 0, 300, 0xff, 0x00, 0x00, 0xff }, * { 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, * prim = cogl_primitive_new_p2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle); * 3, triangle);
* cogl_primitive_draw (prim); * cogl_primitive_draw (prim);
* ]| * ```
* *
* The value passed as @n_vertices is initially used to determine how * 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 * much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines * cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing. * the number of vertices to read when drawing.
* <note>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 * textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your * so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you * 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 * 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) * resized to a power-of-two size (though they don't have to be square)
* </note> *
* *
* Return value: (transfer full): A newly allocated #CoglPrimitive * Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref(). * 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 * Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the * triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position * necessary #CoglAttributeBuffer storage, describe the position
* and color attributes with #CoglAttribute<!-- -->s and upload * and color attributes with `CoglAttribute`s and upload
* your data. * your data.
* *
* For example to draw a convex polygon with a linear gradient you * For example to draw a convex polygon with a linear gradient you
* can do: * can do:
* |[ * ```c
* CoglVertexP3C4 triangle[] = * CoglVertexP3C4 triangle[] =
* { * {
* { 0, 300, 0, 0xff, 0x00, 0x00, 0xff }, * { 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, * prim = cogl_primitive_new_p3c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle); * 3, triangle);
* cogl_primitive_draw (prim); * cogl_primitive_draw (prim);
* ]| * ```
* *
* The value passed as @n_vertices is initially used to determine how * 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 * much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines * cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing. * the number of vertices to read when drawing.
* <note>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 * textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your * so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you * 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 * 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) * resized to a power-of-two size (though they don't have to be square)
* </note> *
* *
* Return value: (transfer full): A newly allocated #CoglPrimitive * Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref(). * 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 * Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the * triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position and * necessary #CoglAttributeBuffer storage, describe the position and
* texture coordinate attributes with #CoglAttribute<!-- -->s and * texture coordinate attributes with `CoglAttribute`s and
* upload your data. * upload your data.
* *
* For example to draw a convex polygon with texture mapping you can * For example to draw a convex polygon with texture mapping you can
* do: * do:
* |[ * ```c
* CoglVertexP2T2 triangle[] = * CoglVertexP2T2 triangle[] =
* { * {
* { 0, 300, 0.0, 1.0}, * { 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, * prim = cogl_primitive_new_p2t2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle); * 3, triangle);
* cogl_primitive_draw (prim); * cogl_primitive_draw (prim);
* ]| * ```
* *
* The value passed as @n_vertices is initially used to determine how * 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 * much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines * cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing. * the number of vertices to read when drawing.
* <note>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 * textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your * so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you * 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 * 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) * resized to a power-of-two size (though they don't have to be square)
* </note> *
* *
* Return value: (transfer full): A newly allocated #CoglPrimitive * Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref(). * 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 * Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the * triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position and * necessary #CoglAttributeBuffer storage, describe the position and
* texture coordinate attributes with #CoglAttribute<!-- -->s and * texture coordinate attributes with `CoglAttribute`s and
* upload your data. * upload your data.
* *
* For example to draw a convex polygon with texture mapping you can * For example to draw a convex polygon with texture mapping you can
* do: * do:
* |[ * ```c
* CoglVertexP3T2 triangle[] = * CoglVertexP3T2 triangle[] =
* { * {
* { 0, 300, 0, 0.0, 1.0}, * { 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, * prim = cogl_primitive_new_p3t2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle); * 3, triangle);
* cogl_primitive_draw (prim); * cogl_primitive_draw (prim);
* ]| * ```
* *
* The value passed as @n_vertices is initially used to determine how * 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 * much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines * cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing. * the number of vertices to read when drawing.
* <note>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 * textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your * so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you * 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 * 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) * resized to a power-of-two size (though they don't have to be square)
* </note> *
* *
* Return value: (transfer full): A newly allocated #CoglPrimitive * Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref(). * 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 * Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the * triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position, texture * necessary #CoglAttributeBuffer storage, describe the position, texture
* coordinate and color attributes with #CoglAttribute<!-- -->s and * coordinate and color attributes with `CoglAttribute`s and
* upload your data. * upload your data.
* *
* For example to draw a convex polygon with texture mapping and a * For example to draw a convex polygon with texture mapping and a
* linear gradient you can do: * linear gradient you can do:
* |[ * ```c
* CoglVertexP2T2C4 triangle[] = * CoglVertexP2T2C4 triangle[] =
* { * {
* { 0, 300, 0.0, 1.0, 0xff, 0x00, 0x00, 0xff}, * { 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, * prim = cogl_primitive_new_p2t2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle); * 3, triangle);
* cogl_primitive_draw (prim); * cogl_primitive_draw (prim);
* ]| * ```
* *
* The value passed as @n_vertices is initially used to determine how * 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 * much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines * cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing. * the number of vertices to read when drawing.
* <note>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 * textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your * so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you * 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 * 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) * resized to a power-of-two size (though they don't have to be square)
* </note> *
* *
* Return value: (transfer full): A newly allocated #CoglPrimitive * Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref(). * 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 * Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the * triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position, texture * necessary #CoglAttributeBuffer storage, describe the position, texture
* coordinate and color attributes with #CoglAttribute<!-- -->s and * coordinate and color attributes with `CoglAttribute`s and
* upload your data. * upload your data.
* *
* For example to draw a convex polygon with texture mapping and a * For example to draw a convex polygon with texture mapping and a
* linear gradient you can do: * linear gradient you can do:
* |[ * ```c
* CoglVertexP3T2C4 triangle[] = * CoglVertexP3T2C4 triangle[] =
* { * {
* { 0, 300, 0, 0.0, 1.0, 0xff, 0x00, 0x00, 0xff}, * { 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, * prim = cogl_primitive_new_p3t2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle); * 3, triangle);
* cogl_primitive_draw (prim); * cogl_primitive_draw (prim);
* ]| * ```
* *
* The value passed as @n_vertices is initially used to determine how * 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 * much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines * cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing. * the number of vertices to read when drawing.
* <note>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 * textures (since switching between slices implies changing state and
* so that implies multiple primitives need to be submitted). If your * so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you * 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 * 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) * resized to a power-of-two size (though they don't have to be square)
* </note> *
* *
* Return value: (transfer full): A newly allocated #CoglPrimitive * Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref(). * 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 * number of vertices to read can also be phrased as the number
* of indices to read. * of indices to read.
* *
* <note>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 * terms of data - associated with the primitive it's just the number
* of vertices to read and draw.</note> * of vertices to read and draw.
* *
* Returns: The number of vertices to read when drawing. * 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 * Usually this value is set implicitly when associating vertex data
* or indices with a #CoglPrimitive. * or indices with a #CoglPrimitive.
* *
* <note>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 * terms of data - associated with the primitive it's just the number
* of vertices to read and draw.</note> * of vertices to read and draw.
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_primitive_set_n_vertices (CoglPrimitive *primitive, 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. * shared data multiple times instead of duplicating the data.
* *
* The value passed as @n_indices will simply update the * The value passed as @n_indices will simply update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if * #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines * cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to draw or, put another way, how many * the number of vertices to draw or, put another way, how many
* indices should be read from @indices when drawing. * indices should be read from @indices when drawing.
* *
* <note>The #CoglPrimitive <structfield>first_vertex</structfield> property * The #CoglPrimitive `first_vertex` property
* also affects drawing with indices by defining the first entry of the * also affects drawing with indices by defining the first entry of the
* indices to start drawing from.</note> * indices to start drawing from.
*/ */
COGL_EXPORT void COGL_EXPORT void
cogl_primitive_set_indices (CoglPrimitive *primitive, cogl_primitive_set_indices (CoglPrimitive *primitive,

12
cogl/cogl/cogl-renderer.h
View File

@ -65,12 +65,6 @@ G_BEGIN_DECLS
* *
* Once you have a configured #CoglRenderer it can be used to create a * Once you have a configured #CoglRenderer it can be used to create a
* #CoglDisplay object using cogl_display_new(). * #CoglDisplay object using cogl_display_new().
*
* <note>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.</note>
*/ */
@ -125,12 +119,6 @@ G_DECLARE_FINAL_TYPE (CoglRenderer,
* Once you have setup your renderer then the next step is to create a * Once you have setup your renderer then the next step is to create a
* #CoglDisplay using cogl_display_new(). * #CoglDisplay using cogl_display_new().
* *
* <note>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.</note>
*
* Return value: (transfer full): A newly created #CoglRenderer. * Return value: (transfer full): A newly created #CoglRenderer.
*/ */
COGL_EXPORT CoglRenderer * COGL_EXPORT CoglRenderer *

352
cogl/cogl/cogl-snippet.h
View File

@ -44,7 +44,7 @@ G_BEGIN_DECLS
* *
* Functions for creating and manipulating shader snippets * Functions for creating and manipulating shader snippets
* *
* #CoglSnippet<!-- -->s 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 * #CoglPipeline using GLSL. GLSL is a programming language supported
* by OpenGL on programmable hardware to provide a more flexible * by OpenGL on programmable hardware to provide a more flexible
* description of what should be rendered. A description of GLSL * 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 * the pipeline at a particular point. The code is split into four
* separate strings (all of which are optional): * separate strings (all of which are optional):
* *
* <glosslist> * - `declarations`
* <glossentry>
* <glossterm>declarations</glossterm>
* <glossdef><para>
* The code in this string will be inserted outside of any function in * 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 * the global scope of the shader. This can be used to declare
* uniforms, attributes, varyings and functions to be used by the * uniforms, attributes, varyings and functions to be used by the
* snippet. * snippet.
* </para></glossdef> * - `pre`
* </glossentry>
* <glossentry>
* <glossterm>pre</glossterm>
* <glossdef><para>
* The code in this string will be inserted before the hook point. * The code in this string will be inserted before the hook point.
* </para></glossdef> * - `post`
* </glossentry>
* <glossentry>
* <glossterm>post</glossterm>
* <glossdef><para>
* The code in this string will be inserted after the hook point. This * 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 * can be used to modify the results of the builtin generated code for
* that hook point. * that hook point.
* </para></glossdef> * - `replace
* </glossentry>
* <glossentry>
* <glossterm>replace</glossterm>
* <glossdef><para>
* If present the code in this string will replace the generated code * If present the code in this string will replace the generated code
* for the hook point. * for the hook point.
* </para></glossdef>
* </glossentry>
* </glosslist>
* *
* All of the strings apart from the declarations string of a pipeline * All of the strings apart from the declarations string of a pipeline
* are generated in a single function so they can share variables * 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 * names under the cogl_* namespace which can be used instead. These
* are: * are:
* *
* <glosslist> * - `uniform mat4 cogl_modelview_matrix
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_modelview_matrix</emphasis></glossterm>
* <glossdef><para>
* The current modelview matrix. This is equivalent to * The current modelview matrix. This is equivalent to
* #gl_ModelViewMatrix. * #gl_ModelViewMatrix.
* </para></glossdef> * - `uniform mat4 cogl_projection_matrix
* </glossentry>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_projection_matrix</emphasis></glossterm>
* <glossdef><para>
* The current projection matrix. This is equivalent to * The current projection matrix. This is equivalent to
* #gl_ProjectionMatrix. * #gl_ProjectionMatrix.
* </para></glossdef> * - `uniform mat4 cogl_modelview_projection_matrix
* </glossentry>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_modelview_projection_matrix</emphasis></glossterm>
* <glossdef><para>
* The combined modelview and projection matrix. A vertex shader * The combined modelview and projection matrix. A vertex shader
* would typically use this to transform the incoming vertex * would typically use this to transform the incoming vertex
* position. The separate modelview and projection matrices are * position. The separate modelview and projection matrices are
* usually only needed for lighting calculations. This is * usually only needed for lighting calculations. This is
* equivalent to #gl_ModelViewProjectionMatrix. * equivalent to #gl_ModelViewProjectionMatrix.
* </para></glossdef> * - `uniform mat4 cogl_texture_matrix[]
* </glossentry>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_texture_matrix</emphasis>[]</glossterm>
* <glossdef><para>
* An array of matrices for transforming the texture * An array of matrices for transforming the texture
* coordinates. This is equivalent to #gl_TextureMatrix. * coordinates. This is equivalent to #gl_TextureMatrix.
* </para></glossdef>
* </glossentry>
* </glosslist>
* *
* In a vertex shader, the following are also available: * In a vertex shader, the following are also available:
* *
* <glosslist> * - `attribute vec4 cogl_position_in
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_position_in</emphasis></glossterm>
* <glossdef><para>
* The incoming vertex position. This is equivalent to #gl_Vertex. * The incoming vertex position. This is equivalent to #gl_Vertex.
* </para></glossdef> * - `attribute vec4 cogl_color_in`
* </glossentry>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_color_in</emphasis></glossterm>
* <glossdef><para>
* The incoming vertex color. This is equivalent to #gl_Color. * The incoming vertex color. This is equivalent to #gl_Color.
* </para></glossdef> * - `attribute vec4 cogl_tex_coord_in`
* </glossentry>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_tex_coord_in</emphasis></glossterm>
* <glossdef><para>
* The texture coordinate for layer 0. This is an alternative name * The texture coordinate for layer 0. This is an alternative name
* for #cogl_tex_coord0_in. * for #cogl_tex_coord0_in.
* </para></glossdef> * - `attribute vec4 cogl_tex_coord0_in
* </glossentry>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_tex_coord0_in</emphasis></glossterm>
* <glossdef><para>
* The texture coordinate for the layer 0. This is equivalent to * The texture coordinate for the layer 0. This is equivalent to
* #gl_MultiTexCoord0. There will also be #cogl_tex_coord1_in and * #gl_MultiTexCoord0. There will also be #cogl_tex_coord1_in and
* so on if more layers are added to the pipeline. * so on if more layers are added to the pipeline.
* </para></glossdef> * - `attribute vec3 cogl_normal_in`
* </glossentry>
* <glossentry>
* <glossterm>attribute vec3
* <emphasis>cogl_normal_in</emphasis></glossterm>
* <glossdef><para>
* The normal of the vertex. This is equivalent to #gl_Normal. * The normal of the vertex. This is equivalent to #gl_Normal.
* </para></glossdef> * - `vec4 cogl_position_out
* </glossentry>
* <glossentry>
* <glossterm>vec4
* <emphasis>cogl_position_out</emphasis></glossterm>
* <glossdef><para>
* The calculated position of the vertex. This must be written to * The calculated position of the vertex. This must be written to
* in all vertex shaders. This is equivalent to #gl_Position. * in all vertex shaders. This is equivalent to #gl_Position.
* </para></glossdef> * - `float cogl_point_size_in
* </glossentry>
* <glossentry>
* <glossterm>float
* <emphasis>cogl_point_size_in</emphasis></glossterm>
* <glossdef><para>
* The incoming point size from the cogl_point_size_in attribute. * The incoming point size from the cogl_point_size_in attribute.
* This is only available if * This is only available if
* cogl_pipeline_set_per_vertex_point_size() is set on the * cogl_pipeline_set_per_vertex_point_size() is set on the
* pipeline. * pipeline.
* </para></glossdef> * - `float cogl_point_size_out`
* </glossentry>
* <glossentry>
* <glossterm>float
* <emphasis>cogl_point_size_out</emphasis></glossterm>
* <glossdef><para>
* The calculated size of a point. This is equivalent to #gl_PointSize. * The calculated size of a point. This is equivalent to #gl_PointSize.
* </para></glossdef> * - `varying vec4 cogl_color_out`
* </glossentry>
* <glossentry>
* <glossterm>varying vec4
* <emphasis>cogl_color_out</emphasis></glossterm>
* <glossdef><para>
* The calculated color of a vertex. This is equivalent to #gl_FrontColor. * The calculated color of a vertex. This is equivalent to #gl_FrontColor.
* </para></glossdef> * - `varying vec4 cogl_tex_coord0_out`
* </glossentry>
* <glossentry>
* <glossterm>varying vec4
* <emphasis>cogl_tex_coord0_out</emphasis></glossterm>
* <glossdef><para>
* The calculated texture coordinate for layer 0 of the pipeline. * The calculated texture coordinate for layer 0 of the pipeline.
* This is equivalent to #gl_TexCoord[0]. There will also be * 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 * #cogl_tex_coord1_out and so on if more layers are added to the
* pipeline. In the fragment shader, this varying is called * pipeline. In the fragment shader, this varying is called
* #cogl_tex_coord0_in. * #cogl_tex_coord0_in.
* </para></glossdef>
* </glossentry>
* </glosslist>
* *
* In a fragment shader, the following are also available: * In a fragment shader, the following are also available:
* *
* <glosslist> * - `varying vec4 cogl_color_in`
* <glossentry>
* <glossterm>varying vec4 <emphasis>cogl_color_in</emphasis></glossterm>
* <glossdef><para>
* The calculated color of a vertex. This is equivalent to #gl_FrontColor. * The calculated color of a vertex. This is equivalent to #gl_FrontColor.
* </para></glossdef> * - `varying vec4 cogl_tex_coord0_in`
* </glossentry>
* <glossentry>
* <glossterm>varying vec4
* <emphasis>cogl_tex_coord0_in</emphasis></glossterm>
* <glossdef><para>
* The texture coordinate for layer 0. This is equivalent to * The texture coordinate for layer 0. This is equivalent to
* #gl_TexCoord[0]. There will also be #cogl_tex_coord1_in and so * #gl_TexCoord[0]. There will also be #cogl_tex_coord1_in and so
* on if more layers are added to the pipeline. * on if more layers are added to the pipeline.
* </para></glossdef> * - `vec4 cogl_color_out`
* </glossentry>
* <glossentry>
* <glossterm>vec4 <emphasis>cogl_color_out</emphasis></glossterm>
* <glossdef><para>
* The final calculated color of the fragment. All fragment shaders * The final calculated color of the fragment. All fragment shaders
* must write to this variable. This is equivalent to * must write to this variable. This is equivalent to
* #gl_FrontColor. * #gl_FrontColor.
* </para></glossdef> * - `float cogl_depth_out`
* </glossentry>
* <glossentry>
* <glossterm>float <emphasis>cogl_depth_out</emphasis></glossterm>
* <glossdef><para>
* An optional output variable specifying the depth value to use * An optional output variable specifying the depth value to use
* for this fragment. This is equivalent to #gl_FragDepth. * for this fragment. This is equivalent to #gl_FragDepth.
* </para></glossdef> * - `bool cogl_front_facing`
* </glossentry>
* <glossentry>
* <glossterm>bool <emphasis>cogl_front_facing</emphasis></glossterm>
* <glossdef><para>
* A readonly variable that will be true if the current primitive * A readonly variable that will be true if the current primitive
* is front facing. This can be used to implement two-sided * is front facing. This can be used to implement two-sided
* coloring algorithms. This is equivalent to #gl_FrontFacing. * coloring algorithms. This is equivalent to #gl_FrontFacing.
* </para></glossdef> * - `vec2 cogl_point_coord`
* </glossentry>
* <glossentry>
* <glossterm>vec2 <emphasis>cogl_point_coord</emphasis></glossterm>
* <glossdef><para>
* When rendering points, this will contain a vec2 which represents * When rendering points, this will contain a vec2 which represents
* the position within the point of the current fragment. * 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) * 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 * Cogl where when rendering to an offscreen buffer these
* coordinates will be upside-down. The value is undefined when not * coordinates will be upside-down. The value is undefined when not
* rendering points. * rendering points.
* </para></glossdef>
* </glossentry>
* </glosslist>
* *
* Here is an example of using a snippet to add a desaturate effect to the * Here is an example of using a snippet to add a desaturate effect to the
* generated color on a pipeline. * 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 * #CoglPipeline where the code of the snippet should be used when it
* is attached to a pipeline. * is attached to a pipeline.
* *
* <glosslist> * - `COGL_SNIPPET_HOOK_VERTEX_GLOBALS`
* <glossentry> *
* <glossterm>%COGL_SNIPPET_HOOK_VERTEX_GLOBALS</glossterm>
* <glossdef>
* <para>
* Adds a shader snippet at the beginning of the global section of the * Adds a shader snippet at the beginning of the global section of the
* shader for the vertex processing. Any declarations here can be * shader for the vertex processing. Any declarations here can be
* shared with all other snippets that are attached to a vertex hook. * shared with all other snippets that are attached to a vertex hook.
* Only the ‘declarations’ string is used and the other strings are * Only the ‘declarations’ string is used and the other strings are
* ignored. * ignored.
* </para> *
* </glossdef> * - `COGL_SNIPPET_HOOK_FRAGMENT_GLOBALS`
* </glossentry> *
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_FRAGMENT_GLOBALS</glossterm>
* <glossdef>
* <para>
* Adds a shader snippet at the beginning of the global section of the * Adds a shader snippet at the beginning of the global section of the
* shader for the fragment processing. Any declarations here can be * shader for the fragment processing. Any declarations here can be
* shared with all other snippets that are attached to a fragment * shared with all other snippets that are attached to a fragment
* hook. Only the ‘declarations’ string is used and the other strings * hook. Only the ‘declarations’ string is used and the other strings
* are ignored. * are ignored.
* </para> *
* </glossdef> * - `COGL_SNIPPET_HOOK_VERTEX`
* </glossentry> *
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_VERTEX</glossterm>
* <glossdef>
* <para>
* Adds a shader snippet that will hook on to the vertex processing * Adds a shader snippet that will hook on to the vertex processing
* stage of the pipeline. This gives a chance for the application to * stage of the pipeline. This gives a chance for the application to
* modify the vertex attributes generated by the shader. Typically the * modify the vertex attributes generated by the shader. Typically the
* snippet will modify cogl_color_out or cogl_position_out builtins. * snippet will modify cogl_color_out or cogl_position_out builtins.
* </para> *
* <para>
* The ‘declarations’ string in @snippet will be inserted in the * The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms, * global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires. * attributes or functions that the snippet requires.
* </para> *
* <para>
* The ‘pre’ string in @snippet will be inserted at the top of the * The ‘pre’ string in @snippet will be inserted at the top of the
* main() function before any vertex processing is done. * main() function before any vertex processing is done.
* </para> *
* <para>
* The ‘replace’ string in @snippet will be used instead of the * The ‘replace’ string in @snippet will be used instead of the
* generated vertex processing if it is present. This can be used if * generated vertex processing if it is present. This can be used if
* the application wants to provide a complete vertex shader and * the application wants to provide a complete vertex shader and
* doesn't need the generated output from Cogl. * doesn't need the generated output from Cogl.
* </para> *
* <para>
* The ‘post’ string in @snippet will be inserted after all of the * The ‘post’ string in @snippet will be inserted after all of the
* standard vertex processing is done. This can be used to modify the * standard vertex processing is done. This can be used to modify the
* outputs. * outputs.
* </para> *
* </glossdef> * - `COGL_SNIPPET_HOOK_VERTEX_TRANSFORM`
* </glossentry> *
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_VERTEX_TRANSFORM</glossterm>
* <glossdef>
* <para>
* Adds a shader snippet that will hook on to the vertex transform stage. * Adds a shader snippet that will hook on to the vertex transform stage.
* Typically the snippet will use the cogl_modelview_matrix, * Typically the snippet will use the cogl_modelview_matrix,
* cogl_projection_matrix and cogl_modelview_projection_matrix matrices and the * cogl_projection_matrix and cogl_modelview_projection_matrix matrices and the
* cogl_position_in attribute. The hook must write to cogl_position_out. * 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 default processing for this hook will multiply cogl_position_in by
* the combined modelview-projection matrix and store it on cogl_position_out. * the combined modelview-projection matrix and store it on cogl_position_out.
* </para> *
* <para>
* The ‘declarations’ string in @snippet will be inserted in the * The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms, * global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires. * attributes or functions that the snippet requires.
* </para> *
* <para>
* The ‘pre’ string in @snippet will be inserted at the top of the * The ‘pre’ string in @snippet will be inserted at the top of the
* main() function before the vertex transform is done. * main() function before the vertex transform is done.
* </para> *
* <para>
* The ‘replace’ string in @snippet will be used instead of the * The ‘replace’ string in @snippet will be used instead of the
* generated vertex transform if it is present. * generated vertex transform if it is present.
* </para> *
* <para>
* The ‘post’ string in @snippet will be inserted after all of the * The ‘post’ string in @snippet will be inserted after all of the
* standard vertex transformation is done. This can be used to modify the * standard vertex transformation is done. This can be used to modify the
* cogl_position_out in addition to the default processing. * cogl_position_out in addition to the default processing.
* </para> *
* </glossdef> * - `COGL_SNIPPET_HOOK_POINT_SIZE`
* </glossentry> *
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_POINT_SIZE</glossterm>
* <glossdef>
* <para>
* Adds a shader snippet that will hook on to the point size * Adds a shader snippet that will hook on to the point size
* calculation step within the vertex shader stage. The snippet should * calculation step within the vertex shader stage. The snippet should
* write to the builtin cogl_point_size_out with the new point size. * 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 * 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 * only used if cogl_pipeline_set_per_vertex_point_size() is enabled
* on the pipeline. * on the pipeline.
* </para> *
* <para>
* The ‘declarations’ string in @snippet will be inserted in the * The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms, * global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires. * attributes or functions that the snippet requires.
* </para> *
* <para>
* The ‘pre’ string in @snippet will be inserted just before * The ‘pre’ string in @snippet will be inserted just before
* calculating the point size. * calculating the point size.
* </para> *
* <para>
* The ‘replace’ string in @snippet will be used instead of the * The ‘replace’ string in @snippet will be used instead of the
* generated point size calculation if it is present. * generated point size calculation if it is present.
* </para> *
* <para>
* The ‘post’ string in @snippet will be inserted after the * The ‘post’ string in @snippet will be inserted after the
* standard point size calculation is done. This can be used to modify * standard point size calculation is done. This can be used to modify
* cogl_point_size_out in addition to the default processing. * cogl_point_size_out in addition to the default processing.
* </para> *
* </glossdef> * - `COGL_SNIPPET_HOOK_FRAGMENT`
* </glossentry> *
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_FRAGMENT</glossterm>
* <glossdef>
* <para>
* Adds a shader snippet that will hook on to the fragment processing * Adds a shader snippet that will hook on to the fragment processing
* stage of the pipeline. This gives a chance for the application to * stage of the pipeline. This gives a chance for the application to
* modify the fragment color generated by the shader. Typically the * modify the fragment color generated by the shader. Typically the
* snippet will modify cogl_color_out. * snippet will modify cogl_color_out.
* </para> *
* <para>
* The ‘declarations’ string in @snippet will be inserted in the * The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms, * global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires. * attributes or functions that the snippet requires.
* </para> *
* <para>
* The ‘pre’ string in @snippet will be inserted at the top of the * The ‘pre’ string in @snippet will be inserted at the top of the
* main() function before any fragment processing is done. * main() function before any fragment processing is done.
* </para> *
* <para>
* The ‘replace’ string in @snippet will be used instead of the * The ‘replace’ string in @snippet will be used instead of the
* generated fragment processing if it is present. This can be used if * generated fragment processing if it is present. This can be used if
* the application wants to provide a complete fragment shader and * the application wants to provide a complete fragment shader and
* doesn't need the generated output from Cogl. * doesn't need the generated output from Cogl.
* </para> *
* <para>
* The ‘post’ string in @snippet will be inserted after all of the * The ‘post’ string in @snippet will be inserted after all of the
* standard fragment processing is done. At this point the generated * standard fragment processing is done. At this point the generated
* value for the rest of the pipeline state will already be in * value for the rest of the pipeline state will already be in
* cogl_color_out so the application can modify the result by altering * cogl_color_out so the application can modify the result by altering
* this variable. * this variable.
* </para> *
* </glossdef> * - `COGL_SNIPPET_HOOK_TEXTURE_COORD_TRANSFORM`
* </glossentry> *
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_TEXTURE_COORD_TRANSFORM</glossterm>
* <glossdef>
* <para>
* Adds a shader snippet that will hook on to the texture coordinate * Adds a shader snippet that will hook on to the texture coordinate
* transformation of a particular layer. This can be used to replace * transformation of a particular layer. This can be used to replace
* the processing for a layer or to modify the results. * the processing for a layer or to modify the results.
* </para> *
* <para>
* Within the snippet code for this hook there are two extra * Within the snippet code for this hook there are two extra
* variables. The first is a mat4 called cogl_matrix which represents * variables. The first is a mat4 called cogl_matrix which represents
* the user matrix for this layer. The second is called cogl_tex_coord * 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 * varying to the fragment processing stage. The default code will
* just multiply cogl_matrix by cogl_tex_coord and store the result in * just multiply cogl_matrix by cogl_tex_coord and store the result in
* cogl_tex_coord. * cogl_tex_coord.
* </para> *
* <para>
* The ‘declarations’ string in @snippet will be inserted in the * The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms, * global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires. * attributes or functions that the snippet requires.
* </para> *
* <para>
* The ‘pre’ string in @snippet will be inserted just before the * The ‘pre’ string in @snippet will be inserted just before the
* fragment processing for this layer. At this point cogl_tex_coord * fragment processing for this layer. At this point cogl_tex_coord
* still contains the value of the texture coordinate attribute. * still contains the value of the texture coordinate attribute.
* </para>
* <para>
* If a ‘replace’ string is given then this will be used instead of * If a ‘replace’ string is given then this will be used instead of
* the default fragment processing for this layer. The snippet can * the default fragment processing for this layer. The snippet can
* modify cogl_tex_coord or leave it as is to apply no transformation. * modify cogl_tex_coord or leave it as is to apply no transformation.
* </para> *
* <para>
* The ‘post’ string in @snippet will be inserted just after the * The ‘post’ string in @snippet will be inserted just after the
* transformation. At this point cogl_tex_coord will contain the * transformation. At this point cogl_tex_coord will contain the
* results of the transformation but it can be further modified by the * results of the transformation but it can be further modified by the
* snippet. * snippet.
* </para> *
* </glossdef> * - `COGL_SNIPPET_HOOK_LAYER_FRAGMENT`
* </glossentry> *
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_LAYER_FRAGMENT</glossterm>
* <glossdef>
* <para>
* Adds a shader snippet that will hook on to the fragment processing * Adds a shader snippet that will hook on to the fragment processing
* of a particular layer. This can be used to replace the processing * of a particular layer. This can be used to replace the processing
* for a layer or to modify the results. * for a layer or to modify the results.
* </para> *
* <para>
* Within the snippet code for this hook there is an extra vec4 * Within the snippet code for this hook there is an extra vec4
* variable called ‘cogl_layer’. This contains the resulting color * variable called ‘cogl_layer’. This contains the resulting color
* that will be used for the layer. This can be modified in the ‘post’ * 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 * section or it the default processing can be replaced entirely using
* the ‘replace’ section. * the ‘replace’ section.
* </para> *
* <para>
* The ‘declarations’ string in @snippet will be inserted in the * The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms, * global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires. * attributes or functions that the snippet requires.
* </para> *
* <para>
* The ‘pre’ string in @snippet will be inserted just before the * The ‘pre’ string in @snippet will be inserted just before the
* fragment processing for this layer. * fragment processing for this layer.
* </para> *
* <para>
* If a ‘replace’ string is given then this will be used instead of * 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 default fragment processing for this layer. The snippet must write to
* the ‘cogl_layer’ variable in that case. * the ‘cogl_layer’ variable in that case.
* </para> *
* <para>
* The ‘post’ string in @snippet will be inserted just after the * The ‘post’ string in @snippet will be inserted just after the
* fragment processing for the layer. The results can be modified by changing * fragment processing for the layer. The results can be modified by changing
* the value of the ‘cogl_layer’ variable. * the value of the ‘cogl_layer’ variable.
* </para> *
* </glossdef> * - `COGL_SNIPPET_HOOK_TEXTURE_LOOKUP`
* </glossentry> *
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_TEXTURE_LOOKUP</glossterm>
* <glossdef>
* <para>
* Adds a shader snippet that will hook on to the texture lookup part * 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 * 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 * the coordinates that will be used for the texture lookup or to
* alter the returned texel. * alter the returned texel.
* </para> *
* <para>
* Within the snippet code for this hook there are three extra * Within the snippet code for this hook there are three extra
* variables available. ‘cogl_sampler’ is a sampler object * variables available. ‘cogl_sampler’ is a sampler object
* representing the sampler for the layer where the snippet is * 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 * coordinates that will be used for the texture lookup. This can be
* modified. ‘cogl_texel’ will contain the result of the texture * modified. ‘cogl_texel’ will contain the result of the texture
* lookup. This can also be modified. * lookup. This can also be modified.
* </para> *
* <para>
* The ‘declarations’ string in @snippet will be inserted in the * The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms, * global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires. * attributes or functions that the snippet requires.
* </para> *
* <para>
* The ‘pre’ string in @snippet will be inserted at the top of the * The ‘pre’ string in @snippet will be inserted at the top of the
* main() function before any fragment processing is done. This is a * main() function before any fragment processing is done. This is a
* good place to modify the cogl_tex_coord variable. * good place to modify the cogl_tex_coord variable.
* </para> *
* <para>
* If a ‘replace’ string is given then this will be used instead of a * 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 * the default texture lookup. The snippet would typically use its own
* sampler in this case. * sampler in this case.
* </para> *
* <para>
* The ‘post’ string in @snippet will be inserted after texture lookup * The ‘post’ string in @snippet will be inserted after texture lookup
* has been performed. Here the snippet can modify the cogl_texel * has been performed. Here the snippet can modify the cogl_texel
* variable to alter the returned texel. * variable to alter the returned texel.
* </para>
* </glossdef>
* </glossentry>
* </glosslist>
*/ */
typedef enum typedef enum
{ {

4
cogl/cogl/cogl-sub-texture.h
View File

@ -80,11 +80,11 @@ GType cogl_sub_texture_get_type (void) G_GNUC_CONST;
* #CoglMetaTexture interface because it's not a low level texture * #CoglMetaTexture interface because it's not a low level texture
* that hardware can understand natively. * that hardware can understand natively.
* *
* <note>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 * as cogl_rectangle() or other APIs documented to understand the
* #CoglMetaTexture interface then you need to use the * #CoglMetaTexture interface then you need to use the
* #CoglMetaTexture interface to resolve a #CoglSubTexture into a * #CoglMetaTexture interface to resolve a #CoglSubTexture into a
* low-level texture before drawing.</note> * low-level texture before drawing.
* *
* Return value: (transfer full): A newly allocated #CoglSubTexture * Return value: (transfer full): A newly allocated #CoglSubTexture
* representing a sub-region of @parent_texture. * representing a sub-region of @parent_texture.

16
cogl/cogl/cogl-texture-2d-sliced.h
View File

@ -111,11 +111,11 @@ GType cogl_texture_2d_sliced_get_type (void) G_GNUC_CONST;
* allocate the underlying storage or let Cogl automatically allocate * allocate the underlying storage or let Cogl automatically allocate
* storage lazily. * storage lazily.
* *
* <note>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 * later due to impossible slicing constraints if a negative
* @max_waste value is given. If the given virtual texture size size * @max_waste value is given. If the given virtual texture size size
* is larger than is supported by the hardware but slicing is disabled * is larger than is supported by the hardware but slicing is disabled
* the texture size would be too large to handle.</note> * the texture size would be too large to handle.
* *
* Returns: (transfer full): A new #CoglTexture2DSliced object with no storage * Returns: (transfer full): A new #CoglTexture2DSliced object with no storage
* allocated yet. * 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 * wasted padding at the bottom and right of the textures is less than
* specified. A negative @max_waste will disable slicing. * specified. A negative @max_waste will disable slicing.
* *
* <note>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 * the required texture slices and upload the given data so that the
* @data pointer does not need to remain valid once this function * @data pointer does not need to remain valid once this function
* returns. This means it is not possible to configure the texture * 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 * for example) then you can instead create a #CoglBitmap for your
* data and use cogl_texture_2d_sliced_new_from_bitmap() or use * 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_2d_sliced_new_with_size() and then upload data using
* cogl_texture_set_data()</note> * cogl_texture_set_data()
* *
* <note>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 * due to impossible slicing constraints if a negative @max_waste
* value is given. If the given virtual texture size is larger than is * value is given. If the given virtual texture size is larger than is
* supported by the hardware but slicing is disabled the texture size * supported by the hardware but slicing is disabled the texture size
* would be too large to handle.</note> * would be too large to handle.
* *
* Return value: (transfer full): A newly created #CoglTexture2DSliced * Return value: (transfer full): A newly created #CoglTexture2DSliced
* or %NULL on failure and @error will be updated. * 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 * allocate the underlying storage or let Cogl automatically allocate
* storage lazily. * storage lazily.
* *
* <note>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 * later due to impossible slicing constraints if a negative
* @max_waste value is given. If the given virtual texture size is * @max_waste value is given. If the given virtual texture size is
* larger than is supported by the hardware but slicing is disabled * larger than is supported by the hardware but slicing is disabled
* the texture size would be too large to handle.</note> * the texture size would be too large to handle.
* *
* Return value: (transfer full): A newly created #CoglTexture2DSliced * Return value: (transfer full): A newly created #CoglTexture2DSliced
* or %NULL on failure and @error will be updated. * or %NULL on failure and @error will be updated.

4
cogl/cogl/cogl-texture-2d.h
View File

@ -152,7 +152,7 @@ cogl_texture_2d_new_with_size (CoglContext *ctx,
* Creates a low-level #CoglTexture2D texture based on data residing * Creates a low-level #CoglTexture2D texture based on data residing
* in memory. * in memory.
* *
* <note>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 * texture and upload the given data so that the @data pointer does
* not need to remain valid once this function returns. This means it * not need to remain valid once this function returns. This means it
* is not possible to configure the texture before it is allocated. If * 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 * instead create a #CoglBitmap for your data and use
* cogl_texture_2d_new_from_bitmap() or use * cogl_texture_2d_new_from_bitmap() or use
* cogl_texture_2d_new_with_size() and then upload data using * cogl_texture_2d_new_with_size() and then upload data using
* cogl_texture_set_data()</note> * cogl_texture_set_data()
* *
* Returns: (transfer full): A newly allocated #CoglTexture2D, or if * Returns: (transfer full): A newly allocated #CoglTexture2D, or if
* the size is not supported (because it is too large or a * the size is not supported (because it is too large or a

26
cogl/cogl/cogl-texture.h
View File

@ -294,10 +294,10 @@ cogl_texture_get_gl_texture (CoglTexture *texture,
* *
* Copies the pixel data from a cogl texture to system memory. * Copies the pixel data from a cogl texture to system memory.
* *
* <note>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 * @rowstride argument, the rowstride should be the rowstride you
* want for the destination @data buffer not the rowstride of the * want for the destination @data buffer not the rowstride of the
* source texture</note> * source texture
* *
* Return value: the size of the texture data in bytes * 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 * Sets the pixels in a rectangular subregion of @texture from an in-memory
* buffer containing pixel data. * buffer containing pixel data.
* *
* <note>The region set can't be larger than the source @data</note> * The region set can't be larger than the source @data
* *
* Return value: %TRUE if the subregion upload was successful, and * Return value: %TRUE if the subregion upload was successful, and
* %FALSE otherwise * %FALSE otherwise
@ -374,16 +374,16 @@ cogl_texture_set_region (CoglTexture *texture,
* fraction then round the number down (floor()), but clamp to 1 * fraction then round the number down (floor()), but clamp to 1
* something like this: * something like this:
* *
* |[ * ```
* next_width = MAX (1, floor (prev_width)); * next_width = MAX (1, floor (prev_width));
* ]| * ```
* *
* You can determine the number of mipmap levels for a given texture * You can determine the number of mipmap levels for a given texture
* like this: * like this:
* *
* |[ * ```
* n_levels = 1 + floor (log2 (max_dimension)); * n_levels = 1 + floor (log2 (max_dimension));
* ]| * ```
* *
* Where %max_dimension is the larger of cogl_texture_get_width() and * Where %max_dimension is the larger of cogl_texture_get_width() and
* cogl_texture_get_height(). * 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 * It is an error to pass a @level number >= the number of levels that
* @texture can have according to the above calculation. * @texture can have according to the above calculation.
* *
* <note>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 * if the given @texture has not previously been allocated then this
* api can return %FALSE and throw an exceptional @error if there is * api can return %FALSE and throw an exceptional @error if there is
* not enough memory to allocate storage for @texture.</note> * not enough memory to allocate storage for @texture.
* *
* Return value: %TRUE if the data upload was successful, and * Return value: %TRUE if the data upload was successful, and
* %FALSE otherwise * %FALSE otherwise
@ -423,8 +423,8 @@ cogl_texture_set_data (CoglTexture *texture,
* Copies a specified source region from @bitmap to the position * Copies a specified source region from @bitmap to the position
* (@src_x, @src_y) of the given destination texture @handle. * (@src_x, @src_y) of the given destination texture @handle.
* *
* <note>The region updated can't be larger than the source * The region updated can't be larger than the source
* bitmap</note> * bitmap
* *
* Return value: %TRUE if the subregion upload was successful, and * Return value: %TRUE if the subregion upload was successful, and
* %FALSE otherwise * %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 * allows you to be sure that there is enough memory for the
* texture and if not then the error can be handled gracefully. * texture and if not then the error can be handled gracefully.
* *
* <note>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 * since the texture will be implicitly allocated when data is set on
* the texture, or if the texture is attached to a #CoglOffscreen * the texture, or if the texture is attached to a #CoglOffscreen
* framebuffer and rendered too.</note> * framebuffer and rendered too.
* *
* Return value: %TRUE if the texture was successfully allocated, * Return value: %TRUE if the texture was successfully allocated,
* otherwise %FALSE and @error will be updated if it * otherwise %FALSE and @error will be updated if it

34
cogl/cogl/cogl-types.h
View File

@ -186,15 +186,12 @@ cogl_blend_string_error_quark (void);
* The @COGL_SYSTEM_ERROR_UNSUPPORTED error can be thrown for a * The @COGL_SYSTEM_ERROR_UNSUPPORTED error can be thrown for a
* variety of reasons. For example: * variety of reasons. For example:
* *
* <itemizedlist> * - You've tried to use a feature that is not advertised by
* <listitem><para>You've tried to use a feature that is not * [func@Cogl.has_feature].
* advertised by cogl_has_feature().</para></listitem> * - The GPU can not handle the configuration you have requested.
* <listitem><para>The GPU can not handle the configuration you have * An example might be if you try to use too many texture
* requested. An example might be if you try to use too many texture * layers in a single #CoglPipeline
* layers in a single #CoglPipeline</para></listitem> * - The driver does not support some configuration.
* <listitem><para>The driver does not support some
* configuration.</para></listiem>
* </itemizedlist>
* *
* Currently this is only used by Cogl API marked as experimental so * Currently this is only used by Cogl API marked as experimental so
* this enum should also be considered experimental. * this enum should also be considered experimental.
@ -254,18 +251,13 @@ typedef enum
/** /**
* CoglVerticesMode: * CoglVerticesMode:
* @COGL_VERTICES_MODE_POINTS: FIXME, equivalent to * @COGL_VERTICES_MODE_POINTS: FIXME, equivalent to `GL_POINTS`
* <constant>GL_POINTS</constant> * @COGL_VERTICES_MODE_LINES: FIXME, equivalent to `GL_LINES`
* @COGL_VERTICES_MODE_LINES: FIXME, equivalent to <constant>GL_LINES</constant> * @COGL_VERTICES_MODE_LINE_LOOP: FIXME, equivalent to `GL_LINE_LOOP`
* @COGL_VERTICES_MODE_LINE_LOOP: FIXME, equivalent to * @COGL_VERTICES_MODE_LINE_STRIP: FIXME, equivalent to `GL_LINE_STRIP`
* <constant>GL_LINE_LOOP</constant> * @COGL_VERTICES_MODE_TRIANGLES: FIXME, equivalent to `GL_TRIANGLES`
* @COGL_VERTICES_MODE_LINE_STRIP: FIXME, equivalent to * @COGL_VERTICES_MODE_TRIANGLE_STRIP: FIXME, equivalent to `GL_TRIANGLE_STRIP`
* <constant>GL_LINE_STRIP</constant> * @COGL_VERTICES_MODE_TRIANGLE_FAN: FIXME, equivalent to `GL_TRIANGLE_FAN`
* @COGL_VERTICES_MODE_TRIANGLES: FIXME, equivalent to
* <constant>GL_TRIANGLES</constant>
* @COGL_VERTICES_MODE_TRIANGLE_STRIP: FIXME, equivalent to
* <constant>GL_TRIANGLE_STRIP</constant>
* @COGL_VERTICES_MODE_TRIANGLE_FAN: FIXME, equivalent to <constant>GL_TRIANGLE_FAN</constant>
* *
* Different ways of interpreting vertices when drawing. * Different ways of interpreting vertices when drawing.
*/ */

4
cogl/cogl/cogl1-context.h
View File

@ -52,9 +52,9 @@ G_BEGIN_DECLS
* as a wrapper around glXGetProcAddress() or whatever is the * as a wrapper around glXGetProcAddress() or whatever is the
* appropriate function for the current backend. * appropriate function for the current backend.
* *
* <note>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 * symbols since eglGetProcAddress for example doesn't allow this and
* and may return a junk pointer if you do.</note> * and may return a junk pointer if you do.
* *
* Return value: a pointer to the requested function or %NULL if the * Return value: a pointer to the requested function or %NULL if the
* function is not available. * function is not available.

137
cogl/cogl/deprecated/cogl-shader.h
View File

@ -57,164 +57,66 @@ G_BEGIN_DECLS
* *
* For use in all GLSL shaders, the Cogl builtins are as follows: * For use in all GLSL shaders, the Cogl builtins are as follows:
* *
* <tip> * - `uniform mat4 cogl_modelview_matrix`
* <glosslist>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_modelview_matrix</emphasis></glossterm>
* <glossdef><para>
* The current modelview matrix. This is equivalent to * The current modelview matrix. This is equivalent to
* #gl_ModelViewMatrix. * #gl_ModelViewMatrix.
* </para></glossdef> * - `uniform mat4 cogl_projection_matrix`
* </glossentry>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_projection_matrix</emphasis></glossterm>
* <glossdef><para>
* The current projection matrix. This is equivalent to * The current projection matrix. This is equivalent to
* #gl_ProjectionMatrix. * #gl_ProjectionMatrix.
* </para></glossdef> * - `uniform mat4 cogl_modelview_projection_matrix`
* </glossentry>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_modelview_projection_matrix</emphasis></glossterm>
* <glossdef><para>
* The combined modelview and projection matrix. A vertex shader * The combined modelview and projection matrix. A vertex shader
* would typically use this to transform the incoming vertex * would typically use this to transform the incoming vertex
* position. The separate modelview and projection matrices are * position. The separate modelview and projection matrices are
* usually only needed for lighting calculations. This is * usually only needed for lighting calculations. This is
* equivalent to #gl_ModelViewProjectionMatrix. * equivalent to #gl_ModelViewProjectionMatrix.
* </para></glossdef> * - `uniform mat4 cogl_texture_matrix[]`
* </glossentry>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_texture_matrix</emphasis>[]</glossterm>
* <glossdef><para>
* An array of matrices for transforming the texture * An array of matrices for transforming the texture
* coordinates. This is equivalent to #gl_TextureMatrix. * coordinates. This is equivalent to #gl_TextureMatrix.
* </para></glossdef>
* </glossentry>
* </glosslist>
* </tip>
* *
* In a vertex shader, the following are also available: * In a vertex shader, the following are also available:
* *
* <tip> * - `attribute vec4 cogl_position_in`
* <glosslist>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_position_in</emphasis></glossterm>
* <glossdef><para>
* The incoming vertex position. This is equivalent to #gl_Vertex. * The incoming vertex position. This is equivalent to #gl_Vertex.
* </para></glossdef> * - `attribute vec4 cogl_color_in`
* </glossentry>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_color_in</emphasis></glossterm>
* <glossdef><para>
* The incoming vertex color. This is equivalent to #gl_Color. * The incoming vertex color. This is equivalent to #gl_Color.
* </para></glossdef> * - `attribute vec4 cogl_tex_coord_in`
* </glossentry>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_tex_coord_in</emphasis></glossterm>
* <glossdef><para>
* The texture coordinate for the first texture unit. This is * The texture coordinate for the first texture unit. This is
* equivalent to #gl_MultiTexCoord0. * equivalent to #gl_MultiTexCoord0.
* </para></glossdef> * - `attribute vec4 cogl_tex_coord0_in`
* </glossentry>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_tex_coord0_in</emphasis></glossterm>
* <glossdef><para>
* The texture coordinate for the first texture unit. This is * The texture coordinate for the first texture unit. This is
* equivalent to #gl_MultiTexCoord0. There is also * equivalent to #gl_MultiTexCoord0. There is also
* #cogl_tex_coord1_in and so on. * #cogl_tex_coord1_in and so on.
* </para></glossdef> * - `attribute vec3 cogl_normal_in`
* </glossentry>
* <glossentry>
* <glossterm>attribute vec3
* <emphasis>cogl_normal_in</emphasis></glossterm>
* <glossdef><para>
* The normal of the vertex. This is equivalent to #gl_Normal. * The normal of the vertex. This is equivalent to #gl_Normal.
* </para></glossdef> * - `vec4 cogl_position_out`
* </glossentry>
* <glossentry>
* <glossterm>vec4
* <emphasis>cogl_position_out</emphasis></glossterm>
* <glossdef><para>
* The calculated position of the vertex. This must be written to * The calculated position of the vertex. This must be written to
* in all vertex shaders. This is equivalent to #gl_Position. * in all vertex shaders. This is equivalent to #gl_Position.
* </para></glossdef> * - `float cogl_point_size_out`
* </glossentry>
* <glossentry>
* <glossterm>float
* <emphasis>cogl_point_size_out</emphasis></glossterm>
* <glossdef><para>
* The calculated size of a point. This is equivalent to #gl_PointSize. * The calculated size of a point. This is equivalent to #gl_PointSize.
* </para></glossdef> * - `varying vec4 cogl_color_out`
* </glossentry>
* <glossentry>
* <glossterm>varying vec4
* <emphasis>cogl_color_out</emphasis></glossterm>
* <glossdef><para>
* The calculated color of a vertex. This is equivalent to #gl_FrontColor. * The calculated color of a vertex. This is equivalent to #gl_FrontColor.
* </para></glossdef> * - `varying vec4 cogl_tex_coord_out[]`
* </glossentry>
* <glossentry>
* <glossterm>varying vec4
* <emphasis>cogl_tex_coord_out</emphasis>[]</glossterm>
* <glossdef><para>
* An array of calculated texture coordinates for a vertex. This is * An array of calculated texture coordinates for a vertex. This is
* equivalent to #gl_TexCoord. * equivalent to #gl_TexCoord.
* </para></glossdef>
* </glossentry>
* </glosslist>
* </tip>
* *
* In a fragment shader, the following are also available: * In a fragment shader, the following are also available:
* *
* <tip> * - `varying vec4 cogl_color_in`
* <glosslist>
* <glossentry>
* <glossterm>varying vec4 <emphasis>cogl_color_in</emphasis></glossterm>
* <glossdef><para>
* The calculated color of a vertex. This is equivalent to #gl_FrontColor. * The calculated color of a vertex. This is equivalent to #gl_FrontColor.
* </para></glossdef> * - `varying vec4 cogl_tex_coord_in[]`
* </glossentry>
* <glossentry>
* <glossterm>varying vec4
* <emphasis>cogl_tex_coord_in</emphasis>[]</glossterm>
* <glossdef><para>
* An array of calculated texture coordinates for a vertex. This is * An array of calculated texture coordinates for a vertex. This is
* equivalent to #gl_TexCoord. * equivalent to #gl_TexCoord.
* </para></glossdef> * - `vec4 cogl_color_out`
* </glossentry>
* <glossentry>
* <glossterm>vec4 <emphasis>cogl_color_out</emphasis></glossterm>
* <glossdef><para>
* The final calculated color of the fragment. All fragment shaders * The final calculated color of the fragment. All fragment shaders
* must write to this variable. This is equivalent to * must write to this variable. This is equivalent to
* #gl_FrontColor. * #gl_FrontColor.
* </para></glossdef> * - `float cogl_depth_out`
* </glossentry>
* <glossentry>
* <glossterm>float <emphasis>cogl_depth_out</emphasis></glossterm>
* <glossdef><para>
* An optional output variable specifying the depth value to use * An optional output variable specifying the depth value to use
* for this fragment. This is equivalent to #gl_FragDepth. * for this fragment. This is equivalent to #gl_FragDepth.
* </para></glossdef> * - `bool cogl_front_facing`
* </glossentry>
* <glossentry>
* <glossterm>bool <emphasis>cogl_front_facing</emphasis></glossterm>
* <glossdef><para>
* A readonly variable that will be true if the current primitive * A readonly variable that will be true if the current primitive
* is front facing. This can be used to implement two-sided * is front facing. This can be used to implement two-sided
* coloring algorithms. This is equivalent to #gl_FrontFacing. * coloring algorithms. This is equivalent to #gl_FrontFacing.
* </para></glossdef>
* </glossentry>
* </glosslist>
* </tip>
* *
* It's worth nothing that this API isn't what Cogl would like to have * 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 * in the long term and it may be removed in Cogl 2.0. The
@ -265,9 +167,6 @@ cogl_create_shader (CoglShaderType shader_type);
* Replaces the current source associated with a shader with a new * Replaces the current source associated with a shader with a new
* one. * one.
* *
* Please see <link
* linkend="cogl-Shaders-and-Programmable-Pipeline.description">above</link>
* for a description of the recommended format for the shader code.
* Deprecated: 1.16: Use #CoglSnippet api * Deprecated: 1.16: Use #CoglSnippet api
*/ */
COGL_DEPRECATED_FOR (cogl_snippet_) COGL_DEPRECATED_FOR (cogl_snippet_)

2
src/compositor/meta-multi-texture.c
View File

@ -198,7 +198,7 @@ meta_multi_texture_class_init (MetaMultiTextureClass *klass)
* @n_planes: The number of planes * @n_planes: The number of planes
* *
* Creates a #MetaMultiTexture with the given @format. Each of the * Creates a #MetaMultiTexture with the given @format. Each of the
* #CoglTexture<!-- -->s represents a plane. * `CoglTexture`s represents a plane.
* *
* Returns: (transfer full): A new #MetaMultiTexture. Use g_object_unref() when * Returns: (transfer full): A new #MetaMultiTexture. Use g_object_unref() when
* you're done with it. * you're done with it.

4
src/tests/clutter-test-utils.c
View File

@ -233,7 +233,7 @@ clutter_test_add_data_full (const char *test_path,
* The typical test suite is composed of a list of functions * The typical test suite is composed of a list of functions
* called by clutter_test_run(), for instance: * called by clutter_test_run(), for instance:
* *
* |[ * ```c
* static void unit_foo (void) { ... } * static void unit_foo (void) { ... }
* *
* static void unit_bar (void) { ... } * static void unit_bar (void) { ... }
@ -251,7 +251,7 @@ clutter_test_add_data_full (const char *test_path,
* *
* return clutter_test_run (); * return clutter_test_run ();
* } * }
* ]| * ```
* *
* Return value: the exit code for the test suite * Return value: the exit code for the test suite
*/ */

8
src/tests/clutter-test-utils.h
View File

@ -51,16 +51,16 @@ G_BEGIN_DECLS
* *
* Defines the entry point and initializes a Clutter test unit, e.g.: * Defines the entry point and initializes a Clutter test unit, e.g.:
* *
* |[ * ```
* CLUTTER_TEST_SUITE ( * CLUTTER_TEST_SUITE (
* CLUTTER_TEST_UNIT ("/foobarize", foobarize) * CLUTTER_TEST_UNIT ("/foobarize", foobarize)
* CLUTTER_TEST_UNIT ("/bar-enabled", bar_enabled) * CLUTTER_TEST_UNIT ("/bar-enabled", bar_enabled)
* ) * )
* ]| * ```
* *
* Expands to: * Expands to:
* *
* |[ * ```c
* int * int
* main (int argc, * main (int argc,
* char *argv[]) * char *argv[])
@ -72,7 +72,7 @@ G_BEGIN_DECLS
* *
* return clutter_test_run (); * return clutter_test_run ();
* } * }
* ]| * ```
*/ */
#define CLUTTER_TEST_SUITE(units) \ #define CLUTTER_TEST_SUITE(units) \
int \ int \