## 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