### Namespace

# Cogl – 12

A Low Level GPU Graphics and Utilities API

Version | 12
Authors | Mutter Development Team
License | GPL-2.0-or-later
Website | https://blogs.gnome.org/shell-dev/
Source | https://gitlab.gnome.org/GNOME/mutter/

#### Build

C headers | `cogl/cogl.h`
pkg-config files | ``

#### Dependencies

GObject—2.0 | The base type system library
| Browse documentation
Graphene—1.0 | A thin layer of mathematical types for 3D libraries
| Browse documentation
cairo—1.0 | A 2D graphics library with support for multiple output devices
| Browse documentation

#### Additional documentation

- Classes Hierarchy

#### Classes

Bitmap |
Context |
Framebuffer |
FrameInfo | Frame information.
Object |
Offscreen |
Onscreen |
Pipeline |
Snippet |
Texture2D |
Texture2DSliced |

#### Interfaces

Texture |

#### Structs

_ColorSizeCheck |
_TextureVertexSizeCheck |
Color | A structure for holding a color definition. The contents of the CoglColor structure are private and should never by accessed directly.
DebugObjectTypeInfo | This struct is used to pass information to the callback when `cogl_debug_object_foreach_type()` is called.
DmaBufHandle | An opaque type that tracks the lifetime of a DMA buffer fd. Release with cogl_dma_buf_handle_free().
FramebufferDriverConfig |
FrameClosure | An opaque type that tracks a `CoglFrameCallback` and associated user data. A `CoglFrameClosure` pointer will be returned from `cogl_onscreen_add_frame_callback()` and it allows you to remove a callback later using cogl_onscreen_remove_frame_callback().
OnscreenDirtyClosure | An opaque type that tracks a `CoglOnscreenDirtyCallback` and associated user data. A `CoglOnscreenDirtyClosure` pointer will be returned from `cogl_onscreen_add_dirty_callback()` and it allows you to remove a callback later using cogl_onscreen_remove_dirty_callback().
OnscreenDirtyInfo | A structure passed to callbacks registered using cogl_onscreen_add_dirty_callback(). The members describe a rectangle within the onscreen buffer that should be redrawn.
Scanout |
TextureVertex | Used to specify vertex information when calling `cogl_polygon()`
TimestampQuery |
TraceContext |
TraceHead |
UserDataKey | A `CoglUserDataKey` is used to declare a key for attaching data to a `CoglObject` using cogl_object_set_user_data. The typedef only exists as a formality to make code self documenting since only the unique address of a `CoglUserDataKey` is used.

#### Aliases

Angle | Integer representation of an angle such that 1024 corresponds to full circle (i.e., 2 * pi).
Handle | Type used for storing references to cogl objects, the CoglHandle is a fully opaque type without any public data members.
PipelineKey |
UserDataDestroyCallback | When associating private data with a `CoglObject` a callback can be given which will be called either if the object is destroyed or if `cogl_object_set_user_data()` is called with NULL user_data for the same key.

#### Enumerations

AttributeType | Data types for the components of a vertex attribute.
BitmapError | Error codes that can be thrown when performing bitmap operations. Note that `gdk_pixbuf_new_from_file()` can also throw errors directly from the underlying image loading library. For example, if GdkPixbuf is used then errors `GdkPixbufError`s will be used directly.
BlendStringError | Error enumeration for the blend strings parser.
DepthTestFunction | When using depth testing one of these functions is used to compare the depth of an incoming fragment against the depth value currently stored in the depth buffer. The function is changed using cogl_depth_state_set_test_function().
FeatureID | All the capabilities that can vary between different GPUs supported by Cogl. Applications that depend on any of these features should explicitly check for them using `cogl_has_feature()` or cogl_has_features().
FilterReturn | Return values for the `CoglXlibFilterFunc` and `CoglWin32FilterFunc` functions.
FramebufferError |
FrameEvent | Identifiers that are passed to `CoglFrameCallback` functions (registered using cogl_onscreen_add_frame_callback()) that mark the progression of a frame in some way which usually means that new information will have been accumulated in the frame’s corresponding `CoglFrameInfo` object.
GraphicsResetStatus | All the error values that might be returned by cogl_get_graphics_reset_status(). Each value’s meaning corresponds to the similarly named value defined in the ARB_robustness and NV_robustness_video_memory_purge extensions.
IndicesType | You should aim to use the smallest data type that gives you enough range, since it reduces the size of your index array and can help reduce the demand on memory bandwidth.
PipelineAlphaFunc | Alpha testing happens before blending primitives with the framebuffer and gives an opportunity to discard fragments based on a comparison with the incoming alpha value and a reference alpha value. The `CoglPipelineAlphaFunc` determines how the comparison is done.
PipelineCullFaceMode | Specifies which faces should be culled. This can be set on a pipeline using cogl_pipeline_set_cull_face_mode().
PipelineFilter | Texture filtering is used whenever the current pixel maps either to more than one texture element (texel) or less than one. These filter enums correspond to different strategies used to come up with a pixel color, by possibly referring to multiple neighbouring texels and taking a weighted average or simply using the nearest texel.
PipelineWrapMode | The wrap mode specifies what happens when texture coordinates outside the range 0→1 are used. Note that if the filter mode is anything but `COGL_PIPELINE_FILTER_NEAREST` then texels outside the range 0→1 might be used even when the coordinate is exactly 0 or 1 because OpenGL will try to sample neighbouring pixels. For example if you are trying to render the full texture then you may get artifacts around the edges when the pixels from the other side are merged in if the wrap mode is set to repeat.
RendererError |
ShaderType | Types of shaders.
SnippetHook | `CoglSnippetHook` is used to specify a location within a `CoglPipeline` where the code of the snippet should be used when it is attached to a pipeline.
StereoMode | Represents how draw should affect the two buffers of a stereo framebuffer. See cogl_framebuffer_set_stereo_mode().
SystemError | Error enumeration for Cogl.
TextureComponents | See cogl_texture_set_components().
TextureError | Error codes that can be thrown when allocating textures.
VerticesMode | Different ways of interpreting vertices when drawing.
Winding | Enum used to represent the two directions of rotation. This can be used to set the front face for culling by calling cogl_pipeline_set_front_face_winding().
WinsysFeature |

#### Bitfields

BufferBit | Types of auxiliary buffers.
BufferTarget | Target flags for FBOs.
EglImageFlags |
PixelFormat | Pixel formats used by Cogl. For the formats with a byte per component, the order of the components specify the order in increasing memory addresses. So for example `COGL_PIXEL_FORMAT_RGB_888` would have the red component in the lowest address, green in the next address and blue after that regardless of the endianness of the system.
ReadPixelsFlags | Flags for `cogl_framebuffer_read_pixels_into_bitmap()`

#### Error Domains

ScanoutError |

#### Callbacks

DebugObjectForeachTypeCallback | A callback function to use for cogl_debug_object_foreach_type().
FeatureCallback | A callback used with `cogl_foreach_feature()` for enumerating all context level features supported by Cogl.
FrameCallback | Is a callback that can be registered via `cogl_onscreen_add_frame_callback()` to be called when a frame progresses in some notable way.
OnscreenDirtyCallback | Is a callback that can be registered via `cogl_onscreen_add_dirty_callback()` to be called when the windowing system determines that a region of the onscreen window has been lost and the application should redraw it.
PipelineLayerCallback | The callback prototype used with `cogl_pipeline_foreach_layer()` for iterating all the layers of a `pipeline`.
Texture2DEGLImageExternalAlloc |
XlibFilterFunc |

#### Functions

blend_string_error_quark |
blit_framebuffer | `return` FALSE for an immediately detected error, TRUE otherwise.
clutter_winsys_has_feature_CLUTTER |
create_program | Create a new cogl program object that can be used to replace parts of the GL rendering pipeline with custom code. deprecated: 1.16
create_shader | Create a new shader handle, use `cogl_shader_source()` to set the source code to be used on it. deprecated: 1.16
debug_object_foreach_type | 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.
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.
egl_texture_2d_new_from_image |
flush | This function should only need to be called in exceptional circumstances.
foreach_feature | Iterates through all the context level features currently supported for a given `context` and for each feature `callback` is called.
get_graphics_reset_status | Returns the graphics reset status as reported by GetGraphicsResetStatusARB defined in the ARB_robustness extension.
get_proc_address | Gets a pointer to a given GL or GL ES extension function. This acts as a wrapper around glXGetProcAddress() or whatever is the appropriate function for the current backend.
handle_get_type |
has_feature | Checks if a given `feature` is currently available.
has_features | Checks if a list of features are all currently available.
is_bitmap | Checks whether `object` is a `CoglBitmap`.
is_context | Gets whether the given object references an existing context object.
is_frame_info | Gets whether the given object references a `CoglFrameInfo`.
is_framebuffer | Gets whether the given object references a `CoglFramebuffer`.
is_pipeline | Gets whether the given `object` references an existing pipeline object.
is_program | Gets whether the given handle references an existing program object. deprecated: 1.16
is_shader | Gets whether the given handle references an existing shader object. deprecated: 1.16
is_snippet | Gets whether the given `object` references an existing snippet object.
is_texture | Gets whether the given object references a texture object.
is_texture_2d | Gets whether the given object references an existing `CoglTexture2D` object.
is_texture_2d_sliced | Gets whether the given object references a `CoglTexture2DSliced`.
pixel_format_get_bytes_per_pixel | Queries the number of bytes per pixel for a given format in the given plane.
pixel_format_get_n_planes | Returns the number of planes the given CoglPixelFormat specifies.
pixel_format_to_string | Returns a string representation of `format`, useful for debugging purposes.
program_attach_shader | Attaches a shader to a program object. A program can have multiple vertex or fragment shaders but only one of them may provide a `main()` function. It is allowed to use a program with only a vertex shader or only a fragment shader. deprecated: 1.16
program_get_uniform_location | Retrieve the location (offset) of a uniform variable in a shader program, a uniform is a variable that is constant for all vertices/fragments for a shader object and is possible to modify as an external parameter. deprecated: 1.16
program_link | Links a program making it ready for use. Note that calling this function is optional. If it is not called the program will automatically be linked the first time it is used. deprecated: 1.16
program_set_uniform_1f | Changes the value of a floating point uniform for the given linked `program`. deprecated: 1.16
program_set_uniform_1i | Changes the value of an integer uniform for the given linked `program`. deprecated: 1.16
program_set_uniform_float | Changes the value of a float vector uniform, or uniform array for the given linked `program`. deprecated: 1.16
program_set_uniform_int | Changes the value of a int vector uniform, or uniform array for the given linked `program`. deprecated: 1.16
program_set_uniform_matrix | Changes the value of a matrix uniform, or uniform array in the given linked `program`. deprecated: 1.16
set_tracing_disabled_on_thread |
set_tracing_enabled_on_thread |
set_tracing_enabled_on_thread_with_fd |
shader_get_type | Retrieves the type of a shader `CoglHandle`. deprecated: 1.16
shader_source | Replaces the current source associated with a shader with a new one. deprecated: 1.16
trace_describe |
trace_end |
xlib_renderer_add_filter | Adds a callback function that will receive all native events. The function can stop further processing of the event by return `COGL_FILTER_REMOVE`.
xlib_renderer_get_display |
xlib_renderer_get_foreign_display |
xlib_renderer_handle_event | This function processes a single event; it can be used to hook into external event retrieval (for example that done by Clutter or GDK).
xlib_renderer_remove_filter | Removes a callback that was previously added with cogl_xlib_renderer_add_filter().
xlib_renderer_request_reset_on_video_memory_purge | Sets whether Cogl should make use of the NV_robustness_video_memory_purge extension, if exposed by the driver, by initializing the GLX context appropriately.
xlib_renderer_set_foreign_display | Sets a foreign Xlib display that Cogl will use for and Xlib based winsys backend.

#### Function Macros

BUFFER |
clear_object | Clears a reference to a `CoglObject`.
META_TEXTURE |
PIXEL_FORMAT_CAN_HAVE_PREMULT |
PRIMITIVE_TEXTURE |
PRIVATE |
STRUCT_SIZE_ASSERT |
TRACE_ANCHOR |
TRACE_BEGIN |
TRACE_BEGIN_ANCHORED |
TRACE_BEGIN_SCOPED |
TRACE_DESCRIBE |
TRACE_END |
TRACE_SCOPED_ANCHOR |

#### Constants

A_BIT |
AFIRST_BIT |
BGR_BIT |
DEPTH_BIT |
PIXEL_FORMAT_MAX_PLANES | The maximum number of planes of a pixel format (see also cogl_pixel_format_get_planes()).
PREMULT_BIT |
STENCIL_BIT |
TEXTURE_MAX_WASTE |