Functions

bitmap_error_quark ()

blend_string_error_quark ()

buffer_get_size (buffer)

buffer_get_update_hint (buffer)

buffer_map (buffer, access, hints)

buffer_map_range (buffer, offset, size, access, hints)

buffer_set_data (buffer, offset, data, size)

buffer_set_update_hint (buffer, hint)

buffer_unmap (buffer)

color_equal (v1, v2)

color_init_from_hsl (hue, saturation, luminance)

debug_matrix_entry_print (entry)

debug_matrix_print (matrix)

debug_object_foreach_type (func, *user_data)

debug_object_print_instances ()

error_copy (error)

error_free (error)

error_matches (error, domain, code)

euler_equal (v1, v2)

foreach_feature (context, callback, *user_data)

framebuffer_error_quark ()

get_clock_time (context)

get_draw_framebuffer ()

get_static_identity_quaternion ()

get_static_zero_quaternion ()

gles2_texture_get_handle (texture, handle, target)

glib_renderer_source_new (renderer, priority)

glib_source_new (context, priority)

gtype_matrix_get_type ()

handle_get_type ()

handle_ref (handle)

handle_unref (handle)

has_feature (context, feature)

is_atlas_texture (object)

is_attribute (object)

is_attribute_buffer (object)

is_bitmap (object)

is_buffer (object)

is_context (object)

is_display (object)

is_frame_info (object)

is_framebuffer (object)

is_gles2_context (object)

is_index_buffer (object)

is_indices (object)

is_matrix_stack (object)

is_onscreen (object)

is_onscreen_template (object)

is_output (object)

is_pipeline (object)

is_pixel_buffer (object)

is_primitive (object)

is_primitive_texture (object)

is_renderer (object)

is_snippet (object)

is_sub_texture (object)

is_swap_chain (object)

is_texture (object)

is_texture_2d (object)

is_texture_2d_sliced (object)

is_texture_3d (object)

is_texture_pixmap_x11 (object)

is_texture_rectangle (object)

kms_display_queue_modes_reset (display)

kms_display_set_ignore_crtc (display, id, ignore)

kms_display_set_layout (display, width, height, crtcs, n_crtcs)

kms_renderer_get_gbm (renderer)

kms_renderer_get_kms_fd (renderer)

kms_renderer_set_kms_fd (renderer, fd)

matrix_equal (v1, v2)

poll_renderer_dispatch (renderer, poll_fds, n_poll_fds)

poll_renderer_get_info (renderer, poll_fds, n_poll_fds, timeout)

pop_gles2_context (ctx)

push_gles2_context (ctx, gles2_ctx, read_buffer, write_buffer)

quaternion_equal (v1, v2)

renderer_error_quark ()

texture_error_quark ()

vector3_add (result, a, b)

vector3_copy (vector)

vector3_cross_product (result, u, v)

vector3_distance (a, b)

vector3_divide_scalar (vector, scalar)

vector3_dot_product (a, b)

vector3_equal (v1, v2)

vector3_equal_with_epsilon (vector0, vector1, epsilon)

vector3_free (vector)

vector3_init (vector, x, y, z)

vector3_init_zero (vector)

vector3_invert (vector)

vector3_magnitude (vector)

vector3_multiply_scalar (vector, scalar)

vector3_normalize (vector)

vector3_subtract (result, a, b)

wayland_display_set_compositor_display (display, wayland_display)

wayland_onscreen_get_shell_surface (onscreen)

wayland_onscreen_get_surface (onscreen)

wayland_onscreen_resize (onscreen, width, height, offset_x, offset_y)

wayland_onscreen_set_foreign_surface (onscreen, surface)

wayland_renderer_get_display (renderer)

wayland_renderer_set_event_dispatch_enabled (renderer, enable)

wayland_renderer_set_foreign_display (renderer, display)

wayland_texture_set_region_from_shm_buffer (texture, src_x, src_y, width, height, shm_buffer, dst_x, dst_y, level)

x11_onscreen_get_visual_xid (onscreen)

x11_onscreen_get_window_xid (onscreen)

Details

Cogl.bitmap_error_quark()
Return type:

int

Cogl.blend_string_error_quark()
Return type:

int

Cogl.buffer_get_size(buffer)
Parameters:

buffer (object) – a buffer object

Returns:

the size of the buffer in bytes

Return type:

int

Retrieves the size of buffer

New in version 1.2.

Cogl.buffer_get_update_hint(buffer)
Parameters:

buffer (object) – a buffer object

Returns:

the Cogl.BufferUpdateHint currently used by the buffer

Return type:

Cogl.BufferUpdateHint

Retrieves the update hints set using Cogl.buffer_set_update_hint()

New in version 1.2.

Cogl.buffer_map(buffer, access, hints)
Parameters:
Returns:

A pointer to the mapped memory or None is the call fails

Return type:

object or None

Maps the buffer into the application address space for direct access. This is equivalent to calling Cogl.buffer_map_range() with zero as the offset and the size of the entire buffer as the size.

It is strongly recommended that you pass Cogl.BufferMapHint._ as a hint if you are going to replace all the buffer’s data. This way if the buffer is currently being used by the GPU then the driver won’t have to stall the CPU and wait for the hardware to finish because it can instead allocate a new buffer to map.

The behaviour is undefined if you access the buffer in a way conflicting with the access mask you pass. It is also an error to release your last reference while the buffer is mapped.

New in version 1.2.

Cogl.buffer_map_range(buffer, offset, size, access, hints)
Parameters:

  • buffer (object) – a buffer object

  • offset (int) – Offset within the buffer to start the mapping

  • size (int) – The size of data to map

  • access (Cogl.BufferAccess) – how the mapped buffer will be used by the application

  • hints (Cogl.BufferMapHint) – A mask of Cogl.BufferMapHint s that tell Cogl how the data will be modified once mapped.

Raises:

GLib.Error

Returns:

A pointer to the mapped memory or None is the call fails

Return type:

object or None

Maps a sub-region of the buffer into the application’s address space for direct access.

It is strongly recommended that you pass Cogl.BufferMapHint._ as a hint if you are going to replace all the buffer’s data. This way if the buffer is currently being used by the GPU then the driver won’t have to stall the CPU and wait for the hardware to finish because it can instead allocate a new buffer to map. You can pass Cogl.BufferMapHint._RANGE instead if you want the regions outside of the mapping to be retained.

The behaviour is undefined if you access the buffer in a way conflicting with the access mask you pass. It is also an error to release your last reference while the buffer is mapped.

New in version 2.0.

Cogl.buffer_set_data(buffer, offset, data, size)
Parameters:

  • buffer (object) – a buffer object

  • offset (int) – destination offset (in bytes) in the buffer

  • data (object or None) – a pointer to the data to be copied into the buffer

  • size (int) – number of bytes to copy

Returns:

True is the operation succeeded, False otherwise

Return type:

int

Updates part of the buffer with new data from data. Where to put this new data is controlled by offset and offset + data should be less than the buffer size.

New in version 1.2.

Cogl.buffer_set_update_hint(buffer, hint)
Parameters:

Sets the update hint on a buffer. See Cogl.BufferUpdateHint for a description of the available hints.

New in version 1.2.

Cogl.buffer_unmap(buffer)
Parameters:

buffer (object) – a buffer object

Unmaps a buffer previously mapped by Cogl.buffer_map().

New in version 1.2.

Cogl.color_equal(v1, v2)
Parameters:
Returns:

True if the two colors are the same.

Return type:

int

Compares two Cogl.Color 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 Cogl.Color s as keys in a GLib.HashTable.

New in version 1.0.

Cogl.color_init_from_hsl(hue, saturation, luminance)
Parameters:

  • hue (float) – hue value, in the 0 .. 360 range

  • saturation (float) – saturation value, in the 0 .. 1 range

  • luminance (float) – luminance value, in the 0 .. 1 range

Returns:

return location for a Cogl.Color

Return type:

color: Cogl.Color

Converts a color expressed in HLS (hue, luminance and saturation) values into a Cogl.Color.

New in version 1.16.

Cogl.debug_matrix_entry_print(entry)
Parameters:

entry (Cogl.MatrixEntry) – A Cogl.MatrixEntry

Allows visualizing the operations that build up the given entry for debugging purposes by printing to stdout.

Cogl.debug_matrix_print(matrix)
Parameters:

matrix (Cogl.Matrix) – A Cogl.Matrix

Prints the contents of a Cogl.Matrix to stdout.

New in version 2.0.

Cogl.debug_object_foreach_type(func, *user_data)
Parameters:

Invokes func once for each type of object that Cogl uses and passes a count of the number of objects for that type. This is intended to be used solely for debugging purposes to track down issues with objects leaking.

New in version 1.8.

Cogl.debug_object_print_instances()

Prints a list of all the object types that Cogl uses along with the number of objects of that type that are currently in use. This is intended to be used solely for debugging purposes to track down issues with objects leaking.

New in version 1.8.

Cogl.error_copy(error)
Parameters:

error (GLib.Error) – A #CoglError thrown by the Cogl api

Returns:

A newly allocated #CoglError initialized to match the contents of error.

Return type:

GLib.Error

Makes a copy of error which can later be freed using Cogl.error_free().

Cogl.error_free(error)
Parameters:

error (GLib.Error) – A #CoglError thrown by the Cogl api

Frees a #CoglError and associated resources.

Cogl.error_matches(error, domain, code)
Parameters:

  • error (GLib.Error) – A #CoglError thrown by the Cogl api or None

  • domain (int) – The error domain

  • code (int) – The error code

Returns:

whether the error corresponds to the given domain and code.

Return type:

int

Returns True if error matches domain and code, False otherwise. In particular, when error is None, False will be returned.

Cogl.euler_equal(v1, v2)
Parameters:

  • v1 (object or None) – The first euler angle to compare

  • v2 (object or None) – The second euler angle to compare

Returns:

True if v1 and v2 are equal else False.

Return type:

int

Compares the two given euler angles v1 and v1 and it they are equal returns True else False.

This function only checks that all three components rotations are numerically equal, it does not consider that some rotations can be represented with different component rotations

New in version 2.0.

Cogl.foreach_feature(context, callback, *user_data)
Parameters:

Iterates through all the context level features currently supported for a given context and for each feature callback is called.

New in version 1.10.

Cogl.framebuffer_error_quark()
Return type:

int

Cogl.get_clock_time(context)
Parameters:

context (Cogl.Context) – a Cogl.Context pointer

Returns:

the time value for the Cogl clock, in nanoseconds from an arbitrary point in time, or 0 if Cogl doesn’t have an active internal clock.

Return type:

int

Returns the current time value from Cogl’s internal clock. This clock is used for measuring times such as the presentation time in a Cogl.FrameInfo.

This method is meant for converting timestamps retrieved from Cogl to other time systems, and is not meant to be used as a standalone timing system. For that reason, if this function is called without having retrieved a valid (non-zero) timestamp from Cogl first, it may return 0 to indicate that Cogl has no active internal clock.

New in version 1.14.

Cogl.get_draw_framebuffer()
Returns:

The current Cogl.Framebuffer

Return type:

Cogl.Framebuffer

Gets the current Cogl.Framebuffer as set using cogl_push_framebuffer()

New in version 1.8.

Cogl.get_static_identity_quaternion()
Returns:

A pointer to an identity quaternion

Return type:

Cogl.Quaternion

Returns a pointer to a singleton quaternion constant describing the canonical identity [1 (0, 0, 0)] which represents no rotation.

If you multiply a quaternion with the identity quaternion you will get back the same value as the original quaternion.

New in version 2.0.

Cogl.get_static_zero_quaternion()
Returns:

a pointer to a singleton quaternion constant describing a rotation of 180 degrees around a degenerate axis: [0 (0, 0, 0)]

Return type:

Cogl.Quaternion

New in version 2.0.

Cogl.gles2_texture_get_handle(texture, handle, target)
Parameters:

  • texture (Cogl.Texture) – A Cogl.Texture

  • handle (int) – A return location for an OpenGL ES 2.0 texture handle

  • target (int) – A return location for an OpenGL ES 2.0 texture target

Returns:

True if a handle and target could be returned otherwise False is returned.

Return type:

int

Gets an OpenGL ES 2.0 texture handle for a Cogl.Texture that can then be referenced by a Cogl.GLES2Context. As well as returning a texture handle the texture’s target (such as GL_TEXTURE_2D) is also returned.

If the Cogl.Texture can not be shared with a Cogl.GLES2Context then this function will return False.

This api does not affect the lifetime of the Cogl.Texture and you must take care not to reference the returned handle after the original texture has been freed.

This interface is only intended for sharing textures to read from. The behaviour is undefined if the texture is modified by a GLES2 context. This function will only return True for low-level Cogl.Texture s such as Cogl.Texture2D or Cogl.Texture3D but not for high level meta textures such as Cogl.Texture2DSliced The handle returned should not be passed directly to a system OpenGL ES 2.0 library, the handle is only intended to be used via a Cogl.GLES2Vtable or via libcogl-gles2.

New in version 2.0.

Cogl.glib_renderer_source_new(renderer, priority)
Parameters:
Returns:

a new GLib.Source

Return type:

GLib.Source

Creates a GLib.Source which handles Cogl’s internal system event processing. This can be used as a convenience instead of Cogl.poll_renderer_get_info() and Cogl.poll_renderer_dispatch() in applications that are already using the GLib main loop. After this is called the GLib.Source should be attached to the main loop using GLib.Source.attach().

New in version 1.16.

Cogl.glib_source_new(context, priority)
Parameters:
Returns:

a new GLib.Source

Return type:

GLib.Source

Creates a GLib.Source which handles Cogl’s internal system event processing. This can be used as a convenience instead of Cogl.poll_renderer_get_info() and Cogl.poll_renderer_dispatch() in applications that are already using the GLib main loop. After this is called the GLib.Source should be attached to the main loop using GLib.Source.attach().

Applications that manually connect to a Cogl.Renderer before they create a Cogl.Context should instead use Cogl.glib_renderer_source_new() so that events may be dispatched before a context has been created. In that case you don’t need to use this api in addition later, it is simply enough to use Cogl.glib_renderer_source_new() instead.

This api is actually just a thin convenience wrapper around Cogl.glib_renderer_source_new()

New in version 1.10.

Cogl.gtype_matrix_get_type()
Returns:

the GObject.GType for the registered “Cogl.Matrix" boxed type. This can be used for example to define GObject.Object properties that accept a Cogl.Matrix value.

Return type:

GObject.GType

Deprecated since version 1.18: Use cogl_matrix_get_gtype() instead.

Cogl.handle_get_type()
Return type:

GObject.GType

Cogl.handle_ref(handle)
Parameters:

handle (object) – a #CoglHandle

Returns:

the handle, with its reference count increased

Return type:

object

Increases the reference count of handle by 1

Cogl.handle_unref(handle)
Parameters:

handle (object) – a #CoglHandle

Drecreases the reference count of handle by 1; if the reference count reaches 0, the resources allocated by handle will be freed

Cogl.has_feature(context, feature)
Parameters:
Returns:

True if the feature is currently supported or False if not.

Return type:

int

Checks if a given feature is currently available

Cogl does not aim to be a lowest common denominator API, it aims to expose all the interesting features of GPUs to application which means applications have some responsibility to explicitly check that certain features are available before depending on them.

New in version 1.10.

Cogl.is_atlas_texture(object)
Parameters:

object (object or None) – a Cogl.Object

Returns:

True if the passed object represents an atlas texture and False otherwise

Return type:

int

Checks whether the given object references a Cogl.AtlasTexture

New in version 1.16.

Cogl.is_attribute(object)
Parameters:

object (object or None) – A Cogl.Object

Returns:

True if the object references a Cogl.Attribute, False otherwise

Return type:

int

Gets whether the given object references a Cogl.Attribute.

Cogl.is_attribute_buffer(object)
Parameters:

object (object or None) – A Cogl.Object

Returns:

True if object references a Cogl.AttributeBuffer, False otherwise

Return type:

int

Gets whether the given object references a Cogl.AttributeBuffer.

New in version 1.4.

Cogl.is_bitmap(object)
Parameters:

object (object or None) – a Cogl.Object pointer

Returns:

True if the passed object represents a bitmap, and False otherwise

Return type:

int

Checks whether object is a Cogl.Bitmap

New in version 1.0.

Cogl.is_buffer(object)
Parameters:

object (object or None) – a buffer object

Returns:

True if the handle is a CoglBuffer, and False otherwise

Return type:

int

Checks whether buffer is a buffer object.

New in version 1.2.

Cogl.is_context(object)
Parameters:

object (object or None) – An object or None

Returns:

True if the object references a Cogl.Context, False otherwise

Return type:

int

Gets whether the given object references an existing context object.

New in version 1.10.

Cogl.is_display(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if the object references a Cogl.Display and False otherwise.

Return type:

int

Gets whether the given object references a Cogl.Display.

New in version 1.10.

Cogl.is_frame_info(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if the object references a Cogl.FrameInfo and False otherwise.

Return type:

int

Gets whether the given object references a Cogl.FrameInfo.

New in version 2.0.

Cogl.is_framebuffer(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if the object references a Cogl.Framebuffer and False otherwise.

Return type:

int

Gets whether the given object references a Cogl.Framebuffer.

New in version 1.10.

Cogl.is_gles2_context(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if the object references a Cogl.GLES2Context and False otherwise.

Return type:

int

Gets whether the given object references a Cogl.GLES2Context.

New in version 2.0.

Cogl.is_index_buffer(object)
Parameters:

object (object or None) – A Cogl.Object

Returns:

True if the object references a Cogl.IndexBuffer, False otherwise

Return type:

int

Gets whether the given object references a Cogl.IndexBuffer.

New in version 1.4.

Cogl.is_indices(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if the object references a Cogl.Indices and False otherwise.

Return type:

int

Gets whether the given object references a Cogl.Indices.

New in version 1.10.

Cogl.is_matrix_stack(object)
Parameters:

object (object or None) – a Cogl.Object

Returns:

True if object is a Cogl.MatrixStack, otherwise False.

Return type:

int

Determines if the given Cogl.Object refers to a Cogl.MatrixStack.

Cogl.is_onscreen(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if the object references a Cogl.Onscreen and False otherwise.

Return type:

int

Gets whether the given object references a Cogl.Onscreen.

New in version 1.10.

Cogl.is_onscreen_template(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if the object references a Cogl.OnscreenTemplate and False otherwise.

Return type:

int

Gets whether the given object references a Cogl.OnscreenTemplate.

New in version 1.10.

Cogl.is_output(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if the object references a Cogl.Output and False otherwise.

Return type:

int

Gets whether the given object references a Cogl.Output.

New in version 1.14.

Cogl.is_pipeline(object)
Parameters:

object (object or None) – A Cogl.Object

Returns:

True if the object references a Cogl.Pipeline, False otherwise

Return type:

int

Gets whether the given object references an existing pipeline object.

New in version 2.0.

Cogl.is_pixel_buffer(object)
Parameters:

object (object or None) – a Cogl.Object to test

Returns:

True if the object is a pixel buffer, and False otherwise

Return type:

int

Checks whether object is a pixel buffer.

New in version 1.2.

Cogl.is_primitive(object)
Parameters:

object (object or None) – A Cogl.Object

Returns:

True if the object references a Cogl.Primitive, False otherwise

Return type:

int

Gets whether the given object references a Cogl.Primitive.

New in version 1.6.

Cogl.is_primitive_texture(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if the pointer references a primitive texture, and False otherwise

Return type:

int

Gets whether the given object references a primitive texture object.

New in version 2.0.

Cogl.is_renderer(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if object is a Cogl.Renderer, else False.

Return type:

int

Determines if the given object is a Cogl.Renderer

New in version 1.10.

Cogl.is_snippet(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if the object references a Cogl.Snippet, False otherwise

Return type:

int

Gets whether the given object references an existing snippet object.

New in version 1.10.

Cogl.is_sub_texture(object)
Parameters:

object (object or None) – a Cogl.Object

Returns:

True if the passed object represents a Cogl.SubTexture and False otherwise.

Return type:

int

Checks whether object is a Cogl.SubTexture.

New in version 1.10.

Cogl.is_swap_chain(object)
Parameters:

object (object or None) –

Return type:

int

Cogl.is_texture(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if the object references a texture, and False otherwise

Return type:

int

Gets whether the given object references a texture object.

Cogl.is_texture_2d(object)
Parameters:

object (object or None) – A Cogl.Object

Returns:

True if the object references a Cogl.Texture2D, False otherwise

Return type:

int

Gets whether the given object references an existing Cogl.Texture2D object.

Cogl.is_texture_2d_sliced(object)
Parameters:

object (object or None) – A Cogl.Object pointer

Returns:

True if the object references a Cogl.Texture2DSliced and False otherwise.

Return type:

int

Gets whether the given object references a Cogl.Texture2DSliced.

New in version 1.10.

Cogl.is_texture_3d(object)
Parameters:

object (object or None) – a Cogl.Object

Returns:

True if the passed object represents a 3D texture and False otherwise

Return type:

int

Checks whether the given object references a Cogl.Texture3D

New in version 1.4.

Cogl.is_texture_pixmap_x11(object)
Parameters:

object (object or None) – A pointer to a Cogl.Object

Returns:

True if the object is a Cogl.TexturePixmapX11, and False otherwise

Return type:

int

Checks whether object points to a Cogl.TexturePixmapX11 instance.

New in version 1.4.

Cogl.is_texture_rectangle(object)
Parameters:

object (object or None) – A Cogl.Object

Returns:

True if the object references a Cogl.TextureRectangle, False otherwise.

Return type:

int

Gets whether the given object references an existing Cogl.TextureRectangle object.

Cogl.kms_display_queue_modes_reset(display)
Parameters:

display (Cogl.Display) – A Cogl.Display

Asks Cogl to explicitly reset the crtc output modes at the next Cogl.Onscreen swap_buffers request. For applications that support VT switching they may want to re-assert the output modes when switching back to the applications VT since the modes are often not correctly restored automatically.

The display must have been either explicitly setup via Cogl.Display.setup() or implicitily setup by having created a context using the display

New in version 2.0.

Cogl.kms_display_set_ignore_crtc(display, id, ignore)
Parameters:

  • display (Cogl.Display) –

  • id (int) – KMS output id

  • ignore (int) – Ignore ouput or not

Tells cogl to ignore (or stop ignoring) a ctrc which means it never flips buffers at this crtc.

Cogl.kms_display_set_layout(display, width, height, crtcs, n_crtcs)
Parameters:
Raises:

GLib.Error

Return type:

int

Configures display to use a framebuffer sized width x height, covering the CRTCS in crtcs. width and height must be within the driver framebuffer limits, and crtcs must be valid KMS API IDs.

Calling this function overrides the automatic mode setting done by Cogl, and for this reason must be called before the first call to Cogl.Onscreen.swap_buffers().

If you want to restore the default behaviour, you can call this function with width and height set to -1.

Cogl.kms_renderer_get_gbm(renderer)
Parameters:

renderer (Cogl.Renderer) –

Return type:

object or None

Cogl.kms_renderer_get_kms_fd(renderer)
Parameters:

renderer (Cogl.Renderer) – A Cogl.Renderer

Returns:

The kms file descriptor or -1 if no kms file desriptor has been opened by Cogl.

Return type:

int

Queries the file descriptor Cogl is using internally for communicating with the kms driver.

Cogl.kms_renderer_set_kms_fd(renderer, fd)
Parameters:

Sets the file descriptor Cogl should use to communicate to the kms driver. If -1 (the default), then Cogl will open its own FD by trying to open “/dev/dri/card0”.

New in version 1.18.

Cogl.matrix_equal(v1, v2)
Parameters:

  • v1 (object or None) – A 4x4 transformation matrix

  • v2 (object or None) – A 4x4 transformation matrix

Return type:

int

Compares two matrices to see if they represent the same transformation. Although internally the matrices may have different annotations associated with them and may potentially have a cached inverse matrix these are not considered in the comparison.

New in version 1.4.

Cogl.poll_renderer_dispatch(renderer, poll_fds, n_poll_fds)
Parameters:

This should be called whenever an application is woken up from going idle in its main loop. The poll_fds array should contain a list of file descriptors matched with the events that occurred in revents. The events field is ignored. It is safe to pass in extra file descriptors that Cogl didn’t request when calling Cogl.poll_renderer_get_info() or a shorter array missing some file descriptors that Cogl requested.

If your application didn’t originally create a Cogl.Renderer manually then you can easily get a Cogl.Renderer pointer by calling cogl_get_renderer().

New in version 1.16.

Cogl.poll_renderer_get_info(renderer, poll_fds, n_poll_fds, timeout)
Parameters:

  • renderer (Cogl.Renderer) – A Cogl.Renderer

  • poll_fds (Cogl.PollFD) – A return location for a pointer to an array of Cogl.PollFD s

  • n_poll_fds (int) – A return location for the number of entries in poll_fds

  • timeout (int) – A return location for the maximum length of time to wait in microseconds, or -1 to wait indefinitely.

Returns:

A “poll fd state age” that changes whenever the set of poll_fds has changed. If this API is being used to integrate with another system mainloop api then knowing if the set of file descriptors and events has really changed can help avoid redundant work depending the api. The age isn’t guaranteed to change when the timeout changes.

Return type:

int

Is used to integrate Cogl with an application mainloop that is based on the unix poll(2) api (or select() or something equivalent). This api should be called whenever an application is about to go idle so that Cogl has a chance to describe what file descriptor events it needs to be woken up for.

If your application is using the Glib mainloop then you should jump to the Cogl.glib_source_new() api as a more convenient way of integrating Cogl with the mainloop. After the function is called poll_fds will contain a pointer to an array of Cogl.PollFD structs describing the file descriptors that Cogl expects. The fd and events members will be updated accordingly. After the application has completed its idle it is expected to either update the revents members directly in this array or to create a copy of the array and update them there.

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 Cogl.PollFD s with updated revent values.

When using the Cogl.WinsysID.WGL winsys (where file descriptors don’t make any sense) or Cogl.WinsysID.SDL (where the event handling functions of SDL don’t allow blocking on a file descriptor) *n_poll_fds is guaranteed to be zero.

timeout will contain a maximum amount of time to wait in microseconds before the application should wake up or -1 if the application should wait indefinitely. This can also be 0 if Cogl needs to be woken up immediately.

New in version 1.16.

Cogl.pop_gles2_context(ctx)
Parameters:

ctx (Cogl.Context) – A Cogl.Context

Restores the previously active Cogl.GLES2Context if there were nested calls to Cogl.push_gles2_context() or otherwise restores the ability to render with the Cogl api instead of OpenGLES 2.0.

The behaviour is undefined if calls to Cogl.pop_gles2_context() are not balenced with the number of corresponding calls to Cogl.push_gles2_context().

New in version 2.0.

Cogl.push_gles2_context(ctx, gles2_ctx, read_buffer, write_buffer)
Parameters:
Raises:

GLib.Error

Returns:

True if operation was successfull or False otherwise and error will be updated.

Return type:

int

Pushes the given gles2_ctx onto a stack associated with ctx so that the OpenGLES 2.0 api can be used instead of the Cogl rendering apis to read and write to the specified framebuffers.

Usage of the api available through a Cogl.GLES2Vtable is only allowed between Cogl.push_gles2_context() and Cogl.pop_gles2_context() calls.

If there is a runtime problem with switching over to the given gles2_ctx then this function will return False and return an error through error.

New in version 2.0.

Cogl.quaternion_equal(v1, v2)
Parameters:
Returns:

True if the quaternions are equal else False.

Return type:

int

Compares that all the components of quaternions a and b are equal.

An epsilon value is not used to compare the float components, but the == operator is at least used so that 0 and -0 are considered equal.

New in version 2.0.

Cogl.renderer_error_quark()
Return type:

int

Cogl.texture_error_quark()
Return type:

int

Cogl.vector3_add(result, a, b)
Parameters:

  • result (float) – Where you want the result written

  • a (float) – The first vector operand

  • b (float) – The second vector operand

Adds each of the corresponding components in vectors a and b storing the results in result.

New in version 1.4.

Cogl.vector3_copy(vector)
Parameters:

vector (float) – The 3 component vector you want to copy

Returns:

A newly allocated 3 component float vector

Return type:

float

Allocates a new 3 component float vector on the heap initializing the components from the given vector and returns a pointer to the newly allocated vector. You should free the memory using Cogl.vector3_free()

New in version 1.4.

Cogl.vector3_cross_product(result, u, v)
Parameters:

  • result (float) – Where you want the result written

  • u (float) – Your first 3 component vector

  • v (float) – Your second 3 component vector

Calculates the cross product between the two vectors u and v.

The cross product is a vector perpendicular to both u and v. This can be useful for calculating the normal of a polygon by creating two vectors in its plane using the polygons vertices and taking their cross product.

If the two vectors are parallel then the cross product is 0.

You can use a right hand rule to determine which direction the perpendicular vector will point: If you place the two vectors tail, to tail and imagine grabbing the perpendicular line that extends through the common tail with your right hand such that you fingers rotate in the direction from u to v then the resulting vector points along your extended thumb.

New in version 1.4.

Cogl.vector3_distance(a, b)
Parameters:

  • a (float) – The first point

  • b (float) – The second point

Returns:

The distance between two points given as 3 component vectors.

Return type:

float

If you consider the two given vectors as (x,y,z) points instead then this will compute the distance between those two points.

New in version 1.4.

Cogl.vector3_divide_scalar(vector, scalar)
Parameters:

  • vector (float) – The 3 component vector you want to manipulate

  • scalar (float) – The scalar you want to divide the vector components by

Divides each of the vector components by the given scalar.

New in version 1.4.

Cogl.vector3_dot_product(a, b)
Parameters:

  • a (float) – Your first 3 component vector

  • b (float) – Your second 3 component vector

Returns:

The dot product of two vectors.

Return type:

float

Calculates the dot product of the two 3 component vectors. This can be used to determine the magnitude of one vector projected onto another. (for example a surface normal)

For example if you have a polygon with a given normal vector and some other point for which you want to calculate its distance from the polygon, you can create a vector between one of the polygon vertices and that point and use the dot product to calculate the magnitude for that vector but projected onto the normal of the polygon. This way you don’t just get the distance from the point to the edge of the polygon you get the distance from the point to the nearest part of the polygon.

If you don’t use a unit length normal in the above example then you would then also have to divide the result by the magnitude of the normal The dot product is calculated as:

(a->x * b->x + a->y * b->y + a->z * b->z)

For reference, the dot product can also be calculated from the angle between two vectors as:

|a||b|cos𝜃

New in version 1.4.

Cogl.vector3_equal(v1, v2)
Parameters:

  • v1 (object or None) – The first 3 component vector you want to compare

  • v2 (object or None) – The second 3 component vector you want to compare

Returns:

True if the vectors are equal else False.

Return type:

int

Compares the components of two vectors and returns True if they are the same.

The comparison of the components is done with the ‘==’ operator such that -0 is considered equal to 0, but otherwise there is no fuzziness such as an epsilon to consider vectors that are essentially identical except for some minor precision error differences due to the way they have been manipulated.

New in version 1.4.

Cogl.vector3_equal_with_epsilon(vector0, vector1, epsilon)
Parameters:

  • vector0 (float) – The first 3 component vector you want to compare

  • vector1 (float) – The second 3 component vector you want to compare

  • epsilon (float) – The allowable difference between components to still be considered equal

Returns:

True if the vectors are equal else False.

Return type:

int

Compares the components of two vectors using the given epsilon and returns True if they are the same, using an internal epsilon for comparing the floats.

Each component is compared against the epsilon value in this way:

if (fabsf (vector0->x - vector1->x) < epsilon)

New in version 1.4.

Cogl.vector3_free(vector)
Parameters:

vector (float) – The 3 component you want to free

Frees a 3 component vector that was previously allocated with Cogl.vector3_copy()

New in version 1.4.

Cogl.vector3_init(vector, x, y, z)
Parameters:

  • vector (float) – The 3 component vector you want to initialize

  • x (float) – The x component

  • y (float) – The y component

  • z (float) – The z component

Initializes a 3 component, single precision float vector which can then be manipulated with the cogl_vector convenience APIs. Vectors can also be used in places where a “point” is often desired.

New in version 1.4.

Cogl.vector3_init_zero(vector)
Parameters:

vector (float) – The 3 component vector you want to initialize

Initializes a 3 component, single precision float vector with zero for each component.

New in version 1.4.

Cogl.vector3_invert(vector)
Parameters:

vector (float) – The 3 component vector you want to manipulate

Inverts/negates all the components of the given vector.

New in version 1.4.

Cogl.vector3_magnitude(vector)
Parameters:

vector (float) – The 3 component vector you want the magnitude for

Returns:

The magnitude of vector.

Return type:

float

Calculates the scalar magnitude or length of vector.

New in version 1.4.

Cogl.vector3_multiply_scalar(vector, scalar)
Parameters:

  • vector (float) – The 3 component vector you want to manipulate

  • scalar (float) – The scalar you want to multiply the vector components by

Multiplies each of the vector components by the given scalar.

New in version 1.4.

Cogl.vector3_normalize(vector)
Parameters:

vector (float) – The 3 component vector you want to manipulate

Updates the vector so it is a “unit vector” such that the vector s magnitude or length is equal to 1.

It’s safe to use this function with the [0, 0, 0] vector, it will not try to divide components by 0 (its norm) and will leave the vector untouched.

New in version 1.4.

Cogl.vector3_subtract(result, a, b)
Parameters:

  • result (float) – Where you want the result written

  • a (float) – The first vector operand

  • b (float) – The second vector operand

Subtracts each of the corresponding components in vector b from a storing the results in result.

New in version 1.4.

Cogl.wayland_display_set_compositor_display(display, wayland_display)
Parameters:

Informs Cogl of a compositor’s Wayland display pointer. This enables Cogl to register private wayland extensions required to pass buffers between the clients and compositor.

New in version 1.10.

Cogl.wayland_onscreen_get_shell_surface(onscreen)
Parameters:

onscreen (Cogl.Onscreen) –

Return type:

object or None

Cogl.wayland_onscreen_get_surface(onscreen)
Parameters:

onscreen (Cogl.Onscreen) –

Return type:

object or None

Cogl.wayland_onscreen_resize(onscreen, width, height, offset_x, offset_y)
Parameters:

  • onscreen (Cogl.Onscreen) – A Cogl.Onscreen framebuffer

  • width (int) – The desired width of the framebuffer

  • height (int) – The desired height of the framebuffer

  • offset_x (int) – A relative x offset for the new framebuffer

  • offset_y (int) – A relative y offset for the new framebuffer

Resizes the backbuffer of the given onscreen framebuffer to the given size. Since a buffer is usually conceptually scaled with a center point the offset_x and offset_y arguments allow the newly allocated buffer to be positioned relative to the old buffer size.

For example a buffer that is being resized by moving the bottom right corner, and the top left corner is remaining static would use x and y offsets of (0, 0) since the top-left of the new buffer should have the same position as the old buffer. If the center of the old buffer is being zoomed into then all the corners of the new buffer move out from the center and the x and y offsets would be (-half_x_size_increase, -half_y_size_increase) where x/y_size_increase is how many pixels bigger the buffer is on the x and y axis.

Note that if some drawing commands have been applied to the framebuffer since the last swap buffers then the resize will be queued and will only take effect in the next swap buffers.

If multiple calls to Cogl.wayland_onscreen_resize() get queued before the next swap buffers request then the relative x and y offsets accumulate instead of being replaced. The width and height values superseed the old values.

New in version 1.10.

Cogl.wayland_onscreen_set_foreign_surface(onscreen, surface)
Parameters:

  • onscreen (Cogl.Onscreen) – An unallocated framebuffer. surface A Wayland surface to associate with the onscreen.

  • surface (object or None) –

Allows you to explicitly notify Cogl of an existing Wayland surface to use, which prevents Cogl from allocating a surface and shell surface for the onscreen. An allocated surface will not be destroyed when the onscreen is freed.

This function must be called before onscreen is allocated.

New in version 1.16.

Cogl.wayland_renderer_get_display(renderer)
Parameters:

renderer (Cogl.Renderer) – A Cogl.Renderer

Returns:

The wayland display currently associated with renderer, or None if the renderer hasn’t yet been connected and no foreign display has been specified.

Return type:

object or None

Retrieves the Wayland display that Cogl is using. If a foreign display has been specified using Cogl.wayland_renderer_set_foreign_display() then that display will be returned. If no foreign display has been specified then the display that Cogl creates internally will be returned unless the renderer has not yet been connected (either implicitly or explicitly by calling Cogl.Renderer.connect()) in which case None is returned.

New in version 1.8.

Cogl.wayland_renderer_set_event_dispatch_enabled(renderer, enable)
Parameters:

Sets whether Cogl should handle calling wl_display_dispatch() and wl_display_flush() as part of its main loop integration via Cogl.poll_renderer_get_info() and Cogl.poll_renderer_dispatch(). The default value is True. When it is enabled the application can register listeners for Wayland interfaces and the callbacks will be invoked during Cogl.poll_renderer_dispatch(). If the application wants to integrate with its own code that is already handling reading from the Wayland display socket, it should disable this to avoid having competing code read from the socket.

New in version 1.16.

Cogl.wayland_renderer_set_foreign_display(renderer, display)
Parameters:

Allows you to explicitly control what Wayland display you want Cogl to work with instead of leaving Cogl to automatically connect to a wayland compositor.

New in version 1.8.

Cogl.wayland_texture_set_region_from_shm_buffer(texture, src_x, src_y, width, height, shm_buffer, dst_x, dst_y, level)
Parameters:

  • texture (Cogl.Texture) – a Cogl.Texture

  • src_x (int) – The X offset within the source bufer to copy from

  • src_y (int) – The Y offset within the source bufer to copy from

  • width (int) – The width of the region to copy

  • height (int) – The height of the region to copy

  • shm_buffer (object or None) – The source buffer

  • dst_x (int) – The X offset within the texture to copy to

  • dst_y (int) – The Y offset within the texture to copy to

  • level (int) – The mipmap level of the texture to copy to

Raises:

GLib.Error

Returns:

True if the subregion upload was successful, and False otherwise

Return type:

int

Sets the pixels in a rectangular subregion of texture from a Wayland SHM buffer. Generally this would be used in response to wl_surface.damage event in a compositor in order to update the texture with the damaged region. This is just a convenience wrapper around getting the SHM buffer pointer and calling Cogl.Texture.set_region(). See that function for a description of the level parameter.

Since the storage for a Cogl.Texture 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.

New in version 1.18.

Cogl.x11_onscreen_get_visual_xid(onscreen)
Parameters:

onscreen (Cogl.Onscreen) –

Return type:

int

Cogl.x11_onscreen_get_window_xid(onscreen)
Parameters:

onscreen (Cogl.Onscreen) – A Cogl.Onscreen framebuffer

Return type:

int

Assuming you know the given onscreen framebuffer is based on an x11 window this queries the XID of that window. If cogl_x11_onscreen_set_foreign_window_xid() was previously called then it will return that same XID otherwise it will be the XID of a window Cogl created internally. If the window has not been allocated yet and a foreign xid has not been set then it’s undefined what value will be returned.

It’s undefined what this function does if called when not using an x11 based renderer.

New in version 1.10.