208 lines
8.0 KiB
Plaintext
208 lines
8.0 KiB
Plaintext
IMPLEMENTING BACKENDS
|
|
===============================================================================
|
|
|
|
Clutter supports multiple backends for handling windowing systems and
|
|
GL/GLES API on different platforms.
|
|
|
|
The GL and GLES API are abstracted by the COGL library. The windowing
|
|
system is handled by the ClutterBackend implementations inside Clutter
|
|
itself.
|
|
|
|
Clutter, at the moment, supports only in-tree backends.
|
|
|
|
In order to write a new backend for a specific platform you should
|
|
create a new sub-directory under clutter/clutter containing:
|
|
|
|
<backend>/clutter-backend-<backend>.h
|
|
<backend>/clutter-backend-<backend>.c
|
|
|
|
-- The subclass of the ClutterBackend abstract class.
|
|
|
|
<backend>/clutter-stage-<backend>.h
|
|
<backend>/clutter-stage-<backend>.c
|
|
|
|
-- The implementation of the stage window
|
|
|
|
<backend>/clutter-device-manager-<backend>.h
|
|
<backend>/clutter-device-manager-<backend>.c
|
|
|
|
-- The implementation of the input device manager
|
|
|
|
<backend>/clutter-event-<backend>.c
|
|
|
|
-- Event-specific code (optional)
|
|
|
|
<backend>/clutter-<backend>.h
|
|
|
|
-- A header for the backend-specific API that should be installed
|
|
by Clutter inside the include directory along with the rest of
|
|
the public API headers (optional).
|
|
|
|
|
|
Implementing ClutterBackend
|
|
-------------------------------------------------------------------------------
|
|
|
|
Each backend must implement the
|
|
|
|
GType
|
|
_clutter_backend_impl_get_type (void);
|
|
|
|
function declared inside clutter/clutter-private.h. The implementation
|
|
of the function must return the same GType of the backend implementation,
|
|
for instance:
|
|
|
|
GType
|
|
_clutter_backend_impl_get_type (void)
|
|
{
|
|
return CLUTTER_TYPE_BACKEND_GLX;
|
|
}
|
|
|
|
The ClutterBackend implementation is a singleton instance, and the
|
|
backend must ensure that every time g_object_new() is called the same
|
|
pointer is returned (with its reference count increased). The GObject
|
|
API reference describes how to use the ::constructor virtual function
|
|
to implement a singleton, so you should refer to that.
|
|
|
|
The ClutterBackend implementation should hold a single drawing context
|
|
for its entire lifetime; stage implementations should be "made current"
|
|
when needed.
|
|
|
|
When implementing the ClutterBackend subclass these virtual functions
|
|
can be overridden:
|
|
|
|
ClutterBackend::add_options
|
|
-- Use this function to install new, backend-specific GOptionEntry
|
|
definitions to the Clutter GOptionGroup. This function is guaranteed
|
|
to be called just once.
|
|
|
|
ClutterBackend::pre_parse
|
|
-- Use this function to check for environment variables or setting
|
|
up default values before the command line arguments are parsed.
|
|
This function is guaranteed to be called just once.
|
|
|
|
ClutterBackend::post_parse
|
|
-- Use this function to prepare the backend with the values either
|
|
set inside the ::pre_parse virtual function or by the command
|
|
line options parsing code. This function is guaranteed to be
|
|
called just once.
|
|
|
|
ClutterBackend::init_events
|
|
-- Use this function to initialize the event handling. This function
|
|
is guaranteed to be called just once.
|
|
|
|
ClutterBackend::get_features
|
|
-- Use this function to retrieve the features detectable at runtime
|
|
from the GL or GLES implementation, plus the eventual backend-specific
|
|
features.
|
|
|
|
ClutterBackend::create_context
|
|
-- This function is used to create the drawing context to be used
|
|
by Clutter. Clutter will call this function during the initialization
|
|
phase. A GL (or GLES) context must always be available after the
|
|
initialization, so that Cogl and Clutter can query it for capabilities.
|
|
This function might be called multiple times so if a context was
|
|
successfully created in a previous call, this function should
|
|
short-circuit early and return TRUE
|
|
|
|
ClutterBackend::ensure_context
|
|
-- This function is used to ensure that the backend drawing context
|
|
is made current for passed ClutterStage, using the backend-specific
|
|
API. This function is called each time a new stage is going to
|
|
be painted. If the Stage is inside its destruction sequence this
|
|
function should either fall back the drawing context to a default
|
|
drawing surface or should unset the drawing surface from the
|
|
drawing context.
|
|
|
|
ClutterBackend::create_stage
|
|
-- This function is used to create the stage implementation. It will
|
|
receive as an argument the ClutterStage instance that is "wrapping"
|
|
the actual implementation being created. The backend must create
|
|
its stage implementation, initialise it and then return it; in case
|
|
of error, the backend must return NULL and set the passed GError.
|
|
|
|
ClutterBackend::get_device_manager
|
|
-- This function is used to return the ClutterDeviceManager instance
|
|
that is going to be returned by clutter_device_manager_get_default()
|
|
and that should be used internally by input event translation.
|
|
|
|
Implementing the stage
|
|
-------------------------------------------------------------------------------
|
|
|
|
ClutterStage acts as a wrapper object relaying all the drawing operations
|
|
to the actual implementation. The implementation of the stage can be any
|
|
GObject subclass, as long as it implements the ClutterStageWindow interface.
|
|
|
|
The ClutterStageWindow interface contains a set of virtual functions that
|
|
should be overridden by backends that support a windowing system, like
|
|
::set_title(), ::set_fullscreen(), ::set_cursor_visible(), etc.
|
|
|
|
The stage implementation actor must implement:
|
|
|
|
• ClutterStageWindow::get_wrapper()
|
|
• ClutterStageWindow::realize() and ::unrealize()
|
|
• ClutterStageWindow::show() and ::hide()
|
|
• ClutterStageWindow::resize()
|
|
• ClutterStageWindow::get_geometry()
|
|
• ClutterStageWindow::redraw()
|
|
|
|
The ::get_wrapper() implementation should return the pointer to the
|
|
ClutterStage actor using the ClutterStageWindow implementation.
|
|
|
|
In the ::realize virtual function the stage implementation should:
|
|
|
|
- create a new native window handle
|
|
- ensure that there is a GL (or GLES) context
|
|
- make sure that the native window handle is compatible with
|
|
the GL (or GLES) context
|
|
|
|
The return value should be TRUE if the stage implementation was successfully
|
|
realized, and FALSE otherwise.
|
|
|
|
Inside the ::unrealize function the stage implementation should destroy
|
|
the native window handle created in ::realize().
|
|
|
|
The ::resize() virtual function implementation should cause an update
|
|
of the COGL viewport.
|
|
|
|
The ::redraw() virtual function implementation should contain the platform
|
|
specific drawing logic, and call _clutter_stage_do_paint() on the ClutterStage
|
|
wrapper instance to cause the scene to be painted.
|
|
|
|
The stage implementation actor can optionally implement:
|
|
|
|
• ClutterStageWindow::get_pending_swaps()
|
|
|
|
The get_pending_swaps() implementation should return the number of swap
|
|
buffer requests pending completion. This is only relevent for backends
|
|
that also support CLUTTER_FEATURE_SWAP_EVENTS.
|
|
|
|
If the stage window is supposed to handle events, then it should also implement
|
|
the ClutterEventTranslator interface; this interface has a single virtual
|
|
function:
|
|
|
|
• ClutterEventTranslator::translate_event()
|
|
|
|
which gets passed a pointer to the native event data structure, and a pointer
|
|
to a newly-allocated, empty ClutterEvent. The EventTranslator implementation
|
|
should then decide between three options:
|
|
|
|
- translate the native event and return CLUTTER_TRANSLATE_QUEUE to
|
|
let Clutter queue it up in the events queue;
|
|
- return CLUTTER_TRANSLATE_CONTINUE to let other event translators handle
|
|
the event;
|
|
- return CLUTTER_TRANSLATE_REMOVE to ignore the event.
|
|
|
|
Implementing ClutterDeviceManager
|
|
-------------------------------------------------------------------------------
|
|
|
|
Backends with input devices should provide a ClutterDeviceManager
|
|
implementation to handle addition, removal and input device event translation
|
|
through the ClutterEventTranslator interface.
|
|
|
|
NOTES
|
|
===============================================================================
|
|
|
|
• If the platform is using X11 you should probably subclass ClutterBackendX11
|
|
and ClutterStageX11, which will provide you with a ready to use code
|
|
implementation for event handling and window management.
|