Threading Model

Clutter is thread-aware: all operations performed by Clutter are assumed to be under the big Clutter lock, which is created when the threading is initialized through clutter_init().

int
main (int argc, char *argv[])
{
  /* initialize Clutter */
  clutter_init (&argc, &argv);

  /* program code */

  /* acquire the main lock */
  clutter_threads_enter ();

  /* start the main loop */
  clutter_main ();

  /* release the main lock */
  clutter_threads_leave ();

  /* clean up */
  return 0;
}
    

This threading model has the caveat that it is only safe to call Clutter's API when the lock has been acquired — which happens between pairs of clutter_threads_enter() and clutter_threads_leave() calls.

The only safe and portable way to use the Clutter API in a multi-threaded environment is to never access the API from a thread that did not call clutter_init() and clutter_main().

The common pattern for using threads with Clutter is to use worker threads to perform blocking operations and then install idle or timeout sources with the result when the thread finished.

Clutter provides thread-aware variants of g_idle_add() and g_timeout_add() that acquire the Clutter lock before invoking the provided callback: clutter_threads_add_idle() and clutter_threads_add_timeout().

The example below shows how to use a worker thread to perform a blocking operation, and perform UI updates using the main loop.

1

FIXME: MISSING XINCLUDE CONTENT

CLUTTER_PRIORITY_REDRAW

#define CLUTTER_PRIORITY_REDRAW         (G_PRIORITY_HIGH_IDLE + 50)

Priority of the redraws. This is chosen to be lower than the GTK+ redraw and resize priorities, because in application with both GTK+ and Clutter it's more likely that the Clutter part will be continually animating (and thus able to starve GTK+) than vice-versa.

Since 0.8

enum ClutterInitError

typedef enum {
  CLUTTER_INIT_SUCCESS        =  1,
  CLUTTER_INIT_ERROR_UNKNOWN  =  0,
  CLUTTER_INIT_ERROR_THREADS  = -1,
  CLUTTER_INIT_ERROR_BACKEND  = -2,
  CLUTTER_INIT_ERROR_INTERNAL = -3
} ClutterInitError;

Error conditions returned by clutter_init() and clutter_init_with_args().

Since 0.2

clutter_init ()

ClutterInitError    clutter_init                        (int *argc,
                                                         char ***argv);

Initialises everything needed to operate with Clutter and parses some standard command line options; argc and argv are adjusted accordingly so your own code will never see those standard arguments.

It is safe to call this function multiple times.

If this function fails, and returns an error code, any subsequent Clutter API will have undefined behaviour - including segmentation faults and assertion failures. Make sure to handle the returned ClutterInitError enumeration value.

clutter_init_with_args ()

ClutterInitError    clutter_init_with_args              (int *argc,
                                                         char ***argv,
                                                         const char *parameter_string,
                                                         GOptionEntry *entries,
                                                         const char *translation_domain,
                                                         GError **error);

This function does the same work as clutter_init(). Additionally, it allows you to add your own command line options, and it automatically generates nicely formatted --help output. Note that your program will be terminated after writing out the help output. Also note that, in case of error, the error message will be placed inside error instead of being printed on the display.

Just like clutter_init(), if this function returns an error code then any subsequent call to any other Clutter API will result in undefined behaviour - including segmentation faults.

Since 0.2

clutter_get_option_group ()

GOptionGroup *      clutter_get_option_group            (void);

Returns a GOptionGroup for the command line arguments recognized by Clutter. You should add this group to your GOptionContext with g_option_context_add_group(), if you are using g_option_context_parse() to parse your commandline arguments.

Calling g_option_context_parse() with Clutter's GOptionGroup will result in Clutter's initialization. That is, the following code:

1
2

g_option_context_set_main_group (context, clutter_get_option_group ());
res = g_option_context_parse (context, &argc, &argc, NULL);

is functionally equivalent to:

1

clutter_init (&argc, &argv);

After g_option_context_parse() on a GOptionContext containing the Clutter GOptionGroup has returned TRUE, Clutter is guaranteed to be initialized.

Since 0.2

clutter_get_option_group_without_init ()

GOptionGroup *      clutter_get_option_group_without_init
                                                        (void);

Returns a GOptionGroup for the command line arguments recognized by Clutter. You should add this group to your GOptionContext with g_option_context_add_group(), if you are using g_option_context_parse() to parse your commandline arguments.

Unlike clutter_get_option_group(), calling g_option_context_parse() with the GOptionGroup returned by this function requires a subsequent explicit call to clutter_init(); use this function when needing to set foreign display connection with clutter_x11_set_display(), or with gtk_clutter_init().

Since 0.8.2

clutter_main ()

void                clutter_main                        (void);

Starts the Clutter mainloop.

clutter_main_quit ()

void                clutter_main_quit                   (void);

Terminates the Clutter mainloop.

clutter_main_level ()

gint                clutter_main_level                  (void);

Retrieves the depth of the Clutter mainloop.

clutter_get_debug_enabled ()

gboolean            clutter_get_debug_enabled           (void);

Check if Clutter has debugging enabled.

clutter_get_show_fps ()

gboolean            clutter_get_show_fps                (void);

Returns whether Clutter should print out the frames per second on the console. You can enable this setting either using the CLUTTER_SHOW_FPS environment variable or passing the --clutter-show-fps command line argument. *

Since 0.4

clutter_get_timestamp ()

gulong              clutter_get_timestamp               (void);

Returns the approximate number of microseconds passed since Clutter was intialised.

This function shdould not be used by application code.

The output of this function depends on whether Clutter was configured to enable its debugging code paths, so it's less useful than intended.

Since Clutter 1.10, this function is an alias to g_get_monotonic_time() if Clutter was configured to enable the debugging code paths.

clutter_get_actor_by_gid ()

ClutterActor *      clutter_get_actor_by_gid            (guint32 id_);

Retrieves the ClutterActor with id_.

Since 0.6

clutter_set_default_frame_rate ()

void                clutter_set_default_frame_rate      (guint frames_per_sec);

Sets the default frame rate. This frame rate will be used to limit the number of frames drawn if Clutter is not able to synchronize with the vertical refresh rate of the display. When synchronization is possible, this value is ignored.

Since 0.6

clutter_get_default_frame_rate ()

guint               clutter_get_default_frame_rate      (void);

Retrieves the default frame rate. See clutter_set_default_frame_rate().

Since 0.6

clutter_set_motion_events_enabled ()

void                clutter_set_motion_events_enabled   (gboolean enable);

Sets whether per-actor motion events should be enabled or not on all ClutterStages managed by Clutter.

If enable is FALSE the following events will not work:

Since 0.6

clutter_get_motion_events_enabled ()

gboolean            clutter_get_motion_events_enabled   (void);

Gets whether the per-actor motion events are enabled.

Since 0.6

clutter_clear_glyph_cache ()

void                clutter_clear_glyph_cache           (void);

Clears the internal cache of glyphs used by the Pango renderer. This will free up some memory and GL texture resources. The cache will be automatically refilled as more text is drawn.

Since 0.8

enum ClutterFontFlags

typedef enum {
 /*< prefix=CLUTTER_FONT >*/
  CLUTTER_FONT_MIPMAPPING = (1 << 0),
  CLUTTER_FONT_HINTING    = (1 << 1)
} ClutterFontFlags;

Runtime flags to change the font quality. To be used with clutter_set_font_flags().

Since 1.0

clutter_set_font_flags ()

void                clutter_set_font_flags              (ClutterFontFlags flags);

Sets the font quality options for subsequent text rendering operations.

Using mipmapped textures will improve the quality for scaled down text but will use more texture memory.

Enabling hinting improves text quality for static text but may introduce some artifacts if the text is animated.

Since 1.0

clutter_get_font_flags ()

ClutterFontFlags    clutter_get_font_flags              (void);

Gets the current font flags for rendering text. See clutter_set_font_flags().

Since 1.0

clutter_get_font_map ()

PangoFontMap *      clutter_get_font_map                (void);

Retrieves the PangoFontMap instance used by Clutter. You can use the global font map object with the COGL Pango API.

Since 1.0

enum ClutterTextDirection

typedef enum {
  CLUTTER_TEXT_DIRECTION_DEFAULT,
  CLUTTER_TEXT_DIRECTION_LTR,
  CLUTTER_TEXT_DIRECTION_RTL
} ClutterTextDirection;

The text direction to be used by ClutterActors

Since 1.2

clutter_get_default_text_direction ()

ClutterTextDirection clutter_get_default_text_direction (void);

Retrieves the default direction for the text. The text direction is determined by the locale and/or by the CLUTTER_TEXT_DIRECTION environment variable.

The default text direction can be overridden on a per-actor basis by using clutter_actor_set_text_direction().

Since 1.2

clutter_get_accessibility_enabled ()

gboolean            clutter_get_accessibility_enabled   (void);

Returns whether Clutter has accessibility support enabled. As least, a value of TRUE means that there are a proper AtkUtil implementation available

Since 1.4

clutter_threads_set_lock_functions ()

void                clutter_threads_set_lock_functions  (GCallback enter_fn,
                                                         GCallback leave_fn);

Allows the application to replace the standard method that Clutter uses to protect its data structures. Normally, Clutter creates a single GMutex that is locked by clutter_threads_enter(), and released by clutter_threads_leave(); using this function an application provides, instead, a function enter_fn that is called by clutter_threads_enter() and a function leave_fn that is called by clutter_threads_leave().

The functions must provide at least same locking functionality as the default implementation, but can also do extra application specific processing.

As an example, consider an application that has its own recursive lock that when held, holds the Clutter lock as well. When Clutter unlocks the Clutter lock when entering a recursive main loop, the application must temporarily release its lock as well.

Most threaded Clutter apps won't need to use this method.

This method must be called before clutter_init(), and cannot be called multiple times.

Since 0.4

clutter_threads_init ()

void                clutter_threads_init                (void);

Initialises the Clutter threading mechanism, so that Clutter API can be called by multiple threads, using clutter_threads_enter() and clutter_threads_leave() to mark the critical sections.

You must call g_thread_init() before this function.

This function must be called before clutter_init().

It is safe to call this function multiple times.

Since 0.4

clutter_threads_enter ()

void                clutter_threads_enter               (void);

Locks the Clutter thread lock.

Since 0.4

clutter_threads_leave ()

void                clutter_threads_leave               (void);

Unlocks the Clutter thread lock.

Since 0.4

clutter_threads_add_idle ()

guint               clutter_threads_add_idle            (GSourceFunc func,
                                                         gpointer data);

Simple wrapper around clutter_threads_add_idle_full() using the default priority.

Since 0.4

clutter_threads_add_idle_full ()

guint               clutter_threads_add_idle_full       (gint priority,
                                                         GSourceFunc func,
                                                         gpointer data,
                                                         GDestroyNotify notify);

Adds a function to be called whenever there are no higher priority events pending. If the function returns FALSE it is automatically removed from the list of event sources and will not be called again.

This function can be considered a thread-safe variant of g_idle_add_full(): it will call function while holding the Clutter lock. It is logically equivalent to the following implementation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

static gboolean
idle_safe_callback (gpointer data)
{
   SafeClosure *closure = data;
   gboolean res = FALSE;

   /* mark the critical section */

   clutter_threads_enter();

   /* the callback does not need to acquire the Clutter
    * lock itself, as it is held by the this proxy handler
    */
   res = closure->callback (closure->data);

   clutter_threads_leave();

   return res;
}
static gulong
add_safe_idle (GSourceFunc callback,
               gpointer    data)
{
  SafeClosure *closure = g_new0 (SafeClosure, 1);

  closure->callback = callback;
  closure->data = data;

  return g_idle_add_full (G_PRIORITY_DEFAULT_IDLE,
                          idle_safe_callback,
                          closure,
                          g_free)
}

This function should be used by threaded applications to make sure that func is emitted under the Clutter threads lock and invoked from the same thread that started the Clutter main loop. For instance, it can be used to update the UI using the results from a worker thread:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

static gboolean
update_ui (gpointer data)
{
  SomeClosure *closure = data;

  /* it is safe to call Clutter API from this function because
   * it is invoked from the same thread that started the main
   * loop and under the Clutter thread lock
   */
  clutter_label_set_text (CLUTTER_LABEL (closure->label),
                          closure->text);

  g_object_unref (closure->label);
  g_free (closure);

  return FALSE;
}

  /* within another thread */
  closure = g_new0 (SomeClosure, 1);
  /* always take a reference on GObject instances */
  closure->label = g_object_ref (my_application->label);
  closure->text = g_strdup (processed_text_to_update_the_label);

  clutter_threads_add_idle_full (G_PRIORITY_HIGH_IDLE,
                                 update_ui,
                                 closure,
                                 NULL);

Rename to: clutter_threads_add_idle

Since 0.4

clutter_threads_add_timeout ()

guint               clutter_threads_add_timeout         (guint interval,
                                                         GSourceFunc func,
                                                         gpointer data);

Simple wrapper around clutter_threads_add_timeout_full().

Since 0.4

clutter_threads_add_timeout_full ()

guint               clutter_threads_add_timeout_full    (gint priority,
                                                         guint interval,
                                                         GSourceFunc func,
                                                         gpointer data,
                                                         GDestroyNotify notify);

Sets a function to be called at regular intervals holding the Clutter threads lock, with the given priority. The function is called repeatedly until it returns FALSE, at which point the timeout is automatically removed and the function will not be called again. The notify function is called when the timeout is removed.

The first call to the function will be at the end of the first interval.

It is important to note that, due to how the Clutter main loop is implemented, the timing will not be accurate and it will not try to "keep up" with the interval.

See also clutter_threads_add_idle_full().

Rename to: clutter_threads_add_timeout

Since 0.4

clutter_threads_add_frame_source ()

guint               clutter_threads_add_frame_source    (guint fps,
                                                         GSourceFunc func,
                                                         gpointer data);

Simple wrapper around clutter_threads_add_frame_source_full().

Since 0.8

clutter_threads_add_frame_source_full ()

guint               clutter_threads_add_frame_source_full
                                                        (gint priority,
                                                         guint fps,
                                                         GSourceFunc func,
                                                         gpointer data,
                                                         GDestroyNotify notify);

Sets a function to be called at regular intervals holding the Clutter threads lock, with the given priority. The function is called repeatedly until it returns FALSE, at which point the timeout is automatically removed and the function will not be called again. The notify function is called when the timeout is removed.

This function is similar to clutter_threads_add_timeout_full() except that it will try to compensate for delays. For example, if func takes half the interval time to execute then the function will be called again half the interval time after it finished. In contrast clutter_threads_add_timeout_full() would not fire until a full interval after the function completes so the delay between calls would be interval * 1.5. This function does not however try to invoke the function multiple times to catch up missing frames if func takes more than interval ms to execute.

See also clutter_threads_add_idle_full().

Rename to: clutter_threads_add_frame_source

Since 0.8

clutter_threads_add_repaint_func ()

guint               clutter_threads_add_repaint_func    (GSourceFunc func,
                                                         gpointer data,
                                                         GDestroyNotify notify);

Adds a function to be called whenever Clutter is processing a new frame.

If the function returns FALSE it is automatically removed from the list of repaint functions and will not be called again.

This function is guaranteed to be called from within the same thread that called clutter_main(), and while the Clutter lock is being held; the function will be called within the main loop, so it is imperative that it does not block, otherwise the frame time budget may be lost.

A repaint function is useful to ensure that an update of the scenegraph is performed before the scenegraph is repainted; for instance, uploading a frame from a video into a ClutterTexture. By default, a repaint function added using this function will be invoked prior to the frame being processed.

Adding a repaint function does not automatically ensure that a new frame will be queued.

When the repaint function is removed (either because it returned FALSE or because clutter_threads_remove_repaint_func() has been called) the notify function will be called, if any is set.

See also: clutter_threads_add_repaint_func_full()

Since 1.0

enum ClutterRepaintFlags

typedef enum {
  CLUTTER_REPAINT_FLAGS_PRE_PAINT = 1 << 0,
  CLUTTER_REPAINT_FLAGS_POST_PAINT = 1 << 1,
  CLUTTER_REPAINT_FLAGS_QUEUE_REDRAW_ON_ADD = 1 << 2
} ClutterRepaintFlags;

Flags to pass to clutter_threads_add_repaint_func_full().

Since 1.10

clutter_threads_add_repaint_func_full ()

guint               clutter_threads_add_repaint_func_full
                                                        (ClutterRepaintFlags flags,
                                                         GSourceFunc func,
                                                         gpointer data,
                                                         GDestroyNotify notify);

Adds a function to be called whenever Clutter is processing a new frame.

If the function returns FALSE it is automatically removed from the list of repaint functions and will not be called again.

This function is guaranteed to be called from within the same thread that called clutter_main(), and while the Clutter lock is being held; the function will be called within the main loop, so it is imperative that it does not block, otherwise the frame time budget may be lost.

A repaint function is useful to ensure that an update of the scenegraph is performed before the scenegraph is repainted; for instance, uploading a frame from a video into a ClutterTexture. The flags passed to this function will determine the section of the frame processing that will result in func being called.

Adding a repaint function does not automatically ensure that a new frame will be queued.

When the repaint function is removed (either because it returned FALSE or because clutter_threads_remove_repaint_func() has been called) the notify function will be called, if any is set.

Since 1.10

clutter_threads_remove_repaint_func ()

void                clutter_threads_remove_repaint_func (guint handle_id);

Removes the repaint function with handle_id as its id

Since 1.0

clutter_get_keyboard_grab ()

ClutterActor *      clutter_get_keyboard_grab           (void);

Queries the current keyboard grab of clutter.

Since 0.6

clutter_get_pointer_grab ()

ClutterActor *      clutter_get_pointer_grab            (void);

Queries the current pointer grab of clutter.

Since 0.6

clutter_grab_keyboard ()

void                clutter_grab_keyboard               (ClutterActor *actor);

Grabs keyboard events, after the grab is done keyboard events ("key-press-event" and "key-release-event") are delivered to this actor directly. The source set in the event will be the actor that would have received the event if the keyboard grab was not in effect.

Like pointer grabs, keyboard grabs should only be used as a last resource.

See also clutter_stage_set_key_focus() and clutter_actor_grab_key_focus() to perform a "soft" key grab and assign key focus to a specific actor.

Since 0.6

clutter_grab_pointer ()

void                clutter_grab_pointer                (ClutterActor *actor);

Grabs pointer events, after the grab is done all pointer related events (press, motion, release, enter, leave and scroll) are delivered to this actor directly without passing through both capture and bubble phases of the event delivery chain. The source set in the event will be the actor that would have received the event if the pointer grab was not in effect.

This function should rarely be used.

If a grab is required, you are strongly encouraged to use a specific input device by calling clutter_input_device_grab().

Since 0.6

clutter_ungrab_keyboard ()

void                clutter_ungrab_keyboard             (void);

Removes an existing grab of the keyboard.

Since 0.6

clutter_ungrab_pointer ()

void                clutter_ungrab_pointer              (void);

Removes an existing grab of the pointer.

Since 0.6

clutter_grab_pointer_for_device ()

void                clutter_grab_pointer_for_device     (ClutterActor *actor,
                                                         gint id_);

Grabs all the pointer events coming from the device id for actor.

If id is -1 then this function is equivalent to clutter_grab_pointer().

Since 0.8

clutter_ungrab_pointer_for_device ()

void                clutter_ungrab_pointer_for_device   (gint id_);

Removes an existing grab of the pointer events for device id_.

Since 0.8

clutter_do_event ()

void                clutter_do_event                    (ClutterEvent *event);

Processes an event.

The event must be a valid ClutterEvent and have a ClutterStage associated to it.

This function is only useful when embedding Clutter inside another toolkit, and it should never be called by applications.

Since 0.4