CoglRenderer: Connect to a backend renderer

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

## Functions

CoglBool | cogl_is_renderer ()
CoglRenderer * | cogl_renderer_new ()
int | cogl_renderer_get_n_fragment_texture_units ()
CoglBool | cogl_renderer_connect ()
void | cogl_renderer_set_winsys_id ()
CoglWinsysID | cogl_renderer_get_winsys_id ()
void | cogl_renderer_add_constraint ()
void | cogl_renderer_remove_constraint ()
void | cogl_xlib_renderer_set_foreign_display ()
Display * | cogl_xlib_renderer_get_foreign_display ()
CoglFilterReturn | (*CoglXlibFilterFunc) ()
void | cogl_xlib_renderer_add_filter ()
void | cogl_xlib_renderer_remove_filter ()
CoglFilterReturn | cogl_xlib_renderer_handle_event ()
CoglFilterReturn | (*CoglWin32FilterFunc) ()
void | cogl_win32_renderer_add_filter ()
void | cogl_win32_renderer_remove_filter ()
CoglFilterReturn | cogl_win32_renderer_handle_event ()
void | cogl_win32_renderer_set_event_retrieval_enabled ()
void | cogl_wayland_renderer_set_foreign_display ()
void | cogl_wayland_renderer_set_event_dispatch_enabled ()
struct wl_display * | cogl_wayland_renderer_get_display ()

## Types and Values

| CoglRenderer
enum | CoglWinsysID
enum | CoglRendererConstraint
enum | CoglFilterReturn

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

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.

## Functions

### cogl_is_renderer ()

    CoglBool
    cogl_is_renderer (void *object);

Determines if the given `object` is a CoglRenderer

#### Parameters

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

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.

#### Returns

A newly created CoglRenderer.

[transfer full]

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

#### Parameters

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.

#### Parameters

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

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

#### Parameters

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.

#### Parameters

renderer | A CoglRenderer |

#### Returns

The CoglWinsysID corresponding to the chosen window system backend.

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

#### Parameters

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.

#### Parameters

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

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

## Types and Values

### CoglRenderer

    typedef struct _CoglRenderer CoglRenderer;

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

#### Members

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 |

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

#### Members

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

### enum CoglFilterReturn

Return values for the CoglXlibFilterFunc and CoglWin32FilterFunc functions.

#### Members

COGL_FILTER_CONTINUE | The event was not handled, continues the processing |
COGL_FILTER_REMOVE | Remove the event, stops the processing |

Stability Level: Unstable