General

General — Various 'global' clutter functions.

Synopsis




enum                ClutterInitError;
ClutterInitError    clutter_init                        (int *argc,
                                                         char ***argv);
ClutterInitError    clutter_init_with_args              (int *argc,
                                                         char ***argv,
                                                         char *parameter_string,
                                                         GOptionEntry *entries,
                                                         char *translation_domain,
                                                         GError **error);
GOptionGroup*       clutter_get_option_group            (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);

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


Description

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

Details

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,
                                                         char *parameter_string,
                                                         GOptionEntry *entries,
                                                         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 comman 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.

Returns : a GOptionGroup for the commandline arguments recognized by Clutter

Since 0.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_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()

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 variant of g_idle_add_full() calls function with the Clutter lock held. It can be thought of a MT-safe version for Clutter actors for the following use case, where you have to worry about idle_callback() running in thread A and accessing self after it has been finalized in thread B:

static gboolean
idle_callback (gpointer data)
{
   // clutter_threads_enter(); would be needed for g_idle_add()

   SomeActor *self = data;
   /* do stuff with self */

   self->idle_id = 0;

   // clutter_threads_leave(); would be needed for g_idle_add()
   return FALSE;
}
static void
some_actor_do_stuff_later (SomeActor *self)
{
   self->idle_id = clutter_threads_add_idle (idle_callback, self)
   // using g_idle_add() here would require thread protection in the callback
}

static void
some_actor_finalize (GObject *object)
{
   SomeActor *self = SOME_ACTOR (object);
   if (self->idle_id)
     g_source_remove (self->idle_id);
   G_OBJECT_CLASS (parent_class)->finalize (object);
}

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 lock, with the given priority. The function is called repeatedly until it returns FALSE, at which point the timeout is automatically destroyed and the function will not be called again. The notify function is called when the timeout is destroyed. The first call to the function will be at the end of the first interval.

Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to 'catch up' time lost in delays).

This variant of g_timeout_add_full() can be thought of a MT-safe version for Clutter actors. 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