Class Onscreen

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.

Whenever the source_property is changed the target_property is updated using the same value. For instance:

  g_object_bind_property (action, "active", widget, "sensitive", 0);

Will result in the "sensitive" property of the widget #GObject instance to be updated with the same value of the "active" property of the action #GObject instance.

If flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: if target_property on target changes then the source_property on source will be updated as well.

The binding will automatically be removed when either the source or the target instances are finalized. To remove the binding without affecting the source and the target you can just call g_object_unref() on the returned #GBinding instance.

Removing the binding by calling g_object_unref() on it must only be done if the binding, source and target are only used from a single thread and it is clear that both source and target outlive the binding. Especially it is not safe to rely on this if the binding, source or target can be finalized from different threads. Keep another reference to the binding and use g_binding_unbind() instead to be on the safe side.

A #GObject can have multiple bindings.

This function is the language bindings friendly version of g_object_bind_property_full(), using #GClosures instead of function pointers.

For example; some tile-based rendering GPUs are able to avoid allocating and accessing system memory for the depth and stencil buffer so long as these buffers are not required as input for subsequent frames and that can save a significant amount of memory bandwidth used to save and restore their contents to system memory between frames.

It is currently considered an error to try and explicitly discard the color buffer by passing %COGL_BUFFER_BIT_COLOR. This is because the color buffer is already implicitly discard when you finish rendering to a #CoglOnscreen framebuffer, and it's not meaningful to try and discard the color buffer of a #CoglOffscreen framebuffer since they are single-buffered.

Then the function draws the given primitive geometry to the specified destination framebuffer using the graphics processing pipeline described by pipeline.

The list of #CoglAttributes define the attributes of the vertices to be drawn, such as positions, colors and normals and the number of attributes is given as n_attributes.

This drawing api doesn't support high-level meta texture types such as #CoglTexture2DSliced so it is the user's responsibility to ensure that only low-level textures that can be directly sampled by a GPU such as #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D are associated with layers of the given pipeline.

This api doesn't support any of the legacy global state options such as cogl_set_depth_test_enabled(), cogl_set_backface_culling_enabled() or cogl_program_use()

For example an indices array of [0, 1, 2, 0, 2, 3] could be used used to draw two triangles (mode = %COGL_VERTICES_MODE_TRIANGLES + n_vertices = 6) but only provide attribute data for the 4 corners of a rectangle. When the GPU needs to read in each of the 6 vertices it will read the indices array for each vertex in sequence and use the index to look up the vertex attribute data. So here you can see that first and fourth vertex will point to the same data and third and fifth vertex will also point to shared data.

Drawing with indices can be a good way of minimizing the size of a mesh by allowing you to avoid data for duplicate vertices because multiple entries in the index array can refer back to a single shared vertex.

The indices array must be at least as long as first_vertex

• n_vertices otherwise the GPU will overrun the indices array when looking up vertex data.

Since it's very common to want to draw a run of rectangles using indices to avoid duplicating vertex data you can use cogl_get_rectangle_indices() to get a set of indices that can be shared.

This drawing api doesn't support high-level meta texture types such as #CoglTexture2DSliced so it is the user's responsibility to ensure that only low-level textures that can be directly sampled by a GPU such as #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D are associated with layers of the given pipeline.

This api doesn't support any of the legacy global state options such as cogl_set_depth_test_enabled(), cogl_set_backface_culling_enabled() or cogl_program_use()

The position is the position before the rectangle has been transformed by the model-view matrix and the projection matrix.

This is a high level drawing api that can handle any kind of #CoglMetaTexture texture for the first layer such as #CoglTexture2DSliced textures which may internally be comprised of multiple low-level textures. This is unlike low-level drawing apis such as cogl_primitive_draw() which only support low level texture types that are directly supported by GPUs such as #CoglTexture2D.

This api can not currently handle multiple high-level meta 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 and additionally they should be textures that can be sampled using normalized coordinates (so not #CoglTextureRectangle textures).

The top left texture coordinate for layer 0 of any pipeline will be (tex_coords[0], tex_coords[1]) and the bottom right coordinate will be (tex_coords[2], tex_coords[3]). The coordinates for layer 1 would be (tex_coords[4], tex_coords[5]) (tex_coords[6], tex_coords[7]) and so on...

The given texture coordinates should always be normalized such that (0, 0) corresponds to the top left and (1, 1) corresponds to the bottom right. To map an entire texture across the rectangle pass in tex_coords[0]=0, tex_coords[1]=0, tex_coords[2]=1, tex_coords[3]=1.

Even if you have associated a #CoglTextureRectangle texture which normally implies working with non-normalized texture coordinates this api should still be passed normalized texture coordinates.

The first pair of coordinates are for the first layer (with the smallest layer index) and if you supply less texture coordinates than there are layers in the current source material then default texture coordinates (0.0, 0.0, 1.0, 1.0) are generated.

This drawing api doesn't support high-level meta texture types such as #CoglTexture2DSliced so it is the user's responsibility to ensure that only low-level textures that can be directly sampled by a GPU such as #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D are associated with layers of the given pipeline.

This api doesn't support any of the legacy global state options such as cogl_set_depth_test_enabled(), cogl_set_backface_culling_enabled() or cogl_program_use()

The position is the position before the rectangle has been transformed by the model-view matrix and the projection matrix.

If you want to describe a rectangle with a texture mapped on it then you can use cogl_framebuffer_draw_textured_rectangle().

The top left corner of the first rectangle is positioned at (coordinates[0], coordinates[1]) and the bottom right corner is positioned at (coordinates[2], coordinates[3]). The positions for the second rectangle are (coordinates[4], coordinates[5]) and (coordinates[6], coordinates[7]) and so on...

The position is the position before the rectangle has been transformed by the model-view matrix and the projection matrix.

As a general rule for better performance its recommended to use this this API instead of calling cogl_framebuffer_draw_textured_rectangle() separately for multiple rectangles if all of the rectangles will be drawn together with the same pipeline state.

The position is the position before the rectangle has been transformed by the model-view matrix and the projection matrix.

This is a high level drawing api that can handle any kind of #CoglMetaTexture texture such as #CoglTexture2DSliced textures which may internally be comprised of multiple low-level textures. This is unlike low-level drawing apis such as cogl_primitive_draw() which only support low level texture types that are directly supported by GPUs such as #CoglTexture2D.

The given texture coordinates will only be used for the first 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

The given texture coordinates should always be normalized such that (0, 0) corresponds to the top left and (1, 1) corresponds to the bottom right. To map an entire texture across the rectangle pass in s_1=0, t_1=0, s_2=1, t_2=1.

Even if you have associated a #CoglTextureRectangle texture with one of your pipeline layers which normally implies working with non-normalized texture coordinates this api should still be passed normalized texture coordinates.

The position is the position before the rectangle has been transformed by the model-view matrix and the projection matrix.

This is a high level drawing api that can handle any kind of #CoglMetaTexture texture such as #CoglTexture2DSliced textures which may internally be comprised of multiple low-level textures. This is unlike low-level drawing apis such as cogl_primitive_draw() which only support low level texture types that are directly supported by GPUs such as #CoglTexture2D.

The top left corner of the first rectangle is positioned at (coordinates[0], coordinates[1]) and the bottom right corner is positioned at (coordinates[2], coordinates[3]). The top left texture coordinate is (coordinates[4], coordinates[5]) and the bottom right texture coordinate is (coordinates[6], coordinates[7]). The coordinates for subsequent rectangles are defined similarly by the subsequent coordinates.

As a general rule for better performance its recommended to use this this API instead of calling cogl_framebuffer_draw_textured_rectangle() separately for multiple rectangles if all of the rectangles will be drawn together with the same pipeline state.

The given texture coordinates should always be normalized such that (0, 0) corresponds to the top left and (1, 1) corresponds to the bottom right. To map an entire texture across the rectangle pass in tex_coords[0]=0, tex_coords[1]=0, tex_coords[2]=1, tex_coords[3]=1.

Even if you have associated a #CoglTextureRectangle texture which normally implies working with non-normalized texture coordinates this api should still be passed normalized texture coordinates.

One example might be for benchmarking purposes to be sure timing measurements reflect the time that the GPU is busy for not just the time it takes to queue rendering commands.

This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.

Calling this function implicitely allocates the framebuffer. The texture returned stays valid as long as the framebuffer stays valid.

This may return %TRUE even when the underlying framebuffer display pipeline does not support dithering. This value only represents the user's request for dithering.

The value can be:

• an empty #GValue initialized by %G_VALUE_INIT, which will be automatically initialized with the expected type of the property (since GLib 2.60)
• a #GValue initialized with the expected type of the property
• a #GValue initialized with a type to which the expected type of the property can be transformed

In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling g_value_unset().

Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming.

Calling cogl_framebuffer_get_samples_per_pixel() before the framebuffer has been allocated will simply return the value set using cogl_framebuffer_set_samples_per_pixel(). After the framebuffer has been allocated the value will reflect the actual number of samples that will be made by the GPU.

When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.

This function omits the property name lookup, hence it is faster than g_object_notify().

One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_object_class_install_property() inside a static array, e.g.:

  enum
  {
    PROP_0,
    PROP_FOO,
    PROP_LAST
  };

  static GParamSpec *properties[PROP_LAST];

  static void
  my_object_class_init (MyObjectClass *klass)
  {
    properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
                                             0, 100,
                                             50,
                                             G_PARAM_READWRITE);
    g_object_class_install_property (gobject_class,
                                     PROP_FOO,
                                     properties[PROP_FOO]);
  }

and then notify a change on the "foo" property with:

  g_object_notify_by_pspec (self, properties[PROP_FOO]);

You should be careful not to have to great a z_far / z_near ratio since that will reduce the effectiveness of depth testing since there wont be enough precision to identify the depth of objects near to each other.

The primitive is transformed by the current model-view matrix and the silhouette is intersected with the previous clipping area. To restore the previous clipping area, call cogl_framebuffer_pop_clip().

The rectangle is intersected with the current clip region. To undo the effect of this function, call cogl_framebuffer_pop_clip().

The rectangle is intersected with the current clip region. To undo the effect of this function, call cogl_framebuffer_pop_clip().

The implementation of the function looks like this:

|[ bitmap = cogl_bitmap_new_for_data (context, width, height, format, /* rowstride */ bpp * width, pixels); cogl_framebuffer_read_pixels_into_bitmap (framebuffer, x, y, COGL_READ_PIXELS_COLOR_BUFFER, bitmap); cogl_object_unref (bitmap);

@param x The x position to read from
@param y The y position to read from
@param width The width of the region of rectangles to read
@param height The height of the region of rectangles to read
@param format The pixel format to store the data in
@param pixels The address of the buffer to store the data in

Currently Cogl assumes that the framebuffer is in a premultiplied format so if the format of bitmap is non-premultiplied it will convert it. To read the pixel values without any conversion you should either specify a format that doesn't use an alpha channel or use one of the formats ending in PRE.

Since GLib 2.56, if GLIB_VERSION_MAX_ALLOWED is 2.56 or greater, the type of object will be propagated to the return type (using the GCC typeof() extension), so any casting the caller needs to do on the return type must be explicit.

In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.

Since GLib 2.56, the type of object will be propagated to the return type under the same conditions as for g_object_ref().

Some GPUs will implicitly resolve the point samples during rendering and so this function is effectively a nop, but with other architectures it is desirable to defer the resolve step until the end of the frame.

Since Cogl will automatically ensure samples are resolved if the target color buffer is used as a source this API only needs to be used if explicit control is desired - perhaps because you want to ensure that the resolve is completed in advance to avoid later having to wait for the resolve to complete.

If you are performing incremental updates to a framebuffer you should consider using cogl_framebuffer_resolve_samples_region() instead to avoid resolving redundant pixels.

Some GPUs will implicitly resolve the point samples during rendering and so this function is effectively a nop, but with other architectures it is desirable to defer the resolve step until the end of the frame.

Use of this API is recommended if incremental, small updates to a framebuffer are being made because by default Cogl will implicitly resolve all the point samples of the framebuffer which can result in redundant work if only a small number of samples have changed.

Because some GPUs implicitly resolve point samples this function only guarantees that at-least the region specified will be resolved and if you have rendered to a larger region then it's possible that other samples may be implicitly resolved.

This function should only be called from object system implementations.

If the object already had an association with that name, the old association will be destroyed.

Internally, the key is converted to a #GQuark using g_quark_from_string(). This means a copy of key is kept permanently (even after object has been finalized) — so it is recommended to only use a small, bounded set of values for key in your program, to avoid the #GQuark storage growing unbounded.

It's possible that your GPU does not support depth textures. You should check the %COGL_FEATURE_ID_DEPTH_TEXTURE feature before using this function. It's not valid to call this function after the framebuffer has been allocated as the creation of the depth texture is done at allocation time.

Depth buffer writing is enabled by default.

Dithering is a hardware dependent technique to increase the visible color resolution beyond what the underlying hardware supports by playing tricks with the colors placed into the framebuffer to give the illusion of other colors. (For example this can be compared to half-toning used by some news papers to show varying levels of grey even though their may only be black and white are available).

If the current display pipeline for framebuffer does not support dithering then this has no affect.

Dithering is enabled by default.

By default this value is usually set to 0 and that is referred to as "single-sample" rendering. A value of 1 or greater is referred to as "multisample" rendering.

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.

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.

By default the viewport has an origin of (0,0) and width and height that match the framebuffer's size. Assuming a default projection and modelview matrix then you could translate the contents of a window down and right by leaving the viewport size unchanged by moving the offset to (10,10). The viewport coordinates are measured in pixels. If you left the x and y origin as (0,0) you could scale the windows contents down by specify and width and height that's half the real size of the framebuffer.

Although the function takes floating point arguments, existing drivers only allow the use of integer values. In the future floating point values will be exposed via a checkable feature.

void
object_add_to_user_list (GObject     *object,
                         const gchar *new_string)
{
  // the quark, naming the object data
  GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
  // retrieve the old string list
  GList *list = g_object_steal_qdata (object, quark_string_list);

  // prepend new string
  list = g_list_prepend (list, g_strdup (new_string));
  // this changed 'list', so we need to set it again
  g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
  GList *node, *list = data;

  for (node = list; node; node = node->next)
    g_free (node->data);
  g_list_free (list);
}

Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full().

Duplicate notifications for each property are squashed so that at most one #GObject::notify signal is emitted for each property, in the reverse order in which they have been queued.

It is an error to call this function when the freeze count is zero.

If the pointer to the #GObject may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to %NULL rather than retain a dangling pointer to a potentially invalid #GObject instance. Use g_clear_object() for this.

When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.