Cogl-18 ▶ Cogl ▶ Offscreen

Explicitly allocates a configured Cogl.Framebuffer allowing developers to check and handle any errors that might arise from an unsupported configuration so that fallback configurations may be tried.

Many applications don't support any fallback options at least when 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.

Creates a binding between source_property on source and target_property on target.

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);
Copy

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

If flags contains GObject.BindingFlags.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 GObject.Binding 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.Object can have multiple bindings.

Creates a binding between source_property on source and target_property on target, allowing you to set the transformation functions to be used by the binding.

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

return FALSE for an immediately detected error, TRUE otherwise.

This blits a region of the color buffer of the source buffer to the destination buffer. This function should only be called if the COGL_FEATURE_ID_BLIT_FRAMEBUFFER feature is advertised.

The source and destination rectangles are defined in offscreen framebuffer orientation. When copying between an offscreen and onscreen framebuffers, the image is y-flipped accordingly.

The two buffers must have the same value types (e.g. floating-point, unsigned int, signed int, or fixed-point), but color formats do not need to match. This limitation comes from OpenGL ES 3.0 definition of glBlitFramebuffer.

Note that this function differs a lot from the glBlitFramebuffer function provided by the GL_EXT_framebuffer_blit extension. Notably it doesn't support having different sizes for the source and destination rectangle. This doesn't seem like a particularly useful feature. If the application wanted to scale the results it may make more sense to draw a primitive instead.

The GL function is documented to be affected by the scissor. This function therefore ensure that an empty clip stack is flushed before performing the blit which means the scissor is effectively ignored.

The function also doesn't support specifying the buffers to copy and instead only the color buffer is copied. When copying the depth or stencil buffers the extension on GLES2.0 only supports copying the full buffer which would be awkward to document with this API. If we wanted to support that feature it may be better to have a separate function to copy the entire buffer for a given mask.

The c error argument is optional, it can be NULL. If it is not NULL and this function returns FALSE, an error object with a code from COGL_SYSTEM_ERROR will be created.

Blocks a handler of an instance so it will not be called during any signal emissions

Clears all the auxiliary buffers identified in the buffers mask, and if that includes the color buffer then the specified color is used.

Clears all the auxiliary buffers identified in the buffers mask, and if that includes the color buffer then the specified color is used.

Declares that the specified buffers no longer need to be referenced by any further rendering commands. This can be an important optimization to avoid subsequent frames of rendering depending on the results of a previous frame.

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.BufferBit.COLOR. This is because the color buffer is already implicitly discard when you finish rendering to a Cogl.Onscreen framebuffer, and it's not meaningful to try and discard the color buffer of a Cogl.Offscreen framebuffer since they are single-buffered.

Disconnects a handler from an instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to.

Draws a textured rectangle to framebuffer with the given pipeline state with the top left corner positioned at (x_1, y_1) and the bottom right corner positioned at (x_2, y_2). As a pipeline may contain multiple texture layers this interface lets you supply texture coordinates for each layer of the pipeline.

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

This is a high level drawing api that can handle any kind of Cogl.Texture texture for the first layer such as Cogl.Texture2DSliced 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 Cogl.Texture2D.

This api can not currently handle multiple high-level meta texture layers. The first layer may be a high level meta texture such as Cogl.Texture2DSliced but all other layers much be low level textures such as Cogl.Texture2D.

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.

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 pipeline then default texture coordinates (0.0, 0.0, 1.0, 1.0) are generated.

Draws a rectangle to framebuffer with the given pipeline state and with the top left corner positioned at (x_1, y_1) and the bottom right corner positioned at (x_2, y_2).

The position is the position before the rectangle has been 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().

Draws a series of rectangles to framebuffer with the given pipeline state in the same way that cogl_framebuffer_draw_rectangle() does.

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.

Draws a textured rectangle to framebuffer using the given pipeline state with the top left corner positioned at (x_1, y_1) and the bottom right corner positioned at (x_2, y_2). The top left corner will have texture coordinates of (s_1, t_1) and the bottom right corner will have texture coordinates of (s_2, t_2).

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

This is a high level drawing api that can handle any kind of Cogl.Texture texture such as Cogl.Texture2DSliced 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 Cogl.Texture2D.

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.

Draws a series of rectangles to framebuffer with the given pipeline state in the same way that cogl_framebuffer_draw_textured_rectangle() does.

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 Cogl.Texture texture such as Cogl.Texture2DSliced 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 Cogl.Texture2D.

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.

This blocks the CPU until all pending rendering associated with the specified framebuffer has completed. It's very rare that developers should ever need this level of synchronization with the GPU and should never be used unless you clearly understand why you need to explicitly force synchronization.

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.

Flushes framebuffer to ensure the current batch of commands is submitted to the GPU.

Unlike cogl_framebuffer_finish(), this does not block the CPU.

This function is intended for GObject.Object implementations to re-enforce a [floating][floating-ref] object reference. Doing this is seldom required: all GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink().

Increases the freeze count on object. If the freeze count is non-zero, the emission of "notify" signals on object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one GObject.Object::notify signal is emitted for each property modified while the object is frozen.

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

Replaces the current projection matrix with a perspective matrix for a given viewing frustum defined by 4 side clip planes that all cross through the origin and 2 near and far clip planes.

Retrieves the number of alpha bits of framebuffer

Retrieves the number of blue bits of framebuffer

Can be used to query the Cogl.Context a given framebuffer was instantiated within. This is the Cogl.Context that was passed to cogl_onscreen_new() for example.

Gets a named field from the objects table of associations (see g_object_set_data()).

Queries whether depth buffer writing is enabled for framebuffer. This can be controlled via cogl_framebuffer_set_depth_write_enabled().

Returns whether dithering has been requested for the given framebuffer. See cogl_framebuffer_set_dither_enabled() for more details about dithering.

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

Retrieves the number of green bits of framebuffer

Queries the current height of the given framebuffer.

Stores the current model-view matrix in matrix.

Stores the current projection matrix in matrix.

Gets a property of an object.

The value can be:

• an empty GObject.Value initialized by G_VALUE_INIT, which will be automatically initialized with the expected type of the property (since GLib 2.60)
• a GObject.Value initialized with the expected type of the property
• a GObject.Value 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 GObject.Value.unset.

Note that GObject.Object.get_property is really intended for language bindings, GObject.Object.get is much more convenient for C programming.

This function gets back user data pointers stored via g_object_set_qdata().

Retrieves the number of red bits of framebuffer

Queries the height of the viewport as set using cogl_framebuffer_set_viewport() or the default value which is the height of the framebuffer.

Queries the width of the viewport as set using cogl_framebuffer_set_viewport() or the default value which is the width of the framebuffer.

Queries the x coordinate of the viewport origin as set using cogl_framebuffer_set_viewport() or the default value which is 0.

Queries the y coordinate of the viewport origin as set using cogl_framebuffer_set_viewport() or the default value which is 0.

Queries the x, y, width and height components of the current viewport as set using cogl_framebuffer_set_viewport() or the default values which are 0, 0, framebuffer_width and framebuffer_height. The values are written into the given viewport array.

Queries the current width of the given framebuffer.

Gets n_properties properties for an object. Obtained properties will be set to values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.

Checks whether object has a [floating][floating-ref] reference.

Emits a "notify" signal for the property property_name on object.

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.

Emits a "notify" signal for the property specified by pspec on object.

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.:

  typedef enum
  {
    PROP_FOO = 1,
    PROP_LAST
  } MyObjectProperty;

  static GParamSpec *properties[PROP_LAST];

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

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

  g_object_notify_by_pspec (self, properties[PROP_FOO]);
Copy

Replaces the current projection matrix with an orthographic projection matrix.

Replaces the current projection matrix with a perspective matrix based on the provided values.

You should be careful not to have to great a z_far / z_near 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.

Reverts the clipping region to the state before the last call to cogl_framebuffer_push_rectangle_clip()

Restores the model-view matrix on the top of the matrix stack.

Copies the current model-view matrix onto the matrix stack. The matrix can later be restored with cogl_framebuffer_pop_matrix().

Specifies a modelview transformed rectangular clipping area for all subsequent drawing operations. Any drawing commands that extend outside the rectangle will be clipped so that only the portion inside the rectangle will be displayed. The rectangle dimensions are transformed by the current model-view matrix.

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

This is a convenience wrapper around cogl_framebuffer_read_pixels_into_bitmap() which allocates a temporary Cogl.Bitmap to read pixel data directly into the given buffer. The rowstride of the buffer is assumed to be the width of the region times the bytes per pixel of the format. The source for the data is always taken from the color buffer. If you want to use any other rowstride or source, please use the cogl_framebuffer_read_pixels_into_bitmap() function directly.

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);
g_object_unref (bitmap);
Copy

This reads a rectangle of pixels from the given framebuffer where position (0, 0) is the top left. The pixel at (x, y) is the first read, and a rectangle of pixels with the same size as the bitmap is read right and downwards from that point.

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.

Increases the reference count of object.

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.

Increase the reference count of object, and possibly remove the [floating][floating-ref] reference, if object has a floating reference.

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().

Multiplies the current model-view matrix by one that rotates the model around the axis-vector specified by x, y and z. The rotation follows the right-hand thumb rule so for example rotating by 10 degrees about the axis-vector (0, 0, 1) causes a small counter-clockwise rotation.

Releases all references to other objects. This can be used to break reference cycles.

This function should only be called from object system implementations.

Multiplies the current model-view matrix by one that scales the x, y and z axes by the given values.

Sets multiple properties of an object at once. The properties argument should be a dictionary mapping property names to values.

Each object carries around a table of associations from strings to pointers. This function lets you set an association.

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

Internally, the key is converted to a GLib.Quark 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 GLib.Quark storage growing unbounded.

Enables or disables depth buffer writing when rendering to framebuffer. If depth writing is enabled for both the framebuffer and the rendering pipeline, and the framebuffer has an associated depth buffer, depth information will be written to this buffer during rendering.

Depth buffer writing is enabled by default.

Enables or disabled dithering if supported by the hardware.

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.

Sets matrix as the new model-view matrix.

Sets matrix as the new projection matrix.

Sets a property on an object.

Defines a scale and offset for everything rendered relative to the top-left of the destination framebuffer.

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.

Remove a specified datum from the object's data associations, without invoking the association's destroy handler.

This function gets back user data pointers stored via g_object_set_qdata() and removes the data from object without invoking its destroy() function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier, for example:

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);
}
Copy

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().

Stops a signal's emission by the given signal name. This will prevent the default handler and any subsequent signal handlers from being invoked.

Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on object and when it reaches zero, queued "notify" signals are emitted.

Duplicate notifications for each property are squashed so that at most one GObject.Object::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.

Multiplies the current model-view matrix by the given matrix.

Multiplies the current model-view matrix by one that translates the model along all three axes according to the given values.

Unblocks a handler so it will be called again during any signal emissions

Decreases the reference count of object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).

If the pointer to the GObject.Object 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.Object instance. Use g_clear_object() for this.

Explicitly allocates a configured Cogl.Framebuffer allowing developers to check and handle any errors that might arise from an unsupported configuration so that fallback configurations may be tried.

Many applications don't support any fallback options at least when 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.

the constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. constructed implementors should chain up to the constructed call of their parent class to allow it to complete its initialisation.

emits property change notification for a bunch of properties. Overriding dispatch_properties_changed should be rarely needed.

the dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, dispose should chain up to the dispose method of the parent class.

instance finalization function, should finish the finalization of the instance begun in dispose and chain up to the finalize method of the parent class.

the generic getter for all properties of this type. Should be overridden for every type with properties.

Emits a "notify" signal for the property property_name on object.

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.

the generic setter for all properties of this type. Should be overridden for every type with properties. If implementations of set_property don't emit property change notification explicitly, this will be done implicitly by the type system. However, if the notify signal is emitted explicitly, the type system will not emit it a second time.

This function essentially limits the life time of the closure to the life time of the object. That is, when the object is finalized, the closure is invalidated by calling g_closure_invalidate() on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also, g_object_ref() and g_object_unref() are added as marshal guards to the closure, to ensure that an extra reference count is held on object during invocation of the closure. Usually, this function will be called on closures that use this object as closure data.

Find the GObject.ParamSpec with the given name for an interface. Generally, the interface vtable passed in as g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek().

Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created GObject.ParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property.

This function is meant to be called from the interface's default vtable initialization function (the class_init member of GObject.TypeInfo.) It must not be called after after class_init has been called for any object types implementing this interface.

If pspec is a floating reference, it will be consumed.

Lists the properties of an interface.Generally, the interface vtable passed in as g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek().