doc/HACKING.backends

   1 IMPLEMENTING BACKENDS
   2 ===============================================================================
   3
   4 Clutter supports multiple backends for handling windowing systems and
   5 GL/GLES API on different platforms.
   6
   7 The GL and GLES API are abstracted by the COGL library. The windowing
   8 system is handled by the ClutterBackend implementations inside Clutter
   9 itself.
  10
  11 Clutter, at the moment, supports only in-tree backends.
  12
  13 In order to write a new backend for a specific platform you should
  14 create a new sub-directory under clutter/clutter containing:
  15
  16   <backend>/clutter-backend-<backend>.h
  17   <backend>/clutter-backend-<backend>.c
  18
  19   -- The subclass of the ClutterBackend abstract class.
  20
  21   <backend>/clutter-stage-<backend>.h
  22   <backend>/clutter-stage-<backend>.c
  23
  24   -- The implementation of the stage window
  25
  26   <backend>/clutter-device-manager-<backend>.h
  27   <backend>/clutter-device-manager-<backend>.c
  28
  29   -- The implementation of the input device manager
  30
  31   <backend>/clutter-event-<backend>.c
  32
  33   -- Event-specific code (optional)
  34
  35   <backend>/clutter-<backend>.h
  36
  37   -- A header for the backend-specific API that should be installed
  38      by Clutter inside the include directory along with the rest of
  39      the public API headers (optional).
  40
  41
  42 Implementing ClutterBackend
  43 -------------------------------------------------------------------------------
  44
  45 Each backend must implement the
  46
  47   GType
  48   _clutter_backend_impl_get_type (void);
  49
  50 function declared inside clutter/clutter-private.h. The implementation
  51 of the function must return the same GType of the backend implementation,
  52 for instance:
  53
  54   GType
  55   _clutter_backend_impl_get_type (void)
  56   {
  57     return CLUTTER_TYPE_BACKEND_GLX;
  58   }
  59
  60 The ClutterBackend implementation is a singleton instance, and the
  61 backend must ensure that every time g_object_new() is called the same
  62 pointer is returned (with its reference count increased). The GObject
  63 API reference describes how to use the ::constructor virtual function
  64 to implement a singleton, so you should refer to that.
  65
  66 The ClutterBackend implementation should hold a single drawing context
  67 for its entire lifetime; stage implementations should be "made current"
  68 when needed.
  69
  70 When implementing the ClutterBackend subclass these virtual functions
  71 can be overridden:
  72
  73   ClutterBackend::add_options
  74   -- Use this function to install new, backend-specific GOptionEntry
  75      definitions to the Clutter GOptionGroup. This function is guaranteed
  76      to be called just once.
  77
  78   ClutterBackend::pre_parse
  79   -- Use this function to check for environment variables or setting
  80      up default values before the command line arguments are parsed.
  81      This function is guaranteed to be called just once.
  82
  83   ClutterBackend::post_parse
  84   -- Use this function to prepare the backend with the values either
  85      set inside the ::pre_parse virtual function or by the command
  86      line options parsing code. This function is guaranteed to be
  87      called just once.
  88
  89   ClutterBackend::init_events
  90   -- Use this function to initialize the event handling. This function
  91      is guaranteed to be called just once.
  92
  93   ClutterBackend::get_features
  94   -- Use this function to retrieve the features detectable at runtime
  95      from the GL or GLES implementation, plus the eventual backend-specific
  96      features.
  97
  98   ClutterBackend::create_context
  99   -- This function is used to create the drawing context to be used
 100      by Clutter. Clutter will call this function during the initialization
 101      phase. A GL (or GLES) context must always be available after the
 102      initialization, so that Cogl and Clutter can query it for capabilities.
 103      This function might be called multiple times so if a context was
 104      successfully created in a previous call, this function should
 105      short-circuit early and return TRUE
 106
 107   ClutterBackend::ensure_context
 108   -- This function is used to ensure that the backend drawing context
 109      is made current for passed ClutterStage, using the backend-specific
 110      API. This function is called each time a new stage is going to
 111      be painted. If the Stage is inside its destruction sequence this
 112      function should either fall back the drawing context to a default
 113      drawing surface or should unset the drawing surface from the
 114      drawing context.
 115
 116   ClutterBackend::create_stage
 117   -- This function is used to create the stage implementation. It will
 118      receive as an argument the ClutterStage instance that is "wrapping"
 119      the actual implementation being created. The backend must create
 120      its stage implementation, initialise it and then return it; in case
 121      of error, the backend must return NULL and set the passed GError.
 122
 123   ClutterBackend::get_device_manager
 124   -- This function is used to return the ClutterDeviceManager instance
 125      that is going to be returned by clutter_device_manager_get_default()
 126      and that should be used internally by input event translation.
 127
 128 Implementing the stage
 129 -------------------------------------------------------------------------------
 130
 131 ClutterStage acts as a wrapper object relaying all the drawing operations
 132 to the actual implementation. The implementation of the stage can be any
 133 GObject subclass, as long as it implements the ClutterStageWindow interface.
 134
 135 The ClutterStageWindow interface contains a set of virtual functions that
 136 should be overridden by backends that support a windowing system, like
 137 ::set_title(), ::set_fullscreen(), ::set_cursor_visible(), etc.
 138
 139 The stage implementation actor must implement:
 140
 141   • ClutterStageWindow::get_wrapper()
 142   • ClutterStageWindow::realize() and ::unrealize()
 143   • ClutterStageWindow::show() and ::hide()
 144   • ClutterStageWindow::resize()
 145   • ClutterStageWindow::get_geometry()
 146   • ClutterStageWindow::redraw()
 147
 148 The ::get_wrapper() implementation should return the pointer to the
 149 ClutterStage actor using the ClutterStageWindow implementation.
 150
 151 In the ::realize virtual function the stage implementation should:
 152
 153   - create a new native window handle
 154   - ensure that there is a GL (or GLES) context
 155   - make sure that the native window handle is compatible with
 156     the GL (or GLES) context
 157
 158 The return value should be TRUE if the stage implementation was successfully
 159 realized, and FALSE otherwise.
 160
 161 Inside the ::unrealize function the stage implementation should destroy
 162 the native window handle created in ::realize().
 163
 164 The ::resize() virtual function implementation should cause an update
 165 of the COGL viewport.
 166
 167 The ::redraw() virtual function implementation should contain the platform
 168 specific drawing logic, and call _clutter_stage_do_paint() on the ClutterStage
 169 wrapper instance to cause the scene to be painted.
 170
 171 The stage implementation actor can optionally implement:
 172
 173   • ClutterStageWindow::get_pending_swaps()
 174
 175 The get_pending_swaps() implementation should return the number of swap
 176 buffer requests pending completion. This is only relevent for backends
 177 that also support CLUTTER_FEATURE_SWAP_EVENTS.
 178
 179 If the stage window is supposed to handle events, then it should also implement
 180 the ClutterEventTranslator interface; this interface has a single virtual
 181 function:
 182
 183   • ClutterEventTranslator::translate_event()
 184
 185 which gets passed a pointer to the native event data structure, and a pointer
 186 to a newly-allocated, empty ClutterEvent. The EventTranslator implementation
 187 should then decide between three options:
 188
 189   - translate the native event and return CLUTTER_TRANSLATE_QUEUE to
 190     let Clutter queue it up in the events queue;
 191   - return CLUTTER_TRANSLATE_CONTINUE to let other event translators handle
 192     the event;
 193   - return CLUTTER_TRANSLATE_REMOVE to ignore the event.
 194
 195 Implementing ClutterDeviceManager
 196 -------------------------------------------------------------------------------
 197
 198 Backends with input devices should provide a ClutterDeviceManager
 199 implementation to handle addition, removal and input device event translation
 200 through the ClutterEventTranslator interface.
 201
 202 NOTES
 203 ===============================================================================
 204
 205 • If the platform is using X11 you should probably subclass ClutterBackendX11
 206   and ClutterStageX11, which will provide you with a ready to use code
 207   implementation for event handling and window management.