CoglRenderer

typedef struct _CoglRenderer CoglRenderer;

cogl_is_renderer ()

CoglBool            cogl_is_renderer                    (void *object);

Determines if the given object is a CoglRenderer

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

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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.

Since 1.8

Stability Level: Unstable