4
Clutter supports multiple backends for handling windowing systems and
5
GL/GLES API on different platforms.
7
The GL and GLES API are abstracted by the COGL library. The windowing
8
system is handled by the ClutterBackend implementations inside Clutter
11
Clutter, at the moment, supports only in-tree backends.
13
In order to write a new backend for a specific platform you should
14
create a new sub-directory under clutter/clutter containing:
16
<backend>/clutter-backend-<backend>.h
17
<backend>/clutter-backend-<backend>.c
19
-- The subclass of the ClutterBackend abstract class.
21
<backend>/clutter-stage-<backend>.h
22
<backend>/clutter-stage-<backend>.c
24
-- The implementation of the stage actor.
26
<backend>/clutter-event-<backend>.c
28
-- The event handling code (optional).
30
<backend>/clutter-<backend>.h
32
-- A header for the backend-specific API that should be installed
33
by Clutter inside the include directory along with the rest of
34
the public API headers (optional).
37
Implementing ClutterBackend
38
---------------------------
40
Each backend must implement the
43
_clutter_backend_impl_get_type (void);
45
function declared inside clutter/clutter-private.h. The implementation
46
of the function must return the same GType of the backend implementation,
50
_clutter_backend_impl_get_type (void)
52
return CLUTTER_TYPE_BACKEND_GLX;
55
The ClutterBackend implementation is a singleton instance, and the
56
backend must ensure that every time g_object_new() is called the same
57
pointer is returned (with its reference count increased). The GObject
58
API reference describes how to use the ::constructor virtual function
59
to implement a singleton, so you should refer to that.
61
The ClutterBackend implementation should hold a single drawing context
62
for its entire lifetime; stage implementations should be "made current"
65
When implementing the ClutterBackend subclass these virtual functions
68
ClutterBackend::add_options
69
-- Use this function to install new, backend-specific GOptionEntry
70
definitions to the Clutter GOptionGroup. This function is guaranteed
71
to be called just once.
73
ClutterBackend::pre_parse
74
-- Use this function to check for environment variables or setting
75
up default values before the command line arguments are parsed.
76
This function is guaranteed to be called just once.
78
ClutterBackend::post_parse
79
-- Use this function to prepare the backend with the values either
80
set inside the ::pre_parse virtual function or by the command
81
line options parsing code. This function is guaranteed to be
84
ClutterBackend::init_events
85
-- Use this function to initialize the event handling. This function
86
is guaranteed to be called just once.
88
ClutterBackend::get_features
89
-- Use this function to retrieve the features detectable at runtime
90
from the GL or GLES implementation, plus the eventual backend-specific
93
ClutterBackend::get_display_size
94
-- Use this function to retrieve the size of the display.
96
ClutterBackend::ensure_context
97
-- This function is used to ensure that the backend drawing context
98
is made current for passed ClutterStage, using the backend-specific
101
ClutterBackend::redraw
102
-- This function is used to draw the passed ClutterStage; the backend
103
must call clutter_actor_paint() on the ClutterStage that has been
104
passed as a parameter and then perform backend-specific tasks, like
105
waiting for vertical blanking and swapping the buffers.
107
ClutterBackend::create_stage
108
-- This function is used to create the stage implementation. It will
109
receive as an argument the ClutterStage instance that is "wrapping"
110
the actual implementation being created. The backend must create
111
its stage implementation, initialise it and then return it; in case
112
of error, the backend must return NULL and set the passed GError.
114
Implementing the stage
115
----------------------
117
ClutterStage acts as a wrapper object relaying all the drawing operations
118
to the actual implementation. The implementation of the stage can be any
119
ClutterActor subclass, as long as it does not subclass ClutterStage and
120
it implements the ClutterStageWindow interface.
122
The ClutterStageWindow interface contains a set of virtual functions that
123
should be overridden by backends that support a windowing system, like
124
::set_title(), ::set_fullscreen(), ::set_cursor_visible(), etc.
126
The stage implementation actor must implement at least the ::realize and
127
::unrealize ClutterActor virtual functions. Inside the ::realize function
128
the stage implementation should:
130
- create a new native window handle
131
- if the backend doesn't have a drawing context (either GL or GLES),
132
create one and pass it to the backend
134
In case of failure, the CLUTTER_ACTOR_REALIZED flag should be unset on
135
the stage implementation.
137
Inside the ::unrealize function the stage implementation should:
139
- destroy the native window handle
144
If the platform is using X11 you should probably subclass ClutterBackendX11
145
and ClutterStageX11, which will provide you with a ready to use code
146
implementation for event handling and window management.
148
Usual points of failure for backends are:
150
- calling public API, like clutter_actor_paint(), or checking properties
151
on the stage implementation instead of the ClutterStage wrapper.
added
removed
HACKING.backends
