## General

General — Various 'global' clutter functions.

## Synopsis

    #define             CLUTTER_PRIORITY_REDRAW
    #define             CLUTTER_PRIORITY_TIMELINE

    enum                ClutterInitError;
    ClutterInitError    clutter_init                        (int *argc,
                                                             char ***argv);
    ClutterInitError    clutter_init_with_args              (int *argc,
                                                             char ***argv,
                                                             const char *parameter_string,
                                                             GOptionEntry *entries,
                                                             const char *translation_domain,
                                                             GError **error);
    GOptionGroup *      clutter_get_option_group            (void);
    GOptionGroup *      clutter_get_option_group_without_init
                                                            (void);

    void                clutter_main                        (void);
    void                clutter_main_quit                   (void);
    gint                clutter_main_level                  (void);

    gboolean            clutter_get_debug_enabled           (void);
    gboolean            clutter_get_show_fps                (void);
    gulong              clutter_get_timestamp               (void);
    ClutterActor *      clutter_get_actor_by_gid            (guint32 id);
    void                clutter_set_default_frame_rate      (guint frames_per_sec);
    guint               clutter_get_default_frame_rate      (void);
    void                clutter_set_motion_events_enabled   (gboolean enable);
    gboolean            clutter_get_motion_events_enabled   (void);
    void                clutter_set_motion_events_frequency (guint frequency);
    guint               clutter_get_motion_events_frequency (void);
    void                clutter_clear_glyph_cache           (void);
    void                clutter_set_use_mipmapped_text      (gboolean value);
    gboolean            clutter_get_use_mipmapped_text      (void);

    void                clutter_threads_set_lock_functions  (GCallback enter_fn,
                                                             GCallback leave_fn);
    void                clutter_threads_init                (void);
    void                clutter_threads_enter               (void);
    void                clutter_threads_leave               (void);
    guint               clutter_threads_add_idle            (GSourceFunc func,
                                                             gpointer data);
    guint               clutter_threads_add_idle_full       (gint priority,
                                                             GSourceFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    guint               clutter_threads_add_timeout         (guint interval,
                                                             GSourceFunc func,
                                                             gpointer data);
    guint               clutter_threads_add_timeout_full    (gint priority,
                                                             guint interval,
                                                             GSourceFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    guint               clutter_threads_add_frame_source    (guint interval,
                                                             GSourceFunc func,
                                                             gpointer data);
    guint               clutter_threads_add_frame_source_full
                                                            (gint priority,
                                                             guint interval,
                                                             GSourceFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);

    ClutterActor *      clutter_get_keyboard_grab           (void);
    ClutterActor *      clutter_get_pointer_grab            (void);
    void                clutter_grab_keyboard               (ClutterActor *actor);
    void                clutter_grab_pointer                (ClutterActor *actor);
    void                clutter_ungrab_keyboard             (void);
    void                clutter_ungrab_pointer              (void);
    void                clutter_grab_pointer_for_device     (ClutterActor *actor,
                                                             gint id);
    void                clutter_ungrab_pointer_for_device   (gint id);

    void                clutter_do_event                    (ClutterEvent *event);

## Description

Functions to retrieve various global Clutter resources and other utility functions for mainloops, events and threads

## Details

### CLUTTER_PRIORITY_REDRAW

    #define CLUTTER_PRIORITY_REDRAW         (G_PRIORITY_DEFAULT + 10)

Priority of the redraws.

Since 0.8

### CLUTTER_PRIORITY_TIMELINE

    #define CLUTTER_PRIORITY_TIMELINE       (G_PRIORITY_DEFAULT + 30)

Priority of the timelines.

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()`.

`CLUTTER_INIT_SUCCESS` | Initialisation successful
`CLUTTER_INIT_ERROR_UNKNOWN` | Unknown error
`CLUTTER_INIT_ERROR_THREADS` | Thread initialisation failed
`CLUTTER_INIT_ERROR_BACKEND` | Backend initialisation failed
`CLUTTER_INIT_ERROR_INTERNAL` | Internal error

Since 0.2

### clutter_init ()

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

It will initialise 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.

`argc` : | The number of arguments in `argv`
`argv` : | A pointer to an array of arguments.
Returns : | 1 on success, < 0 on failure.

### 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.

`argc` : | a pointer to the number of command line arguments
`argv` : | a pointer to the array of command line arguments
`parameter_string` : | a string which is displayed in the first line of `--help` output, after ``programname` [OPTION...]`
`entries` : | a `NULL` terminated array of GOptionEntrys describing the options of your program
`translation_domain` : | a translation domain to use for translating the `--help` output for the options in `entries` with `gettext()`, or `NULL`
`error` : | a return location for a GError
Returns : | `CLUTTER_INIT_SUCCESS` if Clutter has been successfully initialised, or other values or ClutterInitError in case of error.

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:

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

is functionally equivalent to:

      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.

Returns : | a GOptionGroup for the commandline arguments recognized by Clutter

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()`.

Returns : | a GOptionGroup for the commandline arguments recognized by Clutter

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.

Returns : | The level of the mainloop.

### clutter_get_debug_enabled ()

    gboolean            clutter_get_debug_enabled           (void);

Check if clutter has debugging turned on.

Returns : | TRUE if debugging is turned on, FALSE otherwise.

### 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. *

Returns : | `TRUE` if Clutter should show the FPS.

Since 0.4

### clutter_get_timestamp ()

    gulong              clutter_get_timestamp               (void);

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

Returns : | Number of microseconds since `clutter_init()` was called.

### clutter_get_actor_by_gid ()

    ClutterActor *      clutter_get_actor_by_gid            (guint32 id);

Retrieves the ClutterActor with `id`.

`id` : | a ClutterActor ID.
Returns : | the actor with the passed id or `NULL`. The returned actor does not have its reference count increased.

Since 0.6

### clutter_set_default_frame_rate ()

    void                clutter_set_default_frame_rate      (guint frames_per_sec);

Sets the default frame rate to be used when creating ClutterTimelines

`frames_per_sec` : | the new default frame rate

Since 0.6

### clutter_get_default_frame_rate ()

    guint               clutter_get_default_frame_rate      (void);

Retrieves the default frame rate used when creating ClutterTimelines.

This value is also used to compute the default frequency of motion events.

Returns : | the 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 (the default is to enable them).

If `enable` is `FALSE` the following events will not work:

- ClutterActor::motion-event, unless on the ClutterStage

- ClutterActor::enter-event

- ClutterActor::leave-event

`enable` : | `TRUE` to enable per-actor motion events

Since 0.6

### clutter_get_motion_events_enabled ()

    gboolean            clutter_get_motion_events_enabled   (void);

Gets whether the per-actor motion events are enabled.

Returns : | `TRUE` if the motion events are enabled

Since 0.6

### clutter_set_motion_events_frequency ()

    void                clutter_set_motion_events_frequency (guint frequency);

Sets the motion events frequency. Setting this to a non-zero value will override the default setting, so it should be rarely used.

Motion events are delivered from the default backend to the stage and are used to generate the enter/leave events pair. This might lead to a performance penalty due to the way the actors are identified. Using this function is possible to reduce the frequency of the motion events delivery to the stage.

`frequency` : | the number of motion events per second, or 0 for the default value

Since 0.6

### clutter_get_motion_events_frequency ()

    guint               clutter_get_motion_events_frequency (void);

Retrieves the number of motion events per second that are delivered to the stage.

See `clutter_set_motion_events_frequency()`.

Returns : | the number of motion events per second

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

### clutter_set_use_mipmapped_text ()

    void                clutter_set_use_mipmapped_text      (gboolean value);

Sets whether subsequent text rendering operations will use mipmapped textures or not. Using mipmapped textures will improve the quality for scaled down text but will use more texture memory.

`value` : | `TRUE` to enable mipmapping or `FALSE` to disable.

Since 0.8

### clutter_get_use_mipmapped_text ()

    gboolean            clutter_get_use_mipmapped_text      (void);

Gets whether mipmapped textures are used in text operations. See `clutter_set_use_mipmapped_text()`.

Returns : | `TRUE` if text operations should use mipmapped textures

Since 0.8

### 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_threads_init()`, and cannot be called multiple times.

`enter_fn` : | function called when aquiring the Clutter main lock
`leave_fn` : | function called when releasing the Clutter main lock

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()`.

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.

`func` : | function to call
`data` : | data to pass to the function
Returns : | the ID (greater than 0) of the event source.

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:

    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_add_idle_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:

    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);

`priority` : | the priority of the timeout source. Typically this will be in the range between G_PRIORITY_DEFAULT_IDLE and G_PRIORITY_HIGH_IDLE
`func` : | function to call
`data` : | data to pass to the function
`notify` : | functio to call when the idle source is removed
Returns : | the ID (greater than 0) of the event source.

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()`.

`interval` : | the time between calls to the function, in milliseconds
`func` : | function to call
`data` : | data to pass to the function
Returns : | the ID (greater than 0) of the event source.

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. A more reliable source is available using `clutter_threads_add_frame_source_full()`, which is also internally used by ClutterTimeline.

See also `clutter_threads_add_idle_full()`.

`priority` : | the priority of the timeout source. Typically this will be in the range between G_PRIORITY_DEFAULT and G_PRIORITY_HIGH.
`interval` : | the time between calls to the function, in milliseconds
`func` : | function to call
`data` : | data to pass to the function
`notify` : | function to call when the timeout source is removed
Returns : | the ID (greater than 0) of the event source.

Since 0.4

### clutter_threads_add_frame_source ()

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

Simple wrapper around `clutter_threads_add_frame_source_full()`.

`interval` : | the time between calls to the function, in milliseconds
`func` : | function to call
`data` : | data to pass to the function
Returns : | the ID (greater than 0) of the event source.

Since 0.8

### clutter_threads_add_frame_source_full ()

    guint               clutter_threads_add_frame_source_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.

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()`.

`priority` : | the priority of the frame source. Typically this will be in the range between G_PRIORITY_DEFAULT and G_PRIORITY_HIGH.
`interval` : | the time between calls to the function, in milliseconds
`func` : | function to call
`data` : | data to pass to the function
`notify` : | function to call when the timeout source is removed
Returns : | the ID (greater than 0) of the event source.

Since 0.8

### clutter_get_keyboard_grab ()

    ClutterActor *      clutter_get_keyboard_grab           (void);

Queries the current keyboard grab of clutter.

Returns : | the actor currently holding the keyboard grab, or NULL if there is no grab.

Since 0.6

### clutter_get_pointer_grab ()

    ClutterActor *      clutter_get_pointer_grab            (void);

Queries the current pointer grab of clutter.

Returns : | the actor currently holding the pointer grab, or NULL if there is no grab.

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.

`actor` : | a ClutterActor

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. The source set in the event will be the actor that would have received the event if the pointer grab was not in effect.

If you wish to grab all the pointer events for a specific input device, you should use `clutter_grab_pointer_for_device()`.

`actor` : | a ClutterActor

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()`.

`actor` : | a ClutterActor
`id` : | a device id, or -1

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`.

`id` : | a device id

Since 0.8

### clutter_do_event ()

    void                clutter_do_event                    (ClutterEvent *event);

Processes an event. This function should never be called by applications.

`event` : | a ClutterEvent.

Since 0.4