CoglRenderer: Connect to a backend renderer

CoglRenderer: Connect to a backend renderer — Choosing a means to render

Synopsis

                    CoglRenderer;
CoglBool            cogl_is_renderer                    (void *object);

CoglRenderer *      cogl_renderer_new                   (void);
int                 cogl_renderer_get_n_fragment_texture_units
                                                        (CoglRenderer *renderer);
CoglBool            cogl_renderer_connect               (CoglRenderer *renderer,
                                                         CoglError **error);

enum                CoglWinsysID;
void                cogl_renderer_set_winsys_id         (CoglRenderer *renderer,
                                                         CoglWinsysID winsys_id);
CoglWinsysID        cogl_renderer_get_winsys_id         (CoglRenderer *renderer);
enum                CoglRendererConstraint;
void                cogl_renderer_add_constraint        (CoglRenderer *renderer,
                                                         CoglRendererConstraint constraint);
void                cogl_renderer_remove_constraint     (CoglRenderer *renderer,
                                                         CoglRendererConstraint constraint);

void                cogl_xlib_renderer_set_foreign_display
                                                        (CoglRenderer *renderer,
                                                         Display *display);
Display *           cogl_xlib_renderer_get_foreign_display
                                                        (CoglRenderer *renderer);

CoglFilterReturn    (*CoglXlibFilterFunc)               (XEvent *event,
                                                         void *data);
enum                CoglFilterReturn;
void                cogl_xlib_renderer_add_filter       (CoglRenderer *renderer,
                                                         CoglXlibFilterFunc func,
                                                         void *data);
void                cogl_xlib_renderer_remove_filter    (CoglRenderer *renderer,
                                                         CoglXlibFilterFunc func,
                                                         void *data);
CoglFilterReturn    cogl_xlib_renderer_handle_event     (CoglRenderer *renderer,
                                                         XEvent *event);

CoglFilterReturn    (*CoglWin32FilterFunc)              (MSG *message,
                                                         void *data);
void                cogl_win32_renderer_add_filter      (CoglRenderer *renderer,
                                                         CoglWin32FilterFunc func,
                                                         void *data);
void                cogl_win32_renderer_remove_filter   (CoglRenderer *renderer,
                                                         CoglWin32FilterFunc func,
                                                         void *data);
CoglFilterReturn    cogl_win32_renderer_handle_event    (CoglRenderer *renderer,
                                                         MSG *message);
void                cogl_win32_renderer_set_event_retrieval_enabled
                                                        (CoglRenderer *renderer,
                                                         CoglBool enable);

void                cogl_wayland_renderer_set_foreign_display
                                                        (CoglRenderer *renderer,
                                                         struct wl_display *display);
void                cogl_wayland_renderer_set_event_dispatch_enabled
                                                        (CoglRenderer *renderer,
                                                         CoglBool enable);
struct wl_display * cogl_wayland_renderer_get_display   (CoglRenderer *renderer);

Description

A CoglRenderer represents a means to render. It encapsulates the selection of an underlying driver, such as OpenGL or OpenGL-ES and a selection of a window system binding API such as GLX, or EGL or WGL.

A CoglRenderer has two states, "unconnected" and "connected". When a renderer is first instantiated using cogl_renderer_new() it is unconnected so that it can be configured and constraints can be specified for how the backend driver and window system should be chosen.

After configuration a CoglRenderer can (optionally) be explicitly connected using cogl_renderer_connect() which allows for the handling of connection errors so that fallback configurations can be tried if necessary. Applications that don't support any fallbacks though can skip using cogl_renderer_connect() and leave Cogl to automatically connect the renderer.

Once you have a configured CoglRenderer it can be used to create a CoglDisplay object using cogl_display_new().

Note

Many applications don't need to explicitly use cogl_renderer_new() or cogl_display_new() and can just jump straight to cogl_context_new() and pass a NULL display argument so Cogl will automatically connect and setup a renderer and display.

Details

CoglRenderer

typedef struct _CoglRenderer CoglRenderer;

cogl_is_renderer ()

CoglBool            cogl_is_renderer                    (void *object);

Determines if the given object is a CoglRenderer

object :

A CoglObject pointer

Returns :

TRUE if object is a CoglRenderer, else FALSE.

Since 1.10

Stability Level: Unstable


cogl_renderer_new ()

CoglRenderer *      cogl_renderer_new                   (void);

Instantiates a new (unconnected) CoglRenderer object. A CoglRenderer represents a means to render. It encapsulates the selection of an underlying driver, such as OpenGL or OpenGL-ES and a selection of a window system binding API such as GLX, or EGL or WGL.

While the renderer is unconnected it can be configured so that applications may specify backend constraints, such as "must use x11" for example via cogl_renderer_add_constraint().

There are also some platform specific configuration apis such as cogl_xlib_renderer_set_foreign_display() that may also be used while the renderer is unconnected.

Once the renderer has been configured, then it may (optionally) be explicitly connected using cogl_renderer_connect() which allows errors to be handled gracefully and potentially fallback configurations can be tried out if there are initial failures.

If a renderer is not explicitly connected then cogl_display_new() will automatically connect the renderer for you. If you don't have any code to deal with error/fallback situations then its fine to just let Cogl do the connection for you.

Once you have setup your renderer then the next step is to create a CoglDisplay using cogl_display_new().

Note

Many applications don't need to explicitly use cogl_renderer_new() or cogl_display_new() and can just jump straight to cogl_context_new() and pass a NULL display argument so Cogl will automatically connect and setup a renderer and display.

Since 1.10

Stability Level: Unstable


cogl_renderer_get_n_fragment_texture_units ()

int                 cogl_renderer_get_n_fragment_texture_units
                                                        (CoglRenderer *renderer);

Queries how many texture units can be used from fragment programs

renderer :

A CoglRenderer

Returns :

the number of texture image units.

Since 1.8

Stability Level: Unstable


cogl_renderer_connect ()

CoglBool            cogl_renderer_connect               (CoglRenderer *renderer,
                                                         CoglError **error);

Connects the configured renderer. Renderer connection isn't a very active process, it basically just means validating that any given constraint criteria can be satisfied and that a usable driver and window system backend can be found.

renderer :

An unconnected CoglRenderer

error :

a pointer to a CoglError for reporting exceptions

Returns :

TRUE if there was no error while connecting the given renderer. FALSE if there was an error.

Since 1.10

Stability Level: Unstable


enum CoglWinsysID

typedef enum {
  COGL_WINSYS_ID_ANY,
  COGL_WINSYS_ID_STUB,
  COGL_WINSYS_ID_GLX,
  COGL_WINSYS_ID_EGL_XLIB,
  COGL_WINSYS_ID_EGL_NULL,
  COGL_WINSYS_ID_EGL_GDL,
  COGL_WINSYS_ID_EGL_WAYLAND,
  COGL_WINSYS_ID_EGL_KMS,
  COGL_WINSYS_ID_EGL_ANDROID,
  COGL_WINSYS_ID_WGL,
  COGL_WINSYS_ID_SDL
} CoglWinsysID;

Identifies specific window system backends that Cogl supports.

These can be used to query what backend Cogl is using or to try and explicitly select a backend to use.

COGL_WINSYS_ID_ANY

Implies no preference for which backend is used

COGL_WINSYS_ID_STUB

Use the no-op stub backend

COGL_WINSYS_ID_GLX

Use the GLX window system binding API

COGL_WINSYS_ID_EGL_XLIB

Use EGL with the X window system via XLib

COGL_WINSYS_ID_EGL_NULL

Use EGL with the PowerVR NULL window system

COGL_WINSYS_ID_EGL_GDL

Use EGL with the GDL platform

COGL_WINSYS_ID_EGL_WAYLAND

Use EGL with the Wayland window system

COGL_WINSYS_ID_EGL_KMS

Use EGL with the KMS platform

COGL_WINSYS_ID_EGL_ANDROID

Use EGL with the Android platform

COGL_WINSYS_ID_WGL

Use the Microsoft Windows WGL binding API

COGL_WINSYS_ID_SDL

Use the SDL window system

cogl_renderer_set_winsys_id ()

void                cogl_renderer_set_winsys_id         (CoglRenderer *renderer,
                                                         CoglWinsysID winsys_id);

This allows you to explicitly select a winsys backend to use instead of letting Cogl automatically select a backend.

if you select an unsupported backend then cogl_renderer_connect() will fail and report an error.

This may only be called on an un-connected CoglRenderer.

renderer :

A CoglRenderer

winsys_id :

An ID of the winsys you explicitly want to use.

cogl_renderer_get_winsys_id ()

CoglWinsysID        cogl_renderer_get_winsys_id         (CoglRenderer *renderer);

Queries which window system backend Cogl has chosen to use.

This may only be called on a connected CoglRenderer.

renderer :

A CoglRenderer

Returns :

The CoglWinsysID corresponding to the chosen window system backend.

enum CoglRendererConstraint

typedef enum {
  COGL_RENDERER_CONSTRAINT_USES_X11 = (1 << 0),
  COGL_RENDERER_CONSTRAINT_USES_XLIB = (1 << 1),
  COGL_RENDERER_CONSTRAINT_USES_EGL = (1 << 2),
  COGL_RENDERER_CONSTRAINT_SUPPORTS_COGL_GLES2 = (1 << 3)
} CoglRendererConstraint;

These constraint flags are hard-coded features of the different renderer backends. Sometimes a platform may support multiple rendering options which Cogl will usually choose from automatically. Some of these features are important to higher level applications and frameworks though, such as whether a renderer is X11 based because an application might only support X11 based input handling. An application might also need to ensure EGL is used internally too if they depend on access to an EGLDisplay for some purpose.

Applications should ideally minimize how many of these constraints they depend on to ensure maximum portability.

COGL_RENDERER_CONSTRAINT_USES_X11

Require the renderer to be X11 based

COGL_RENDERER_CONSTRAINT_USES_XLIB

Require the renderer to be X11 based and use Xlib

COGL_RENDERER_CONSTRAINT_USES_EGL

Require the renderer to be EGL based

COGL_RENDERER_CONSTRAINT_SUPPORTS_COGL_GLES2

Require that the renderer supports creating a CoglGLES2Context via cogl_gles2_context_new(). This can be used to integrate GLES 2.0 code into Cogl based applications.

Since 1.10

Stability Level: Unstable


cogl_renderer_add_constraint ()

void                cogl_renderer_add_constraint        (CoglRenderer *renderer,
                                                         CoglRendererConstraint constraint);

This adds a renderer selection constraint.

Applications should ideally minimize how many of these constraints they depend on to ensure maximum portability.

renderer :

An unconnected CoglRenderer

constraint :

A CoglRendererConstraint to add

Since 1.10

Stability Level: Unstable


cogl_renderer_remove_constraint ()

void                cogl_renderer_remove_constraint     (CoglRenderer *renderer,
                                                         CoglRendererConstraint constraint);

This removes a renderer selection constraint.

Applications should ideally minimize how many of these constraints they depend on to ensure maximum portability.

renderer :

An unconnected CoglRenderer

constraint :

A CoglRendererConstraint to remove

Since 1.10

Stability Level: Unstable


cogl_xlib_renderer_set_foreign_display ()

void                cogl_xlib_renderer_set_foreign_display
                                                        (CoglRenderer *renderer,
                                                         Display *display);

cogl_xlib_renderer_get_foreign_display ()

Display *           cogl_xlib_renderer_get_foreign_display
                                                        (CoglRenderer *renderer);

CoglXlibFilterFunc ()

CoglFilterReturn    (*CoglXlibFilterFunc)               (XEvent *event,
                                                         void *data);

enum CoglFilterReturn

typedef enum {
 /*< prefix=COGL_FILTER >*/
  COGL_FILTER_CONTINUE,
  COGL_FILTER_REMOVE
} CoglFilterReturn;

Return values for the CoglXlibFilterFunc and CoglWin32FilterFunc functions.

COGL_FILTER_CONTINUE

The event was not handled, continues the processing

COGL_FILTER_REMOVE

Remove the event, stops the processing

Stability Level: Unstable


cogl_xlib_renderer_add_filter ()

void                cogl_xlib_renderer_add_filter       (CoglRenderer *renderer,
                                                         CoglXlibFilterFunc func,
                                                         void *data);

cogl_xlib_renderer_remove_filter ()

void                cogl_xlib_renderer_remove_filter    (CoglRenderer *renderer,
                                                         CoglXlibFilterFunc func,
                                                         void *data);

cogl_xlib_renderer_handle_event ()

CoglFilterReturn    cogl_xlib_renderer_handle_event     (CoglRenderer *renderer,
                                                         XEvent *event);

CoglWin32FilterFunc ()

CoglFilterReturn    (*CoglWin32FilterFunc)              (MSG *message,
                                                         void *data);

A callback function that can be registered with cogl_win32_renderer_add_filter(). The function should return COGL_FILTER_REMOVE if it wants to prevent further processing or COGL_FILTER_CONTINUE otherwise.

message :

A pointer to a win32 MSG struct

data :

The data that was given when the filter was added

cogl_win32_renderer_add_filter ()

void                cogl_win32_renderer_add_filter      (CoglRenderer *renderer,
                                                         CoglWin32FilterFunc func,
                                                         void *data);

Adds a callback function that will receive all native events. The function can stop further processing of the event by return COGL_FILTER_REMOVE.

renderer :

a CoglRenderer

func :

the callback function

data :

user data passed to func when called

cogl_win32_renderer_remove_filter ()

void                cogl_win32_renderer_remove_filter   (CoglRenderer *renderer,
                                                         CoglWin32FilterFunc func,
                                                         void *data);

Removes a callback that was previously added with cogl_win32_renderer_add_filter().

renderer :

a CoglRenderer

func :

the callback function

data :

user data given when the callback was installed

cogl_win32_renderer_handle_event ()

CoglFilterReturn    cogl_win32_renderer_handle_event    (CoglRenderer *renderer,
                                                         MSG *message);

This function processes a single event; it can be used to hook into external event retrieval (for example that done by Clutter or GDK).

renderer :

a CoglRenderer

message :

A pointer to a win32 MSG struct

Returns :

CoglFilterReturn. COGL_FILTER_REMOVE indicates that Cogl has internally handled the event and the caller should do no further processing. COGL_FILTER_CONTINUE indicates that Cogl is either not interested in the event, or has used the event to update internal state without taking any exclusive action.

cogl_win32_renderer_set_event_retrieval_enabled ()

void                cogl_win32_renderer_set_event_retrieval_enabled
                                                        (CoglRenderer *renderer,
                                                         CoglBool enable);

Sets whether Cogl should automatically retrieve messages from Windows. It defaults to TRUE. It can be set to FALSE if the application wants to handle its own message retrieval. Note that Cogl still needs to see all of the messages to function properly so the application should call cogl_win32_renderer_handle_event() for each message if it disables automatic event retrieval.

renderer :

a CoglRenderer

enable :

The new value

Since 1.16

Stability Level: Unstable


cogl_wayland_renderer_set_foreign_display ()

void                cogl_wayland_renderer_set_foreign_display
                                                        (CoglRenderer *renderer,
                                                         struct wl_display *display);

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.

renderer :

A CoglRenderer

display :

A Wayland display

Since 1.8

Stability Level: Unstable


cogl_wayland_renderer_set_event_dispatch_enabled ()

void                cogl_wayland_renderer_set_event_dispatch_enabled
                                                        (CoglRenderer *renderer,
                                                         CoglBool enable);

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.

renderer :

A CoglRenderer

enable :

The new value

Since 1.16

Stability Level: Unstable


cogl_wayland_renderer_get_display ()

struct wl_display * cogl_wayland_renderer_get_display   (CoglRenderer *renderer);

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 NULL is returned.

renderer :

A CoglRenderer

Returns :

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

Since 1.8

Stability Level: Unstable