The Top-Level Context

The Top-Level Context — The top level application context.

Synopsis

                    CoglContext;
CoglBool            cogl_is_context                     (void *object);
CoglContext *       cogl_context_new                    (CoglDisplay *display,
                                                         CoglError **error);
CoglDisplay *       cogl_context_get_display            (CoglContext *context);

enum                CoglFeatureID;
CoglBool            cogl_has_feature                    (CoglContext *context,
                                                         CoglFeatureID feature);
CoglBool            cogl_has_features                   (CoglContext *context,
                                                         ...);
void                (*CoglFeatureCallback)              (CoglFeatureID feature,
                                                         void *user_data);
void                cogl_foreach_feature                (CoglContext *context,
                                                         CoglFeatureCallback callback,
                                                         void *user_data);


enum                CoglReadPixelsFlags;

Description

A CoglContext is the top most sandbox of Cogl state for an application or toolkit. Its main purpose is to act as a sandbox for the memory management of state objects. Normally an application will only create a single context since there is no way to share resources between contexts.

For those familiar with OpenGL or perhaps Cairo it should be understood that unlike these APIs a Cogl context isn't a rendering context as such. In other words Cogl doesn't aim to provide a state machine style model for configuring rendering parameters. Most rendering state in Cogl is directly associated with user managed objects called pipelines and geometry is drawn with a specific pipeline object to a framebuffer object and those 3 things fully define the state for drawing. This is an important part of Cogl's design since it helps you write orthogonal rendering components that can all access the same GPU without having to worry about what state other components have left you with.

Note

Cogl does not maintain internal references to the context for resources that depend on the context so applications. This is to help applications control the lifetime a context without us needing to introduce special api to handle the breakup of internal circular references due to internal resources and caches associated with the context.

One a context has been destroyed then all directly or indirectly dependant resources will be in an inconsistent state and should not be manipulated or queried in any way.

For applications that rely on the operating system to clean up resources this policy shouldn't affect them, but for applications that need to carefully destroy and re-create Cogl contexts multiple times throughout their lifetime (such as Android applications) they should be careful to destroy all context dependant resources, such as framebuffers or textures etc before unrefing and destroying the context.

Details

CoglContext

typedef struct _CoglContext CoglContext;

cogl_is_context ()

CoglBool            cogl_is_context                     (void *object);

Gets whether the given object references an existing context object.

object :

An object or NULL

Returns :

TRUE if the object references a CoglContext, FALSE otherwise

Since 1.10

Stability Level: Unstable


cogl_context_new ()

CoglContext *       cogl_context_new                    (CoglDisplay *display,
                                                         CoglError **error);

Creates a new CoglContext which acts as an application sandbox for any state objects that are allocated.

display :

A CoglDisplay pointer

error :

A CoglError return location.

Returns :

A newly allocated CoglContext. [transfer full]

Since 1.8

Stability Level: Unstable


cogl_context_get_display ()

CoglDisplay *       cogl_context_get_display            (CoglContext *context);

Retrieves the CoglDisplay that is internally associated with the given context. This will return the same CoglDisplay that was passed to cogl_context_new() or if NULL was passed to cogl_context_new() then this function returns a pointer to the display that was automatically setup internally.

context :

A CoglContext pointer

Returns :

The CoglDisplay associated with the given context. [transfer none]

Since 1.8

Stability Level: Unstable


enum CoglFeatureID

typedef enum {
  COGL_FEATURE_ID_TEXTURE_NPOT_BASIC = 1,
  COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP,
  COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT,
  COGL_FEATURE_ID_TEXTURE_NPOT,
  COGL_FEATURE_ID_TEXTURE_RECTANGLE,
  COGL_FEATURE_ID_TEXTURE_3D,
  COGL_FEATURE_ID_GLSL,
  COGL_FEATURE_ID_OFFSCREEN,
  COGL_FEATURE_ID_OFFSCREEN_MULTISAMPLE,
  COGL_FEATURE_ID_ONSCREEN_MULTIPLE,
  COGL_FEATURE_ID_UNSIGNED_INT_INDICES,
  COGL_FEATURE_ID_DEPTH_RANGE,
  COGL_FEATURE_ID_POINT_SPRITE,
  COGL_FEATURE_ID_MAP_BUFFER_FOR_READ,
  COGL_FEATURE_ID_MAP_BUFFER_FOR_WRITE,
  COGL_FEATURE_ID_MIRRORED_REPEAT,
  COGL_FEATURE_ID_GLES2_CONTEXT,
  COGL_FEATURE_ID_DEPTH_TEXTURE,
  COGL_FEATURE_ID_PRESENTATION_TIME,
  COGL_FEATURE_ID_FENCE,
  COGL_FEATURE_ID_PER_VERTEX_POINT_SIZE,
} CoglFeatureID;

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

COGL_FEATURE_ID_TEXTURE_NPOT_BASIC

The hardware supports non power of two textures, but you also need to check the COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP and COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT features to know if the hardware supports npot texture mipmaps or repeat modes other than COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE respectively.

COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP

Mipmapping is supported in conjuntion with non power of two textures.

COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT

Repeat modes other than COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE are supported by the hardware.

COGL_FEATURE_ID_TEXTURE_NPOT

Non power of two textures are supported by the hardware. This is a equivalent to the COGL_FEATURE_ID_TEXTURE_NPOT_BASIC, COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP and COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT features combined.

COGL_FEATURE_ID_TEXTURE_RECTANGLE

Support for rectangular textures with non-normalized texture coordinates.

COGL_FEATURE_ID_TEXTURE_3D

3D texture support

COGL_FEATURE_ID_GLSL

GLSL support

COGL_FEATURE_ID_OFFSCREEN

Offscreen rendering support

COGL_FEATURE_ID_OFFSCREEN_MULTISAMPLE

Multisample support for offscreen framebuffers

COGL_FEATURE_ID_ONSCREEN_MULTIPLE

Multiple onscreen framebuffers supported.

COGL_FEATURE_ID_UNSIGNED_INT_INDICES

Set if COGL_INDICES_TYPE_UNSIGNED_INT is supported in cogl_indices_new().

COGL_FEATURE_ID_DEPTH_RANGE

cogl_pipeline_set_depth_range() support

COGL_FEATURE_ID_POINT_SPRITE

Whether cogl_pipeline_set_layer_point_sprite_coords_enabled() is supported.

COGL_FEATURE_ID_MAP_BUFFER_FOR_READ

Whether cogl_buffer_map() is supported with CoglBufferAccess including read support.

COGL_FEATURE_ID_MAP_BUFFER_FOR_WRITE

Whether cogl_buffer_map() is supported with CoglBufferAccess including write support.

COGL_FEATURE_ID_MIRRORED_REPEAT

Whether COGL_PIPELINE_WRAP_MODE_MIRRORED_REPEAT is supported.

COGL_FEATURE_ID_GLES2_CONTEXT

Whether creating new GLES2 contexts is suported.

COGL_FEATURE_ID_DEPTH_TEXTURE

Whether CoglFramebuffer support rendering the depth buffer to a texture.

COGL_FEATURE_ID_PRESENTATION_TIME

Whether frame presentation time stamps will be recorded in CoglFrameInfo objects.

COGL_FEATURE_ID_FENCE

COGL_FEATURE_ID_PER_VERTEX_POINT_SIZE

Whether cogl_point_size_in can be used as an attribute to set a per-vertex point size.

Since 1.10


cogl_has_feature ()

CoglBool            cogl_has_feature                    (CoglContext *context,
                                                         CoglFeatureID feature);

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.

context :

A CoglContext pointer

feature :

A CoglFeatureID

Returns :

TRUE if the feature is currently supported or FALSE if not.

Since 1.10

Stability Level: Unstable


cogl_has_features ()

CoglBool            cogl_has_features                   (CoglContext *context,
                                                         ...);

Checks if a list of features are all currently available.

This checks all of the listed features using cogl_has_feature() and returns TRUE if all the features are available or FALSE otherwise.

context :

A CoglContext pointer

... :

A 0 terminated list of CoglFeatureIDs

Returns :

TRUE if all the features are available, FALSE otherwise.

Since 1.10

Stability Level: Unstable


CoglFeatureCallback ()

void                (*CoglFeatureCallback)              (CoglFeatureID feature,
                                                         void *user_data);

A callback used with cogl_foreach_feature() for enumerating all context level features supported by Cogl.

feature :

A single feature currently supported by Cogl

user_data :

A private pointer passed to cogl_foreach_feature().

Since 0.10

Stability Level: Unstable


cogl_foreach_feature ()

void                cogl_foreach_feature                (CoglContext *context,
                                                         CoglFeatureCallback callback,
                                                         void *user_data);

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

context :

A CoglContext pointer

callback :

A CoglFeatureCallback called for each supported feature

user_data :

Private data to pass to the callback

Since 1.10

Stability Level: Unstable


enum CoglReadPixelsFlags

typedef enum {
 /*< prefix=COGL_READ_PIXELS >*/
  COGL_READ_PIXELS_COLOR_BUFFER = 1L << 0
} CoglReadPixelsFlags;

Flags for cogl_framebuffer_read_pixels_into_bitmap()

COGL_READ_PIXELS_COLOR_BUFFER

Read from the color buffer

Since 1.0