Top |
CoglRenderer: Connect to a backend rendererCoglRenderer: Connect to a backend renderer — Choosing a means to render |
Functions
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()
.
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
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()
.
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
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.
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.
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
);
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).
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.
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.
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
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
Implies no preference for which backend is used |
||
Use the no-op stub backend |
||
Use the GLX window system binding API |
||
Use EGL with the X window system via XLib |
||
Use EGL with the PowerVR NULL window system |
||
Use EGL with the GDL platform |
||
Use EGL with the Wayland window system |
||
Use EGL with the KMS platform |
||
Use EGL with the Android platform |
||
Use EGL with the Mir server |
||
Use the Microsoft Windows WGL binding API |
||
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
Require the renderer to be X11 based |
||
Require the renderer to be X11 based and use Xlib |
||
Require the renderer to be EGL based |
||
Require that the
renderer supports creating a CoglGLES2Context via
|
Since: 1.10
Stability Level: Unstable
enum CoglFilterReturn
Return values for the CoglXlibFilterFunc and CoglWin32FilterFunc functions.
Stability Level: Unstable