clutter-main

clutter-main — Various 'global' Clutter functions.

Functions

Description

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

The Clutter 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(), and entered when calling user-related code during event handling and actor drawing.

The only safe and portable way to use the Clutter API in a multi-threaded environment is to only access the Clutter API from a thread that did called 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 finishes, and update the UI from those callbacks.

For a working example of how to use a worker thread to update the UI, see threads.c

Functions

clutter_threads_init ()

void
clutter_threads_init (void);

clutter_threads_init has been deprecated since version 1.10 and should not be used in newly-written code.

This function does not do anything. Threading support is initialized when Clutter is initialized.

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

clutter_threads_enter has been deprecated since version 1.12 and should not be used in newly-written code.

This function should not be used by application code; marking critical sections is not portable on various platforms. Instead of acquiring the Clutter lock, schedule UI updates from the main loop using clutter_threads_add_idle() or clutter_threads_add_timeout().

Locks the Clutter thread lock.

Since: 0.4


clutter_threads_leave ()

void
clutter_threads_leave (void);

clutter_threads_leave has been deprecated since version 1.12 and should not be used in newly-written code.

This function should not be used by application code; marking critical sections is not portable on various platforms. Instead of acquiring the Clutter lock, schedule UI updates from the main loop using clutter_threads_add_idle() or clutter_threads_add_timeout().

Unlocks the Clutter thread lock.

Since: 0.4


clutter_threads_add_frame_source ()

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

clutter_threads_add_frame_source has been deprecated since version 1.6 and should not be used in newly-written code.

There is no direct replacement for this API

Simple wrapper around clutter_threads_add_frame_source_full().

[skip]

Parameters

fps

the number of times per second to call the function

 

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 fps,
                                       GSourceFunc func,
                                       gpointer data,
                                       GDestroyNotify notify);

clutter_threads_add_frame_source_full has been deprecated since version 1.6 and should not be used in newly-written code.

There is no direct replacement for this API

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]

Parameters

priority

the priority of the frame source. Typically this will be in the range between G_PRIORITY_DEFAULT and G_PRIORITY_HIGH.

 

fps

the number of times per second to call the function

 

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_set_motion_events_enabled ()

void
clutter_set_motion_events_enabled (gboolean enable);

clutter_set_motion_events_enabled has been deprecated since version 1.8 and should not be used in newly-written code.

Use clutter_stage_set_motion_events_enabled() instead.

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:

  • ClutterActor::motion-event, except on the ClutterStage

  • ClutterActor::enter-event

  • ClutterActor::leave-event

Parameters

enable

TRUE to enable per-actor motion events

 

Since: 0.6


clutter_get_motion_events_enabled ()

gboolean
clutter_get_motion_events_enabled (void);

clutter_get_motion_events_enabled has been deprecated since version 1.8 and should not be used in newly-written code.

Use clutter_stage_get_motion_events_enabled() instead.

Gets whether the per-actor motion events are enabled.

Returns

TRUE if the motion events are enabled

Since: 0.6


clutter_redraw ()

void
clutter_redraw (ClutterStage *stage);

clutter_redraw has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_stage_ensure_redraw() instead.

Forces a redraw of the entire stage. Applications should never use this function, but queue a redraw using clutter_actor_queue_redraw().

This function should only be used by libraries integrating Clutter from within another toolkit.


clutter_clear_glyph_cache ()

void
clutter_clear_glyph_cache (void);

clutter_clear_glyph_cache has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_get_font_map() and cogl_pango_font_map_clear_glyph_cache() instead.

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_font_flags ()

void
clutter_set_font_flags (ClutterFontFlags flags);

clutter_set_font_flags has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_backend_set_font_options() and the cairo_font_option_t API.

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.

Parameters

flags

The new flags

 

Since: 1.0


clutter_get_font_flags ()

ClutterFontFlags
clutter_get_font_flags (void);

clutter_get_font_flags has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_backend_get_font_options() and the cairo_font_options_t API.

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

Returns

The font flags

Since: 1.0


clutter_get_input_device_for_id ()

ClutterInputDevice *
clutter_get_input_device_for_id (gint id_);

clutter_get_input_device_for_id has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_device_manager_get_device() instead.

Retrieves the ClutterInputDevice from its id_ . This is a convenience wrapper for clutter_device_manager_get_device() and it is functionally equivalent to:

1
2
3
4
5
ClutterDeviceManager *manager;
ClutterInputDevice *device;

manager = clutter_device_manager_get_default ();
device = clutter_device_manager_get_device (manager, id);

Parameters

id_

the unique id for a device

 

Returns

a ClutterInputDevice, or NULL.

[transfer none]

Since: 0.8


clutter_grab_pointer_for_device ()

void
clutter_grab_pointer_for_device (ClutterActor *actor,
                                 gint id_);

clutter_grab_pointer_for_device has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_input_device_grab() instead.

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

Parameters

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

clutter_ungrab_pointer_for_device has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_input_device_ungrab() instead.

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

Parameters

id_

a device id

 

Since: 0.8


clutter_set_default_frame_rate ()

void
clutter_set_default_frame_rate (guint frames_per_sec);

clutter_set_default_frame_rate has been deprecated since version 1.10 and should not be used in newly-written code.

This function does not do anything any more.

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.

Parameters

frames_per_sec

the new default frame rate

 

Since: 0.6


clutter_get_timestamp ()

gulong
clutter_get_timestamp (void);

clutter_get_timestamp has been deprecated since version 1.10 and should not be used in newly-written code.

Use GTimer or g_get_monotonic_time() for a proper timing source

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.

Returns

Number of microseconds since clutter_init() was called, or zero if Clutter was not configured with debugging code paths.


clutter_get_debug_enabled ()

gboolean
clutter_get_debug_enabled (void);

clutter_get_debug_enabled has been deprecated since version 1.10 and should not be used in newly-written code.

This function does not do anything.

Check if Clutter has debugging enabled.

Returns

FALSE


clutter_get_show_fps ()

gboolean
clutter_get_show_fps (void);

clutter_get_show_fps has been deprecated since version 1.10 and should not be used in newly-written code.

This function does not do anything. Use the environment variable or the configuration file to determine whether Clutter should print out the FPS counter on the console.

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