sungmg/mutter-performance-source
1
0
Fork 0
Code 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
* @add_actor: Signal handler for child-added 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
{

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

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

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

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

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

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

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

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

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

@ -48,12 +48,6 @@ struct _CallyUtil
CallyUtilPrivate *priv;
};
/**
* CallyUtilClass:
*
* The <structname>CallyUtilClass</structname> structure contains only
* private data
*/
struct _CallyUtilClass
{
/*< 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 is defined.
*
* The documentation of the <ulink
* url="http://developer.gnome.org/doc/API/2.0/atk/index.html">ATK</ulink>
* The documentation of the [https://gnome.pages.gitlab.gnome.org/at-spi2-core/atk/](ATK)
* library contains more information about accessible objects and
* their uses.
*

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

@ -761,8 +761,7 @@ clutter_color_from_string (ClutterColor *color,
* @color: a #ClutterColor
*
* Returns a textual specification of @color in the hexadecimal form
* <literal>&num;rrggbbaa</literal>, where <literal>r</literal>,
* <literal>g</literal>, <literal>b</literal> and <literal>a</literal> are
* `&num;rrggbbaa`, where `r`, `g`, `b` and `a` are
* hexadecimal digits representing the red, green, blue and alpha components
* 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
* 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
* #CoglMetaTexture for more details.</note>
* #CoglMetaTexture for more details.
*/
#define COGL_TYPE_ATLAS_TEXTURE (cogl_atlas_texture_get_type ())
#define COGL_ATLAS_TEXTURE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), COGL_TYPE_ATLAS_TEXTURE, CoglAtlasTexture))
@ -100,13 +100,13 @@ GType cogl_atlas_texture_get_type (void) G_GNUC_CONST;
* using cogl_texture_set_components() and
* cogl_texture_set_premultiplied().
*
* <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
* 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
* for more details.</note>
* for more details.
*
* Returns: (transfer full): A new #CoglAtlasTexture object.
*/
@ -131,7 +131,7 @@ cogl_atlas_texture_new_with_size (CoglContext *ctx,
* memory. A #CoglAtlasTexture represents a sub-region within one of
* Cogl's shared texture atlases.
*
* <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
* not need to remain valid once this function returns. This means it
* is not possible to configure the texture before it is allocated. If
@ -140,15 +140,15 @@ cogl_atlas_texture_new_with_size (CoglContext *ctx,
* instead create a #CoglBitmap for your data and use
* cogl_atlas_texture_new_from_bitmap() or use
* cogl_atlas_texture_new_with_size() and then upload data using
* cogl_texture_set_data()</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
* 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
* #CoglMetaTexture for more details.</note>
* #CoglMetaTexture for more details.
*
* Return value: (transfer full): A new #CoglAtlasTexture object or
* %NULL on failure and @error will be updated.
@ -181,13 +181,13 @@ cogl_atlas_texture_new_from_data (CoglContext *ctx,
* using cogl_texture_set_components() and
* cogl_texture_set_premultiplied().
*
* <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
* 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
* for more details.</note>
* for more details.
*
* 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.
*
* <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
* 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
* application needs to gracefully handle out-of-memory errors then
* you can use cogl_attribute_buffer_new_with_size() and then
* explicitly catch errors with cogl_buffer_set_data() or
* cogl_buffer_map().</note>
* cogl_buffer_map().
*
* 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)
* @stride: The number of bytes to jump to get to the next attribute
* value for the next vertex. (Usually
* <literal>sizeof (MyVertex)</literal>)
* `sizeof (MyVertex)`)
* @offset: The byte offset from the start of @attribute_buffer for
* 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
* 3 for and (x,y,z) position)
* @type: FIXME
@ -79,50 +79,48 @@ G_DECLARE_FINAL_TYPE (CoglAttribute,
* The @name is used to access the attribute inside a GLSL vertex
* shader and there are some special names you should use if they are
* applicable:
* <itemizedlist>
* <listitem>"cogl_position_in" (used for vertex positions)</listitem>
* <listitem>"cogl_color_in" (used for vertex colors)</listitem>
* <listitem>"cogl_tex_coord0_in", "cogl_tex_coord1", ...
* (used for vertex texture coordinates)</listitem>
* <listitem>"cogl_normal_in" (used for vertex normals)</listitem>
* <listitem>"cogl_point_size_in" (used to set the size of points
*
* - "cogl_position_in" (used for vertex positions)
* - "cogl_color_in" (used for vertex colors)
* - "cogl_tex_coord0_in", "cogl_tex_coord1", ...
* (used for vertex texture coordinates)
* - "cogl_normal_in" (used for vertex normals)
* - "cogl_point_size_in" (used to set the size of points
* per-vertex. Note this can only be used if
* %COGL_FEATURE_ID_POINT_SIZE_ATTRIBUTE is advertised and
* cogl_pipeline_set_per_vertex_point_size() is called on the pipeline.
* </listitem>
* </itemizedlist>
*
* The attribute values corresponding to different vertices can either
* be tightly packed or interleaved with other attribute values. For
* example it's common to define a structure for a single vertex like:
* |[
* ```c
* typedef struct
* {
* float x, y, z; /<!-- -->* position attribute *<!-- -->/
* float s, t; /<!-- -->* texture coordinate attribute *<!-- -->/
* } MyVertex;
* ]|
* ```
*
* And then create an array of vertex data something like:
* |[
* ```c
* MyVertex vertices[100] = { .... }
* ]|
* ```
*
* In this case, to describe either the position or texture coordinate
* attribute you have to move <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
* @stride. If you weren't interleving attributes and you instead had
* a packed array of float x, y pairs then the attribute stride would
* be <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.
*
* Normally a list of attributes starts at the beginning of an array.
* So for the <literal>MyVertex</literal> example above the @offset is the
* offset inside the <literal>MyVertex</literal> structure to the first
* So for the `MyVertex` example above the @offset is the
* offset inside the `MyVertex` structure to the first
* component of the attribute. For the texture coordinate attribute
* the offset would be <literal>offsetof (MyVertex, s)</literal> or instead of
* using the offsetof macro you could use <literal>sizeof (float) *
* 3</literal>. If you've divided your @array into blocks of non-interleved
* the offset would be `offsetof (MyVertex, s)` or instead of
* using the offsetof macro you could use `sizeof (float) *
* 3`. If you've divided your @array into blocks of non-interleved
* attributes then you will need to calculate the @offset as the number of
* bytes in blocks preceding the attribute you're describing.
*

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
* 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
* a texture from it with cogl_texture_new_from_bitmap(). For various
* reasons, such arrays are likely to have a stride larger than width
* * bytes_per_pixel. The user must take the stride into account when
* writing into it. The stride can be retrieved with
* cogl_bitmap_get_rowstride().</note>
* cogl_bitmap_get_rowstride().
*
* Return value: (transfer full): a #CoglPixelBuffer representing the
* 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:
* @buffer: a buffer object
* @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.
*
* Maps the buffer into the application address space for direct
@ -234,7 +234,7 @@ cogl_buffer_map (CoglBuffer *buffer,
* @offset: Offset within the buffer to start the mapping
* @size: The size of data to map
* @access: how the mapped buffer will be used by the application
* @hints: A mask of #CoglBufferMapHint<!-- -->s that tell Cogl how
* @hints: A mask of `CoglBufferMapHint`s that tell Cogl how
* the data will be modified once mapped.
* @error: A #GError for catching exceptional errors
*

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

@ -440,10 +440,10 @@ cogl_color_unpremultiply (CoglColor *color);
* @v1: 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
* 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.
*/

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
* 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
* help applications control the lifetime a context without us needing to
* introduce special api to handle the breakup of internal circular
@ -90,7 +90,7 @@ G_BEGIN_DECLS
* times throughout their lifetime (such as Android applications) they
* should be careful to destroy all context dependent resources, such as
* framebuffers or textures etc before unrefing and destroying the
* context.</para></note>
* context.
*/
#define COGL_TYPE_CONTEXT (cogl_context_get_type ())
@ -219,7 +219,7 @@ cogl_has_feature (CoglContext *context, CoglFeatureID feature);
/**
* cogl_has_features:
* @context: A #CoglContext pointer
* @...: A 0 terminated list of CoglFeatureID<!-- -->s
* @...: A 0 terminated list of `CoglFeatureID`s
*
* 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
* 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
* 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
* CLOCK_MONOTONIC.
*
* <note>Some buggy Mesa drivers up to 9.0.1 may
* incorrectly report non-monotonic timestamps.</note>
* Some buggy Mesa drivers up to 9.0.1 may
* incorrectly report non-monotonic timestamps.
*
* Return value: the presentation time for the frame
*/
@ -98,11 +98,11 @@ int64_t cogl_frame_info_get_presentation_time_us (CoglFrameInfo *info);
* Gets the refresh rate in Hertz for the output that the frame was on
* at the time the frame was presented.
*
* <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
* this api. Therefore if you need this information then this api is
* more reliable than using cogl_frame_info_get_output() followed by
* cogl_output_get_refresh_rate().</note>
* cogl_output_get_refresh_rate().
*
* 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
* 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
* since Cogl will automatically allocate a framebuffer when it first gets
* used. The disadvantage of relying on automatic allocation is that the
* program will abort with an error message if there is an error during
* automatic allocation.</note>
* automatic allocation.
*
* Return value: %TRUE if there were no error allocating the framebuffer, else %FALSE.
*/
@ -167,9 +167,9 @@ cogl_framebuffer_get_height (CoglFramebuffer *framebuffer);
* contents down by specify and width and height that's half the real
* size of the framebuffer.
*
* <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
* point values will be exposed via a checkable feature.</note>
* point values will be exposed via a checkable feature.
*
*/
COGL_EXPORT void
@ -382,10 +382,10 @@ cogl_framebuffer_set_modelview_matrix (CoglFramebuffer *framebuffer,
* Replaces the current projection matrix with a perspective matrix
* based on the provided values.
*
* <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
* 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_framebuffer_perspective (CoglFramebuffer *framebuffer,
@ -428,11 +428,11 @@ cogl_framebuffer_frustum (CoglFramebuffer *framebuffer,
* @y_1: The y coordinate for the first horizontal clipping plane
* @x_2: The x coordinate for the second vertical clipping plane
* @y_2: The y coordinate for the second horizontal clipping plane
* @near: The <emphasis>distance</emphasis> to the near clipping
* plane (will be <emphasis>negative</emphasis> if the plane is
* @near: The *distance* to the near clipping
* plane (will be *negative* if the plane is
* behind the viewer)
* @far: The <emphasis>distance</emphasis> to the far clipping
* plane (will be <emphasis>negative</emphasis> if the plane is
* @far: The *distance* to the far clipping
* plane (will be *negative* if the plane is
* behind the viewer)
*
* Replaces the current projection matrix with an orthographic projection
@ -622,9 +622,9 @@ cogl_framebuffer_get_is_stereo (CoglFramebuffer *framebuffer);
* Returns whether dithering has been requested for the given @framebuffer.
* See cogl_framebuffer_set_dither_enabled() for more details about dithering.
*
* <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
* 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.
*/
@ -737,19 +737,19 @@ cogl_framebuffer_set_stereo_mode (CoglFramebuffer *framebuffer,
* as "single-sample" rendering. A value of 1 or greater is referred
* to as "multisample" rendering.
*
* <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
* being redundant to use the cogl_framebuffer_resolve_samples() and
* 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
* end of rendering to a point sample buffer to minimize the number of
* samples that get resolved. By default Cogl will implicitly resolve
* all framebuffer samples but if only a small region of a
* framebuffer has changed this can lead to redundant work being
* done.</note>
* done.
*
*/
COGL_EXPORT void
@ -865,7 +865,7 @@ cogl_framebuffer_get_context (CoglFramebuffer *framebuffer);
/**
* cogl_framebuffer_clear:
* @framebuffer: A #CoglFramebuffer
* @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary
* @buffers: A mask of `CoglBufferBit`s identifying which auxiliary
* buffers to clear
* @color: The color to clear the color buffer too if specified in
* @buffers.
@ -882,7 +882,7 @@ cogl_framebuffer_clear (CoglFramebuffer *framebuffer,
/**
* cogl_framebuffer_clear4f:
* @framebuffer: A #CoglFramebuffer
* @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary
* @buffers: A mask of `CoglBufferBit`s identifying which auxiliary
* buffers to clear
* @red: The red component of color to clear the color buffer too if
* specified in @buffers.
@ -918,13 +918,13 @@ cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer,
* and with the top left corner positioned at (@x_1, @y_1) and the
* bottom right corner positioned at (@x_2, @y_2).
*
* <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
* 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
* cogl_framebuffer_draw_textured_rectangle().</note>
* cogl_framebuffer_draw_textured_rectangle().
*/
COGL_EXPORT void
cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer,
@ -953,9 +953,9 @@ cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer,
* left corner will have texture coordinates of (@s_1, @t_1) and the
* bottom right corner will have texture coordinates of (@s_2, @t_2).
*
* <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
* matrix.</note>
* matrix.
*
* This is a high level drawing api that can handle any kind of
* #CoglMetaTexture texture such as #CoglTexture2DSliced textures
@ -964,10 +964,10 @@ cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer,
* which only support low level texture types that are directly
* supported by GPUs such as #CoglTexture2D.
*
* <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
* 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
* (0, 0) corresponds to the top left and (1, 1) corresponds to the
@ -1009,9 +1009,9 @@ cogl_framebuffer_draw_textured_rectangle (CoglFramebuffer *framebuffer,
* contain multiple texture layers this interface lets you supply
* texture coordinates for each layer of the pipeline.
*
* <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
* matrix.</note>
* matrix.
*
* This is a high level drawing api that can handle any kind of
* #CoglMetaTexture texture for the first layer such as
@ -1020,7 +1020,7 @@ cogl_framebuffer_draw_textured_rectangle (CoglFramebuffer *framebuffer,
* such as cogl_primitive_draw() which only support low level texture
* types that are directly supported by GPUs such as #CoglTexture2D.
*
* <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
* such as #CoglTexture2DSliced but all other layers much be low
* level textures such as #CoglTexture2D.
@ -1073,9 +1073,9 @@ cogl_framebuffer_draw_multitextured_rectangle (CoglFramebuffer *framebuffer,
* the second rectangle are (coordinates[4], coordinates[5]) and
* (coordinates[6], coordinates[7]) and so on...
*
* <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
* matrix.</note>
* matrix.
*
* As a general rule for better performance its recommended to use
* this this API instead of calling
@ -1103,9 +1103,9 @@ cogl_framebuffer_draw_rectangles (CoglFramebuffer *framebuffer,
* @pipeline state in the same way that
* cogl_framebuffer_draw_textured_rectangle() does.
*
* <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
* matrix.</note>
* matrix.
*
* This is a high level drawing api that can handle any kind of
* #CoglMetaTexture texture such as #CoglTexture2DSliced textures
@ -1240,7 +1240,7 @@ cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer,
*
* The implementation of the function looks like this:
*
* |[
* ```c
* bitmap = cogl_bitmap_new_for_data (context,
* width, height,
* format,
@ -1252,7 +1252,7 @@ cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer,
* COGL_READ_PIXELS_COLOR_BUFFER,
* bitmap);
* g_object_unref (bitmap);
* ]|
* ```
*
* Return value: %TRUE if the read succeeded or %FALSE otherwise.
*/

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

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

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
* related transforms, these can be some advantages to using a
* #CoglMatrixStack:
* <itemizedlist>
* <listitem>Faster equality comparisons of transformations</listitem>
* <listitem>Efficient comparisons of the differences between arbitrary
* transformations</listitem>
* <listitem>Avoid redundant arithmetic related to common transforms
* </listitem>
* <listitem>Can be more space efficient (not always though)</listitem>
* </itemizedlist>
*
* - Faster equality comparisons of transformations
* - Efficient comparisons of the differences between arbitrary
* transformations
* - Avoid redundant arithmetic related to common transforms
* - Can be more space efficient (not always though)
*
* For reference (to give an idea of when a #CoglMatrixStack can
* provide a space saving) a #graphene_matrix_t can be expected to take 72
@ -172,9 +170,9 @@ G_DECLARE_FINAL_TYPE (CoglMatrixStack,
* comparison but often these false negatives are unlikely and
* don't matter anyway so this enables extremely cheap comparisons.
*
* <note>#CoglMatrixEntry<!-- -->s are reference counted using
* `CoglMatrixEntry`s are reference counted using
* cogl_matrix_entry_ref() and cogl_matrix_entry_unref() not with
* g_object_ref() and g_object_unref().</note>
* g_object_ref() and g_object_unref().
*/
typedef struct _CoglMatrixEntry CoglMatrixEntry;
@ -370,10 +368,10 @@ cogl_matrix_stack_frustum (CoglMatrixStack *stack,
* Replaces the current matrix with a perspective matrix based on the
* provided values.
*
* <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
* 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_matrix_stack_perspective (CoglMatrixStack *stack,
@ -389,11 +387,11 @@ cogl_matrix_stack_perspective (CoglMatrixStack *stack,
* @y_1: The y coordinate for the first horizontal clipping plane
* @x_2: The x coordinate for the second vertical clipping plane
* @y_2: The y coordinate for the second horizontal clipping plane
* @near: The <emphasis>distance</emphasis> to the near clipping
* plane (will be <emphasis>negative</emphasis> if the plane is
* @near: The *distance* to the near clipping
* plane (will be *negative* if the plane is
* behind the viewer)
* @far: The <emphasis>distance</emphasis> to the far clipping
* plane (will be <emphasis>negative</emphasis> if the plane is
* @far: The *distance* to the far clipping
* plane (will be *negative* if the plane is
* behind the viewer)
*
* Replaces the current matrix with an orthographic projection matrix.
@ -430,13 +428,13 @@ cogl_matrix_stack_get_inverse (CoglMatrixStack *stack,
* Gets a reference to the current transform represented by a
* #CoglMatrixEntry pointer.
*
* <note>The transform represented by a #CoglMatrixEntry is
* immutable.</note>
* The transform represented by a #CoglMatrixEntry is
* 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
* 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
* representing the current matrix stack transform.
@ -463,8 +461,8 @@ cogl_matrix_stack_get_entry (CoglMatrixStack *stack);
* if the function returns %NULL then @matrix will be initialized
* to match the current transform of @stack.
*
* <note>@matrix will be left untouched if a direct pointer is
* returned.</note>
* @matrix will be left untouched if a direct pointer is
* returned.
*
* Return value: A direct pointer to the current transform or %NULL
* and in that case @matrix will be initialized with
@ -494,8 +492,8 @@ cogl_matrix_stack_get (CoglMatrixStack *stack,
* if the function returns %NULL then @matrix will be initialized
* to match the transform of @entry.
*
* <note>@matrix will be left untouched if a direct pointer is
* returned.</note>
* @matrix will be left untouched if a direct pointer is
* returned.
*
* Return value: A direct pointer to a #graphene_matrix_t transform or %NULL
* and in that case @matrix will be initialized with
@ -570,9 +568,9 @@ cogl_matrix_entry_is_identity (CoglMatrixEntry *entry);
* Compares two arbitrary #CoglMatrixEntry transforms for equality
* returning %TRUE if they are equal or %FALSE otherwise.
*
* <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
* cheaper too.</note>
* cheaper too.
*
* Return value: %TRUE if @entry0 represents the same transform as
* @entry1, otherwise %FALSE.

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

@ -44,12 +44,12 @@ G_BEGIN_DECLS
* low-level textures like #CoglTexture2D.
*
* Cogl helps to make it easy to deal with high level textures such
* as #CoglAtlasTexture<!-- -->s, #CoglSubTexture<!-- -->s,
* as `CoglAtlasTexture`s, `CoglSubTexture`s,
* #CoglTexturePixmapX11 textures and #CoglTexture2DSliced textures
* consistently.
*
* A #CoglMetaTexture is a texture that might internally be
* represented by one or more low-level #CoglTexture<!-- -->s
* represented by one or more low-level `CoglTexture`s
* such as #CoglTexture2D. These low-level textures are the only ones
* that a GPU really understands but because applications often want
* more high-level texture abstractions (such as storing multiple
@ -76,17 +76,17 @@ G_BEGIN_DECLS
*
* If you want to develop custom primitive APIs like
* cogl_framebuffer_draw_rectangle() and you want to support drawing
* with #CoglAtlasTexture<!-- -->s or #CoglSubTexture<!-- -->s for
* with `CoglAtlasTexture`s or `CoglSubTexture`s for
* example, then you will need to use this #CoglMetaTexture interface
* to be able to resolve high-level textures into low-level textures
* before drawing with Cogl's low-level drawing APIs such as
* cogl_primitive_draw().
*
* <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
* low-level and meta textures because you may find other references
* 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().
*
* 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.
*/
typedef void (*CoglMetaTextureCallback) (CoglTexture *sub_texture,
@ -150,10 +150,10 @@ typedef void (*CoglMetaTextureCallback) (CoglTexture *sub_texture,
* internally use this API to resolve the low level textures of any
* meta textures you have associated with CoglPipeline layers.
*
* <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
* 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
* 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
* 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
* #CoglTexture2DSliced.</note>
* #CoglTexture2DSliced.
*
* The storage for the framebuffer is actually allocated lazily
* 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
* 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
* being redundant to use the cogl_framebuffer_resolve_samples() and
* cogl_framebuffer_resolve_samples_region() apis with single-sample
* rendering.</note>
* rendering.
*/
COGL_EXPORT void
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
* 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
* requests e.g. to show an already visible window. This also means
* that it's acceptable to alternatively use native APIs to show and
* hide windows without confusing Cogl.</note>
* hide windows without confusing Cogl.
*/
COGL_EXPORT void
cogl_onscreen_show (CoglOnscreen *onscreen);
@ -135,11 +135,11 @@ cogl_onscreen_show (CoglOnscreen *onscreen);
* This function does not implicitly allocate the given @onscreen
* framebuffer before hiding it.
*
* <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
* requests e.g. to show an already visible window. This also means
* that it's acceptable to alternatively use native APIs to show and
* hide windows without confusing Cogl.</note>
* hide windows without confusing Cogl.
*/
COGL_EXPORT void
cogl_onscreen_hide (CoglOnscreen *onscreen);
@ -156,11 +156,11 @@ cogl_onscreen_hide (CoglOnscreen *onscreen);
* start a new frame that incrementally builds on the contents of the previous
* frame.
*
* <note>It is highly recommended that applications use
* It is highly recommended that applications use
* cogl_onscreen_swap_buffers_with_damage() instead whenever possible
* and also use the cogl_onscreen_get_buffer_age() api so they can
* perform incremental updates to older buffers instead of having to
* render a full buffer for every frame.</note>
* render a full buffer for every frame.
*/
COGL_EXPORT void
cogl_onscreen_swap_buffers (CoglOnscreen *onscreen,
@ -189,10 +189,10 @@ cogl_onscreen_swap_buffers (CoglOnscreen *onscreen,
*
* The queried value remains valid until the next buffer swap.
*
* <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
* 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
* build up a circular buffer of length 3 for tracking damage regions
@ -202,14 +202,14 @@ cogl_onscreen_swap_buffers (CoglOnscreen *onscreen,
* everything that must be redrawn to update the old contents for the
* new frame.
*
* <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
* 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
* 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
* contents are undefined.
@ -278,9 +278,9 @@ cogl_onscreen_queue_damage_region (CoglOnscreen *onscreen,
* function instead of cogl_onscreen_swap_buffers() to improve
* performance when running under a compositor.
*
* <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
* perform incremental rendering based on old back buffers.</note>
* perform incremental rendering based on old back buffers.
*/
COGL_EXPORT void
cogl_onscreen_swap_buffers_with_damage (CoglOnscreen *onscreen,
@ -354,9 +354,9 @@ cogl_onscreen_swap_region (CoglOnscreen *onscreen,
* opportunity to collect statistics about a frame since the
* #CoglFrameInfo should hold the most data at this point.
*
* <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
* a particular frame before they can start a new frame.</note>
* a particular frame before they can start a new frame.
*/
typedef enum _CoglFrameEvent
{

118
cogl/cogl/cogl-pipeline-layer-state.h
View file

@ -140,8 +140,8 @@ typedef enum
* explicitly specify the type of default texture required, use
* cogl_pipeline_set_layer_null_texture() instead.
*
* <note>In the future, we may define other types of pipeline layers, such
* as purely GLSL based layers.</note>
* In the future, we may define other types of pipeline layers, such
* as purely GLSL based layers.
*/
COGL_EXPORT void
cogl_pipeline_set_layer_texture (CoglPipeline *pipeline,
@ -193,88 +193,64 @@ cogl_pipeline_remove_layer (CoglPipeline *pipeline,
* cogl_pipeline_set_layer_combine:
* @pipeline: A #CoglPipeline object
* @layer_index: Specifies the layer you want define a combine function for
* @blend_string: A <link linkend="cogl-Blend-Strings">Cogl blend string</link>
* describing the desired texture combine function.
* @blend_string: A Cogl blend string describing the desired
* texture combine function.
* @error: A #GError that may report parse errors or lack of GPU/driver
* support. May be %NULL, in which case a warning will be printed out if an
* error is encountered.
*
* If not already familiar; you can refer
* <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:
* <itemizedlist>
* <listitem>REPLACE(arg0) = arg0</listitem>
* <listitem>MODULATE(arg0, arg1) = arg0 x arg1</listitem>
* <listitem>ADD(arg0, arg1) = arg0 + arg1</listitem>
* <listitem>ADD_SIGNED(arg0, arg1) = arg0 + arg1 - 0.5</listitem>
* <listitem>INTERPOLATE(arg0, arg1, arg2) = arg0 x arg2 + arg1 x (1 - arg2)</listitem>
* <listitem>SUBTRACT(arg0, arg1) = arg0 - arg1</listitem>
* <listitem>
* <programlisting>
*
* - `REPLACE(arg0) = arg0`
* - `MODULATE(arg0, arg1) = arg0 x arg1`
* - `ADD(arg0, arg1) = arg0 + arg1`
* - `ADD_SIGNED(arg0, arg1) = arg0 + arg1 - 0.5`
* - `INTERPOLATE(arg0, arg1, arg2) = arg0 x arg2 + arg1 x (1 - arg2)`
* - `SUBTRACT(arg0, arg1) = arg0 - arg1`
* -
* ```
* DOT3_RGB(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) +
* (arg0[G] - 0.5)) * (arg1[G] - 0.5) +
* (arg0[B] - 0.5)) * (arg1[B] - 0.5))
* </programlisting>
* </listitem>
* <listitem>
* <programlisting>
* ```
* -
* ```
* DOT3_RGBA(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) +
* (arg0[G] - 0.5)) * (arg1[G] - 0.5) +
* (arg0[B] - 0.5)) * (arg1[B] - 0.5))
* </programlisting>
* </listitem>
* </itemizedlist>
* ```
*
* Refer to the
* <link linkend="cogl-Blend-String-syntax">color-source syntax</link> for
* describing the arguments. The valid source names for texture combining
* are:
* <variablelist>
* <varlistentry>
* <term>TEXTURE</term>
* <listitem>Use the color from the current texture layer</listitem>
* </varlistentry>
* <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
* The valid source names for texture combining are:
*
* - `TEXTURE`: Use the color from the current texture layer
* - `TEXTURE_0, TEXTURE_1, etc`: Use the color from the specified texture layer
* - `CONSTANT`: Use the color from the constant given with
* [method@Cogl.Pipeline.set_layer_combine_constant]
* - `PRIMARY`: Use the color of the pipeline as set with
* [method@Cogl.Pipeline.set_color]
* - `PREVIOUS`: Either use the texture color from the previous layer, or
* if this is layer 0, use the color of the pipeline as set with
* cogl_pipeline_set_color()</listitem>
* </varlistentry>
* </variablelist>
* [method@Cogl.Pipeline.set_color]
*
* Layer Combine Examples:
*
* This is effectively what the default blending is:
*
* ```
* RGBA = MODULATE (PREVIOUS, TEXTURE)
* ```
*
* This could be used to cross-fade between two images, using
* the alpha component of a constant as the interpolator. The constant
* color is given by calling [method@Cogl.Pipeline.set_layer_combine_constant].
*
* ```
* RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])
* ```
*
* <refsect2 id="cogl-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
* with blending.</note>
* You can't give a multiplication factor for arguments as you can
* with blending.
*
* Return value: %TRUE if the blend string was successfully parsed, and the
* described texture combining is supported by the underlying driver and
@ -352,10 +328,10 @@ cogl_pipeline_get_layer_filters (CoglPipeline *pipeline,
* Changes the decimation and interpolation filters used when a texture is
* drawn at other scales than 100%.
*
* <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
* 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_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
* 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
* applied on top of its parent. Copying a pipeline creates an empty
* diff and a child->parent relationship between the empty diff and
@ -617,7 +617,7 @@ _cogl_get_n_args_for_combine_func (CoglPipelineCombineFunc func);
*
* This is the recommended coding pattern for validating an input
* pipeline and caching a derived result:
* |[
* ```c
* static GQuark _cogl_my_cache_key = 0;
*
* typedef struct {
@ -673,7 +673,7 @@ _cogl_get_n_args_for_combine_func (CoglPipelineCombineFunc func);
*
* return cache->validated_source;
* }
* ]|
* ```
*/
CoglPipeline *
_cogl_pipeline_weak_copy (CoglPipeline *pipeline,

68
cogl/cogl/cogl-pipeline-state.h
View file

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

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
* 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
* 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.
*
* Note that CoglPollFD is deliberately exactly the same as struct
@ -115,7 +115,7 @@ typedef struct {
* cogl_poll_renderer_get_info:
* @renderer: A #CoglRenderer
* @poll_fds: A return location for a pointer to an array
* of #CoglPollFD<!-- -->s
* of `CoglPollFD`s
* @n_poll_fds: A return location for the number of entries in *@poll_fds
* @timeout: A return location for the maximum length of time to wait
* in microseconds, or -1 to wait indefinitely.
@ -126,9 +126,9 @@ typedef struct {
* that Cogl has a chance to describe what file descriptor events it
* needs to be woken up for.
*
* <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
* 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
* an array of #CoglPollFD structs describing the file descriptors
@ -140,7 +140,7 @@ typedef struct {
*
* When the application mainloop returns from calling poll(2) (or its
* equivalent) then it should call cogl_poll_renderer_dispatch()
* passing a pointer the array of CoglPollFD<!-- -->s with updated
* passing a pointer the array of `CoglPollFD`s with updated
* revent values.
*
* @timeout will contain a maximum amount of time to wait in
@ -165,7 +165,7 @@ cogl_poll_renderer_get_info (CoglRenderer *renderer,
/**
* cogl_poll_renderer_dispatch:
* @renderer: A #CoglRenderer
* @poll_fds: An array of #CoglPollFD<!-- -->s describing the events
* @poll_fds: An array of `CoglPollFD`s describing the events
* that have occurred since the application went idle.
* @n_poll_fds: The length of the @poll_fds array.
*
@ -176,10 +176,6 @@ cogl_poll_renderer_get_info (CoglRenderer *renderer,
* file descriptors that Cogl didn't request when calling
* cogl_poll_renderer_get_info() or a shorter array missing some file
* descriptors that Cogl requested.
*
* <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_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
* @...: 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
* drawn later with no addition information required.
*
* 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
* the number of vertices to read when drawing.
*
@ -226,12 +226,12 @@ cogl_primitive_new (CoglVerticesMode mode,
* @attributes: An array of CoglAttribute
* @n_attributes: The number of attributes
*
* Combines a set of #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
* drawn later with no addition information required.
*
* 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
* the number of vertices to read when drawing.
*
@ -258,7 +258,7 @@ cogl_primitive_new_with_attributes (CoglVerticesMode mode,
* attribute with a #CoglAttribute and upload your data.
*
* For example to draw a convex polygon you can do:
* |[
* ```c
* CoglVertexP2 triangle[] =
* {
* { 0, 300 },
@ -268,21 +268,21 @@ cogl_primitive_new_with_attributes (CoglVerticesMode mode,
* prim = cogl_primitive_new_p2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
* ]|
* ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if
* #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
* <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
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
* </note>
*
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@ -308,7 +308,7 @@ cogl_primitive_new_p2 (CoglContext *context,
* attribute with a #CoglAttribute and upload your data.
*
* For example to draw a convex polygon you can do:
* |[
* ```c
* CoglVertexP3 triangle[] =
* {
* { 0, 300, 0 },
@ -318,21 +318,21 @@ cogl_primitive_new_p2 (CoglContext *context,
* prim = cogl_primitive_new_p3 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
* ]|
* ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if
* #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
* <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
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
* </note>
*
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@ -355,12 +355,12 @@ cogl_primitive_new_p3 (CoglContext *context,
* Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position
* and color attributes with #CoglAttribute<!-- -->s and upload
* and color attributes with `CoglAttribute`s and upload
* your data.
*
* For example to draw a convex polygon with a linear gradient you
* can do:
* |[
* ```c
* CoglVertexP2C4 triangle[] =
* {
* { 0, 300, 0xff, 0x00, 0x00, 0xff },
@ -370,21 +370,21 @@ cogl_primitive_new_p3 (CoglContext *context,
* prim = cogl_primitive_new_p2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
* ]|
* ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if
* #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
* <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
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
* </note>
*
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@ -407,12 +407,12 @@ cogl_primitive_new_p2c4 (CoglContext *context,
* Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position
* and color attributes with #CoglAttribute<!-- -->s and upload
* and color attributes with `CoglAttribute`s and upload
* your data.
*
* For example to draw a convex polygon with a linear gradient you
* can do:
* |[
* ```c
* CoglVertexP3C4 triangle[] =
* {
* { 0, 300, 0, 0xff, 0x00, 0x00, 0xff },
@ -422,21 +422,21 @@ cogl_primitive_new_p2c4 (CoglContext *context,
* prim = cogl_primitive_new_p3c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
* ]|
* ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if
* #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
* <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
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
* </note>
*
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@ -459,12 +459,12 @@ cogl_primitive_new_p3c4 (CoglContext *context,
* Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position and
* texture coordinate attributes with #CoglAttribute<!-- -->s and
* texture coordinate attributes with `CoglAttribute`s and
* upload your data.
*
* For example to draw a convex polygon with texture mapping you can
* do:
* |[
* ```c
* CoglVertexP2T2 triangle[] =
* {
* { 0, 300, 0.0, 1.0},
@ -474,21 +474,21 @@ cogl_primitive_new_p3c4 (CoglContext *context,
* prim = cogl_primitive_new_p2t2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
* ]|
* ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if
* #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
* <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
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
* </note>
*
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@ -511,12 +511,12 @@ cogl_primitive_new_p2t2 (CoglContext *context,
* Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position and
* texture coordinate attributes with #CoglAttribute<!-- -->s and
* texture coordinate attributes with `CoglAttribute`s and
* upload your data.
*
* For example to draw a convex polygon with texture mapping you can
* do:
* |[
* ```c
* CoglVertexP3T2 triangle[] =
* {
* { 0, 300, 0, 0.0, 1.0},
@ -526,21 +526,21 @@ cogl_primitive_new_p2t2 (CoglContext *context,
* prim = cogl_primitive_new_p3t2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
* ]|
* ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if
* #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
* <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
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
* </note>
*
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@ -563,12 +563,12 @@ cogl_primitive_new_p3t2 (CoglContext *context,
* Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position, texture
* coordinate and color attributes with #CoglAttribute<!-- -->s and
* coordinate and color attributes with `CoglAttribute`s and
* upload your data.
*
* For example to draw a convex polygon with texture mapping and a
* linear gradient you can do:
* |[
* ```c
* CoglVertexP2T2C4 triangle[] =
* {
* { 0, 300, 0.0, 1.0, 0xff, 0x00, 0x00, 0xff},
@ -578,21 +578,21 @@ cogl_primitive_new_p3t2 (CoglContext *context,
* prim = cogl_primitive_new_p2t2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
* ]|
* ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if
* #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
* <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
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
* </note>
*
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@ -615,12 +615,12 @@ cogl_primitive_new_p2t2c4 (CoglContext *context,
* Provides a convenient way to describe a primitive, such as a single
* triangle strip or a triangle fan, that will internally allocate the
* necessary #CoglAttributeBuffer storage, describe the position, texture
* coordinate and color attributes with #CoglAttribute<!-- -->s and
* coordinate and color attributes with `CoglAttribute`s and
* upload your data.
*
* For example to draw a convex polygon with texture mapping and a
* linear gradient you can do:
* |[
* ```c
* CoglVertexP3T2C4 triangle[] =
* {
* { 0, 300, 0, 0.0, 1.0, 0xff, 0x00, 0x00, 0xff},
@ -630,21 +630,21 @@ cogl_primitive_new_p2t2c4 (CoglContext *context,
* prim = cogl_primitive_new_p3t2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
* 3, triangle);
* cogl_primitive_draw (prim);
* ]|
* ```
*
* The value passed as @n_vertices is initially used to determine how
* much can be read from @data but it will also be used to update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if
* #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to read when drawing.
* <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
* so that implies multiple primitives need to be submitted). If your
* hardware doesn't support non-power of two textures (For example you
* are using GLES 1.1) then you will need to make sure your assets are
* resized to a power-of-two size (though they don't have to be square)
* </note>
*
*
* Return value: (transfer full): A newly allocated #CoglPrimitive
* with a reference of 1. This can be freed using g_object_unref().
@ -674,9 +674,9 @@ cogl_primitive_set_first_vertex (CoglPrimitive *primitive,
* number of vertices to read can also be phrased as the number
* of indices to read.
*
* <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
* of vertices to read and draw.</note>
* of vertices to read and draw.
*
* Returns: The number of vertices to read when drawing.
*/
@ -694,9 +694,9 @@ cogl_primitive_get_n_vertices (CoglPrimitive *primitive);
* Usually this value is set implicitly when associating vertex data
* or indices with a #CoglPrimitive.
*
* <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
* of vertices to read and draw.</note>
* of vertices to read and draw.
*/
COGL_EXPORT void
cogl_primitive_set_n_vertices (CoglPrimitive *primitive,
@ -725,14 +725,14 @@ cogl_primitive_set_mode (CoglPrimitive *primitive,
* shared data multiple times instead of duplicating the data.
*
* The value passed as @n_indices will simply update the
* #CoglPrimitive <structfield>n_vertices</structfield> property as if
* #CoglPrimitive `n_vertices` property as if
* cogl_primitive_set_n_vertices() were called. This property defines
* the number of vertices to draw or, put another way, how many
* indices should be read from @indices when drawing.
*
* <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
* indices to start drawing from.</note>
* indices to start drawing from.
*/
COGL_EXPORT void
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
* #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
* #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.
*/
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
*
* #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
* by OpenGL on programmable hardware to provide a more flexible
* description of what should be rendered. A description of GLSL
@ -61,38 +61,20 @@ G_BEGIN_DECLS
* the pipeline at a particular point. The code is split into four
* separate strings (all of which are optional):
*
* <glosslist>
* <glossentry>
* <glossterm>declarations</glossterm>
* <glossdef><para>
* - `declarations`
* The code in this string will be inserted outside of any function in
* the global scope of the shader. This can be used to declare
* uniforms, attributes, varyings and functions to be used by the
* snippet.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>pre</glossterm>
* <glossdef><para>
* - `pre`
* The code in this string will be inserted before the hook point.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>post</glossterm>
* <glossdef><para>
* - `post`
* The code in this string will be inserted after the hook point. This
* can be used to modify the results of the builtin generated code for
* that hook point.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>replace</glossterm>
* <glossdef><para>
* - `replace
* If present the code in this string will replace the generated code
* for the hook point.
* </para></glossdef>
* </glossentry>
* </glosslist>
*
* All of the strings apart from the declarations string of a pipeline
* are generated in a single function so they can share variables
@ -120,174 +102,76 @@ G_BEGIN_DECLS
* names under the cogl_* namespace which can be used instead. These
* are:
*
* <glosslist>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_modelview_matrix</emphasis></glossterm>
* <glossdef><para>
* - `uniform mat4 cogl_modelview_matrix
* The current modelview matrix. This is equivalent to
* #gl_ModelViewMatrix.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_projection_matrix</emphasis></glossterm>
* <glossdef><para>
* - `uniform mat4 cogl_projection_matrix
* The current projection matrix. This is equivalent to
* #gl_ProjectionMatrix.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_modelview_projection_matrix</emphasis></glossterm>
* <glossdef><para>
* - `uniform mat4 cogl_modelview_projection_matrix
* The combined modelview and projection matrix. A vertex shader
* would typically use this to transform the incoming vertex
* position. The separate modelview and projection matrices are
* usually only needed for lighting calculations. This is
* equivalent to #gl_ModelViewProjectionMatrix.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_texture_matrix</emphasis>[]</glossterm>
* <glossdef><para>
* - `uniform mat4 cogl_texture_matrix[]
* An array of matrices for transforming the texture
* coordinates. This is equivalent to #gl_TextureMatrix.
* </para></glossdef>
* </glossentry>
* </glosslist>
*
* In a vertex shader, the following are also available:
*
* <glosslist>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_position_in</emphasis></glossterm>
* <glossdef><para>
* - `attribute vec4 cogl_position_in
* The incoming vertex position. This is equivalent to #gl_Vertex.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_color_in</emphasis></glossterm>
* <glossdef><para>
* - `attribute vec4 cogl_color_in`
* The incoming vertex color. This is equivalent to #gl_Color.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_tex_coord_in</emphasis></glossterm>
* <glossdef><para>
* - `attribute vec4 cogl_tex_coord_in`
* The texture coordinate for layer 0. This is an alternative name
* for #cogl_tex_coord0_in.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_tex_coord0_in</emphasis></glossterm>
* <glossdef><para>
* - `attribute vec4 cogl_tex_coord0_in
* The texture coordinate for the layer 0. This is equivalent to
* #gl_MultiTexCoord0. There will also be #cogl_tex_coord1_in and
* so on if more layers are added to the pipeline.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>attribute vec3
* <emphasis>cogl_normal_in</emphasis></glossterm>
* <glossdef><para>
* - `attribute vec3 cogl_normal_in`
* The normal of the vertex. This is equivalent to #gl_Normal.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>vec4
* <emphasis>cogl_position_out</emphasis></glossterm>
* <glossdef><para>
* - `vec4 cogl_position_out
* The calculated position of the vertex. This must be written to
* in all vertex shaders. This is equivalent to #gl_Position.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>float
* <emphasis>cogl_point_size_in</emphasis></glossterm>
* <glossdef><para>
* - `float cogl_point_size_in
* The incoming point size from the cogl_point_size_in attribute.
* This is only available if
* cogl_pipeline_set_per_vertex_point_size() is set on the
* pipeline.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>float
* <emphasis>cogl_point_size_out</emphasis></glossterm>
* <glossdef><para>
* - `float cogl_point_size_out`
* The calculated size of a point. This is equivalent to #gl_PointSize.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>varying vec4
* <emphasis>cogl_color_out</emphasis></glossterm>
* <glossdef><para>
* - `varying vec4 cogl_color_out`
* The calculated color of a vertex. This is equivalent to #gl_FrontColor.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>varying vec4
* <emphasis>cogl_tex_coord0_out</emphasis></glossterm>
* <glossdef><para>
* - `varying vec4 cogl_tex_coord0_out`
* The calculated texture coordinate for layer 0 of the pipeline.
* This is equivalent to #gl_TexCoord[0]. There will also be
* #cogl_tex_coord1_out and so on if more layers are added to the
* pipeline. In the fragment shader, this varying is called
* #cogl_tex_coord0_in.
* </para></glossdef>
* </glossentry>
* </glosslist>
*
* In a fragment shader, the following are also available:
*
* <glosslist>
* <glossentry>
* <glossterm>varying vec4 <emphasis>cogl_color_in</emphasis></glossterm>
* <glossdef><para>
* - `varying vec4 cogl_color_in`
* The calculated color of a vertex. This is equivalent to #gl_FrontColor.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>varying vec4
* <emphasis>cogl_tex_coord0_in</emphasis></glossterm>
* <glossdef><para>
* - `varying vec4 cogl_tex_coord0_in`
* The texture coordinate for layer 0. This is equivalent to
* #gl_TexCoord[0]. There will also be #cogl_tex_coord1_in and so
* on if more layers are added to the pipeline.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>vec4 <emphasis>cogl_color_out</emphasis></glossterm>
* <glossdef><para>
* - `vec4 cogl_color_out`
* The final calculated color of the fragment. All fragment shaders
* must write to this variable. This is equivalent to
* #gl_FrontColor.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>float <emphasis>cogl_depth_out</emphasis></glossterm>
* <glossdef><para>
* - `float cogl_depth_out`
* An optional output variable specifying the depth value to use
* for this fragment. This is equivalent to #gl_FragDepth.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>bool <emphasis>cogl_front_facing</emphasis></glossterm>
* <glossdef><para>
* - `bool cogl_front_facing`
* A readonly variable that will be true if the current primitive
* is front facing. This can be used to implement two-sided
* coloring algorithms. This is equivalent to #gl_FrontFacing.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>vec2 <emphasis>cogl_point_coord</emphasis></glossterm>
* <glossdef><para>
* - `vec2 cogl_point_coord`
* When rendering points, this will contain a vec2 which represents
* the position within the point of the current fragment.
* vec2(0.0,0.0) will be the topleft of the point and vec2(1.0,1.0)
@ -295,9 +179,6 @@ G_BEGIN_DECLS
* Cogl where when rendering to an offscreen buffer these
* coordinates will be upside-down. The value is undefined when not
* rendering points.
* </para></glossdef>
* </glossentry>
* </glosslist>
*
* Here is an example of using a snippet to add a desaturate effect to the
* generated color on a pipeline.
@ -377,97 +258,70 @@ G_DECLARE_FINAL_TYPE (CoglSnippet,
* #CoglPipeline where the code of the snippet should be used when it
* is attached to a pipeline.
*
* <glosslist>
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_VERTEX_GLOBALS</glossterm>
* <glossdef>
* <para>
* - `COGL_SNIPPET_HOOK_VERTEX_GLOBALS`
*
* Adds a shader snippet at the beginning of the global section of the
* shader for the vertex processing. Any declarations here can be
* shared with all other snippets that are attached to a vertex hook.
* Only the ‘declarations’ string is used and the other strings are
* ignored.
* </para>
* </glossdef>
* </glossentry>
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_FRAGMENT_GLOBALS</glossterm>
* <glossdef>
* <para>
*
* - `COGL_SNIPPET_HOOK_FRAGMENT_GLOBALS`
*
* Adds a shader snippet at the beginning of the global section of the
* shader for the fragment processing. Any declarations here can be
* shared with all other snippets that are attached to a fragment
* hook. Only the ‘declarations’ string is used and the other strings
* are ignored.
* </para>
* </glossdef>
* </glossentry>
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_VERTEX</glossterm>
* <glossdef>
* <para>
*
* - `COGL_SNIPPET_HOOK_VERTEX`
*
* Adds a shader snippet that will hook on to the vertex processing
* stage of the pipeline. This gives a chance for the application to
* modify the vertex attributes generated by the shader. Typically the
* snippet will modify cogl_color_out or cogl_position_out builtins.
* </para>
* <para>
*
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
* </para>
* <para>
*
* The ‘pre’ string in @snippet will be inserted at the top of the
* main() function before any vertex processing is done.
* </para>
* <para>
*
* The ‘replace’ string in @snippet will be used instead of the
* generated vertex processing if it is present. This can be used if
* the application wants to provide a complete vertex shader and
* doesn't need the generated output from Cogl.
* </para>
* <para>
*
* The ‘post’ string in @snippet will be inserted after all of the
* standard vertex processing is done. This can be used to modify the
* outputs.
* </para>
* </glossdef>
* </glossentry>
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_VERTEX_TRANSFORM</glossterm>
* <glossdef>
* <para>
*
* - `COGL_SNIPPET_HOOK_VERTEX_TRANSFORM`
*
* Adds a shader snippet that will hook on to the vertex transform stage.
* Typically the snippet will use the cogl_modelview_matrix,
* cogl_projection_matrix and cogl_modelview_projection_matrix matrices and the
* cogl_position_in attribute. The hook must write to cogl_position_out.
* The default processing for this hook will multiply cogl_position_in by
* the combined modelview-projection matrix and store it on cogl_position_out.
* </para>
* <para>
*
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
* </para>
* <para>
*
* The ‘pre’ string in @snippet will be inserted at the top of the
* main() function before the vertex transform is done.
* </para>
* <para>
*
* The ‘replace’ string in @snippet will be used instead of the
* generated vertex transform if it is present.
* </para>
* <para>
*
* The ‘post’ string in @snippet will be inserted after all of the
* standard vertex transformation is done. This can be used to modify the
* cogl_position_out in addition to the default processing.
* </para>
* </glossdef>
* </glossentry>
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_POINT_SIZE</glossterm>
* <glossdef>
* <para>
*
* - `COGL_SNIPPET_HOOK_POINT_SIZE`
*
* Adds a shader snippet that will hook on to the point size
* calculation step within the vertex shader stage. The snippet should
* write to the builtin cogl_point_size_out with the new point size.
@ -476,69 +330,52 @@ G_DECLARE_FINAL_TYPE (CoglSnippet,
* that would be set by a previous snippet. Note that this hook is
* only used if cogl_pipeline_set_per_vertex_point_size() is enabled
* on the pipeline.
* </para>
* <para>
*
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
* </para>
* <para>
*
* The ‘pre’ string in @snippet will be inserted just before
* calculating the point size.
* </para>
* <para>
*
* The ‘replace’ string in @snippet will be used instead of the
* generated point size calculation if it is present.
* </para>
* <para>
*
* The ‘post’ string in @snippet will be inserted after the
* standard point size calculation is done. This can be used to modify
* cogl_point_size_out in addition to the default processing.
* </para>
* </glossdef>
* </glossentry>
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_FRAGMENT</glossterm>
* <glossdef>
* <para>
*
* - `COGL_SNIPPET_HOOK_FRAGMENT`
*
* Adds a shader snippet that will hook on to the fragment processing
* stage of the pipeline. This gives a chance for the application to
* modify the fragment color generated by the shader. Typically the
* snippet will modify cogl_color_out.
* </para>
* <para>
*
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
* </para>
* <para>
*
* The ‘pre’ string in @snippet will be inserted at the top of the
* main() function before any fragment processing is done.
* </para>
* <para>
*
* The ‘replace’ string in @snippet will be used instead of the
* generated fragment processing if it is present. This can be used if
* the application wants to provide a complete fragment shader and
* doesn't need the generated output from Cogl.
* </para>
* <para>
*
* The ‘post’ string in @snippet will be inserted after all of the
* standard fragment processing is done. At this point the generated
* value for the rest of the pipeline state will already be in
* cogl_color_out so the application can modify the result by altering
* this variable.
* </para>
* </glossdef>
* </glossentry>
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_TEXTURE_COORD_TRANSFORM</glossterm>
* <glossdef>
* <para>
*
* - `COGL_SNIPPET_HOOK_TEXTURE_COORD_TRANSFORM`
*
* Adds a shader snippet that will hook on to the texture coordinate
* transformation of a particular layer. This can be used to replace
* the processing for a layer or to modify the results.
* </para>
* <para>
*
* Within the snippet code for this hook there are two extra
* variables. The first is a mat4 called cogl_matrix which represents
* the user matrix for this layer. The second is called cogl_tex_coord
@ -549,76 +386,57 @@ G_DECLARE_FINAL_TYPE (CoglSnippet,
* varying to the fragment processing stage. The default code will
* just multiply cogl_matrix by cogl_tex_coord and store the result in
* cogl_tex_coord.
* </para>
* <para>
*
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
* </para>
* <para>
*
* The ‘pre’ string in @snippet will be inserted just before the
* fragment processing for this layer. At this point cogl_tex_coord
* still contains the value of the texture coordinate attribute.
* </para>
* <para>
* If a ‘replace’ string is given then this will be used instead of
* the default fragment processing for this layer. The snippet can
* modify cogl_tex_coord or leave it as is to apply no transformation.
* </para>
* <para>
*
* The ‘post’ string in @snippet will be inserted just after the
* transformation. At this point cogl_tex_coord will contain the
* results of the transformation but it can be further modified by the
* snippet.
* </para>
* </glossdef>
* </glossentry>
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_LAYER_FRAGMENT</glossterm>
* <glossdef>
* <para>
*
* - `COGL_SNIPPET_HOOK_LAYER_FRAGMENT`
*
* Adds a shader snippet that will hook on to the fragment processing
* of a particular layer. This can be used to replace the processing
* for a layer or to modify the results.
* </para>
* <para>
*
* Within the snippet code for this hook there is an extra vec4
* variable called ‘cogl_layer’. This contains the resulting color
* that will be used for the layer. This can be modified in the ‘post’
* section or it the default processing can be replaced entirely using
* the ‘replace’ section.
* </para>
* <para>
*
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
* </para>
* <para>
*
* The ‘pre’ string in @snippet will be inserted just before the
* fragment processing for this layer.
* </para>
* <para>
*
* If a ‘replace’ string is given then this will be used instead of
* the default fragment processing for this layer. The snippet must write to
* the ‘cogl_layer’ variable in that case.
* </para>
* <para>
*
* The ‘post’ string in @snippet will be inserted just after the
* fragment processing for the layer. The results can be modified by changing
* the value of the ‘cogl_layer’ variable.
* </para>
* </glossdef>
* </glossentry>
* <glossentry>
* <glossterm>%COGL_SNIPPET_HOOK_TEXTURE_LOOKUP</glossterm>
* <glossdef>
* <para>
*
* - `COGL_SNIPPET_HOOK_TEXTURE_LOOKUP`
*
* Adds a shader snippet that will hook on to the texture lookup part
* of a given layer. This gives a chance for the application to modify
* the coordinates that will be used for the texture lookup or to
* alter the returned texel.
* </para>
* <para>
*
* Within the snippet code for this hook there are three extra
* variables available. ‘cogl_sampler’ is a sampler object
* representing the sampler for the layer where the snippet is
@ -626,30 +444,22 @@ G_DECLARE_FINAL_TYPE (CoglSnippet,
* coordinates that will be used for the texture lookup. This can be
* modified. ‘cogl_texel’ will contain the result of the texture
* lookup. This can also be modified.
* </para>
* <para>
*
* The ‘declarations’ string in @snippet will be inserted in the
* global scope of the shader. Use this to declare any uniforms,
* attributes or functions that the snippet requires.
* </para>
* <para>
*
* The ‘pre’ string in @snippet will be inserted at the top of the
* main() function before any fragment processing is done. This is a
* good place to modify the cogl_tex_coord variable.
* </para>
* <para>
*
* If a ‘replace’ string is given then this will be used instead of a
* the default texture lookup. The snippet would typically use its own
* sampler in this case.
* </para>
* <para>
*
* The ‘post’ string in @snippet will be inserted after texture lookup
* has been performed. Here the snippet can modify the cogl_texel
* variable to alter the returned texel.
* </para>
* </glossdef>
* </glossentry>
* </glosslist>
*/
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
* 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
* #CoglMetaTexture interface then you need to use the
* #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
* 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
* 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
* @max_waste value is given. If the given virtual texture size size
* is larger than is supported by the hardware but slicing is disabled
* the texture size would be too large to handle.</note>
* the texture size would be too large to handle.
*
* Returns: (transfer full): A new #CoglTexture2DSliced object with no storage
* allocated yet.
@ -159,7 +159,7 @@ cogl_texture_2d_sliced_new_with_size (CoglContext *ctx,
* wasted padding at the bottom and right of the textures is less than
* specified. A negative @max_waste will disable slicing.
*
* <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
* @data pointer does not need to remain valid once this function
* returns. This means it is not possible to configure the texture
@ -168,13 +168,13 @@ cogl_texture_2d_sliced_new_with_size (CoglContext *ctx,
* for example) then you can instead create a #CoglBitmap for your
* data and use cogl_texture_2d_sliced_new_from_bitmap() or use
* cogl_texture_2d_sliced_new_with_size() and then upload data using
* cogl_texture_set_data()</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
* value is given. If the given virtual texture size is larger than is
* supported by the hardware but slicing is disabled the texture size
* would be too large to handle.</note>
* would be too large to handle.
*
* Return value: (transfer full): A newly created #CoglTexture2DSliced
* or %NULL on failure and @error will be updated.
@ -219,11 +219,11 @@ cogl_texture_2d_sliced_new_from_data (CoglContext *ctx,
* allocate the underlying storage or let Cogl automatically allocate
* storage lazily.
*
* <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
* @max_waste value is given. If the given virtual texture size is
* larger than is supported by the hardware but slicing is disabled
* the texture size would be too large to handle.</note>
* the texture size would be too large to handle.
*
* Return value: (transfer full): A newly created #CoglTexture2DSliced
* or %NULL on failure and @error will be updated.

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

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.
*
* <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
* 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
*/
@ -328,7 +328,7 @@ cogl_texture_get_data (CoglTexture *texture,
* Sets the pixels in a rectangular subregion of @texture from an in-memory
* buffer containing pixel data.
*
* <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
* %FALSE otherwise
@ -374,16 +374,16 @@ cogl_texture_set_region (CoglTexture *texture,
* fraction then round the number down (floor()), but clamp to 1
* something like this:
*
* |[
* ```
* next_width = MAX (1, floor (prev_width));
* ]|
* ```
*
* You can determine the number of mipmap levels for a given texture
* like this:
*
* |[
* ```
* n_levels = 1 + floor (log2 (max_dimension));
* ]|
* ```
*
* Where %max_dimension is the larger of cogl_texture_get_width() and
* cogl_texture_get_height().
@ -391,10 +391,10 @@ cogl_texture_set_region (CoglTexture *texture,
* It is an error to pass a @level number >= the number of levels that
* @texture can have according to the above calculation.
*
* <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
* 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
* %FALSE otherwise
@ -423,8 +423,8 @@ cogl_texture_set_data (CoglTexture *texture,
* Copies a specified source region from @bitmap to the position
* (@src_x, @src_y) of the given destination texture @handle.
*
* <note>The region updated can't be larger than the source
* bitmap</note>
* The region updated can't be larger than the source
* bitmap
*
* Return value: %TRUE if the subregion upload was successful, and
* %FALSE otherwise
@ -448,10 +448,10 @@ cogl_texture_set_region_from_bitmap (CoglTexture *texture,
* allows you to be sure that there is enough memory for the
* texture and if not then the error can be handled gracefully.
*
* <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
* 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,
* otherwise %FALSE and @error will be updated if it

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

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

@ -52,9 +52,9 @@ G_BEGIN_DECLS
* as a wrapper around glXGetProcAddress() or whatever is the
* 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
* 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
* function is not available.

139
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:
*
* <tip>
* <glosslist>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_modelview_matrix</emphasis></glossterm>
* <glossdef><para>
* - `uniform mat4 cogl_modelview_matrix`
* The current modelview matrix. This is equivalent to
* #gl_ModelViewMatrix.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_projection_matrix</emphasis></glossterm>
* <glossdef><para>
* - `uniform mat4 cogl_projection_matrix`
* The current projection matrix. This is equivalent to
* #gl_ProjectionMatrix.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_modelview_projection_matrix</emphasis></glossterm>
* <glossdef><para>
* - `uniform mat4 cogl_modelview_projection_matrix`
* The combined modelview and projection matrix. A vertex shader
* would typically use this to transform the incoming vertex
* position. The separate modelview and projection matrices are
* usually only needed for lighting calculations. This is
* equivalent to #gl_ModelViewProjectionMatrix.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>uniform mat4
* <emphasis>cogl_texture_matrix</emphasis>[]</glossterm>
* <glossdef><para>
* - `uniform mat4 cogl_texture_matrix[]`
* An array of matrices for transforming the texture
* coordinates. This is equivalent to #gl_TextureMatrix.
* </para></glossdef>
* </glossentry>
* </glosslist>
* </tip>
*
* In a vertex shader, the following are also available:
*
* <tip>
* <glosslist>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_position_in</emphasis></glossterm>
* <glossdef><para>
* - `attribute vec4 cogl_position_in`
* The incoming vertex position. This is equivalent to #gl_Vertex.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_color_in</emphasis></glossterm>
* <glossdef><para>
* - `attribute vec4 cogl_color_in`
* The incoming vertex color. This is equivalent to #gl_Color.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_tex_coord_in</emphasis></glossterm>
* <glossdef><para>
* - `attribute vec4 cogl_tex_coord_in`
* The texture coordinate for the first texture unit. This is
* equivalent to #gl_MultiTexCoord0.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>attribute vec4
* <emphasis>cogl_tex_coord0_in</emphasis></glossterm>
* <glossdef><para>
* - `attribute vec4 cogl_tex_coord0_in`
* The texture coordinate for the first texture unit. This is
* equivalent to #gl_MultiTexCoord0. There is also
* #cogl_tex_coord1_in and so on.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>attribute vec3
* <emphasis>cogl_normal_in</emphasis></glossterm>
* <glossdef><para>
* - `attribute vec3 cogl_normal_in`
* The normal of the vertex. This is equivalent to #gl_Normal.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>vec4
* <emphasis>cogl_position_out</emphasis></glossterm>
* <glossdef><para>
* - `vec4 cogl_position_out`
* The calculated position of the vertex. This must be written to
* in all vertex shaders. This is equivalent to #gl_Position.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>float
* <emphasis>cogl_point_size_out</emphasis></glossterm>
* <glossdef><para>
* - `float cogl_point_size_out`
* The calculated size of a point. This is equivalent to #gl_PointSize.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>varying vec4
* <emphasis>cogl_color_out</emphasis></glossterm>
* <glossdef><para>
* - `varying vec4 cogl_color_out`
* The calculated color of a vertex. This is equivalent to #gl_FrontColor.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>varying vec4
* <emphasis>cogl_tex_coord_out</emphasis>[]</glossterm>
* <glossdef><para>
* - `varying vec4 cogl_tex_coord_out[]`
* An array of calculated texture coordinates for a vertex. This is
* equivalent to #gl_TexCoord.
* </para></glossdef>
* </glossentry>
* </glosslist>
* </tip>
*
* In a fragment shader, the following are also available:
*
* <tip>
* <glosslist>
* <glossentry>
* <glossterm>varying vec4 <emphasis>cogl_color_in</emphasis></glossterm>
* <glossdef><para>
* - `varying vec4 cogl_color_in`
* The calculated color of a vertex. This is equivalent to #gl_FrontColor.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>varying vec4
* <emphasis>cogl_tex_coord_in</emphasis>[]</glossterm>
* <glossdef><para>
* - `varying vec4 cogl_tex_coord_in[]`
* An array of calculated texture coordinates for a vertex. This is
* equivalent to #gl_TexCoord.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>vec4 <emphasis>cogl_color_out</emphasis></glossterm>
* <glossdef><para>
* - `vec4 cogl_color_out`
* The final calculated color of the fragment. All fragment shaders
* must write to this variable. This is equivalent to
* #gl_FrontColor.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>float <emphasis>cogl_depth_out</emphasis></glossterm>
* <glossdef><para>
* - `float cogl_depth_out`
* An optional output variable specifying the depth value to use
* for this fragment. This is equivalent to #gl_FragDepth.
* </para></glossdef>
* </glossentry>
* <glossentry>
* <glossterm>bool <emphasis>cogl_front_facing</emphasis></glossterm>
* <glossdef><para>
* - `bool cogl_front_facing`
* A readonly variable that will be true if the current primitive
* is front facing. This can be used to implement two-sided
* coloring algorithms. This is equivalent to #gl_FrontFacing.
* </para></glossdef>
* </glossentry>
* </glosslist>
* </tip>
*
* It's worth nothing that this API isn't what Cogl would like to have
* in the long term and it may be removed in Cogl 2.0. The
@ -264,10 +166,7 @@ cogl_create_shader (CoglShaderType shader_type);
*
* Replaces the current source associated with a shader with a new
* one.
*
* Please see <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
*/
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
*
* 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
* 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
* called by clutter_test_run(), for instance:
*
* |[
* ```c
* static void unit_foo (void) { ... }
*
* static void unit_bar (void) { ... }
@ -251,7 +251,7 @@ clutter_test_add_data_full (const char *test_path,
*
* return clutter_test_run ();
* }
* ]|
* ```
*
* Return value: the exit code for the test suite
*/

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.:
*
* |[
* ```
* CLUTTER_TEST_SUITE (
* CLUTTER_TEST_UNIT ("/foobarize", foobarize)
* CLUTTER_TEST_UNIT ("/bar-enabled", bar_enabled)
* )
* ]|
* ```
*
* Expands to:
*
* |[
* ```c
* int
* main (int argc,
* char *argv[])
@ -72,7 +72,7 @@ G_BEGIN_DECLS
*
* return clutter_test_run ();
* }
* ]|
* ```
*/
#define CLUTTER_TEST_SUITE(units) \
int \