Utilities

## Utilities Utilities — Misc utility functions. |

## Synopsis

    int                 clutter_util_next_p2                (int a);

    ClutterTimeoutPool * clutter_timeout_pool_new           (gint priority);
    guint               clutter_timeout_pool_add            (ClutterTimeoutPool *pool,
                                                             guint fps,
                                                             GSourceFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    void                clutter_timeout_pool_remove         (ClutterTimeoutPool *pool,
                                                             guint id);

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

                        ClutterParamSpecFixed;
    GParamSpec *        clutter_param_spec_fixed            (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             CoglFixed minimum,
                                                             CoglFixed maximum,
                                                             CoglFixed default_value,
                                                             GParamFlags flags);
    #define             CLUTTER_VALUE_HOLDS_FIXED           (x)
    void                clutter_value_set_fixed             (GValue *value,
                                                             CoglFixed fixed_);
    CoglFixed           clutter_value_get_fixed             (const GValue *value);

## Description

Various misc utilility functions.

## Details

### clutter_util_next_p2 ()

    int                 clutter_util_next_p2                (int a);

Calculates the nearest power of two, greater than or equal to `a`.

`a` : | Value to get the next power
Returns : | The nearest power of two, greater or equal to `a`.

### clutter_timeout_pool_new ()

    ClutterTimeoutPool * clutter_timeout_pool_new           (gint priority);

Creates a new timeout pool source. A timeout pool should be used when multiple timeout functions, running at the same priority, are needed and the `g_timeout_add()` API might lead to starvation of the time slice of the main loop. A timeout pool allocates a single time slice of the main loop and runs every timeout function inside it. The timeout pool is always sorted, so that the extraction of the next timeout function is a constant time operation.

Inside Clutter, every ClutterTimeline share the same timeout pool, unless the CLUTTER_TIMELINE=no-pool environment variable is set.

ClutterTimeoutPool is part of the ClutterTimeline implementation and should not be used by application developers.

`priority` : | the priority of the timeout pool. Typically this will be G_PRIORITY_DEFAULT
Returns : | the newly created ClutterTimeoutPool. The created pool is owned by the GLib default context and will be automatically destroyed when the context is destroyed. It is possible to force the destruction of the timeout pool using `g_source_destroy()`

Since 0.4

### clutter_timeout_pool_add ()

    guint               clutter_timeout_pool_add            (ClutterTimeoutPool *pool,
                                                             guint fps,
                                                             GSourceFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);

Sets a function to be called at regular intervals, and puts it inside the `pool`. The function is repeatedly called until it returns `FALSE`, at which point the timeout is automatically destroyed and the function won't be called again. If `notify` is not `NULL`, the `notify` function will be called. The first call to `func` will be at the end of `interval`.

Since version 0.8 this 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. Before version 0.8 it 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.

`pool` : | a ClutterTimeoutPool
`fps` : | the time between calls to the function, in frames per second
`func` : | function to call
`data` : | data to pass to the function, or `NULL`
`notify` : | function to call when the timeout is removed, or `NULL`
Returns : | the ID (greater than 0) of the timeout inside the pool. Use `clutter_timeout_pool_remove()` to stop the timeout.

Since 0.4

### clutter_timeout_pool_remove ()

    void                clutter_timeout_pool_remove         (ClutterTimeoutPool *pool,
                                                             guint id);

Removes a timeout function with `id` from the timeout pool. The id is the same returned when adding a function to the timeout pool with `clutter_timeout_pool_add()`.

`pool` : | a ClutterTimeoutPool
`id` : | the id of the timeout to remove

Since 0.4

### clutter_frame_source_add ()

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

Simple wrapper around `clutter_frame_source_add_full()`.

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

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

Sets a function to be called at regular intervals 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`.

This function is similar to `g_timeout_add_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 `g_timeout_add_full()` would not fire until a full interval after the function completes so the delay between calls would be 1.0 / `fps` * 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.

`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

### ClutterParamSpecFixed

    typedef struct {
      CoglFixed minimum;
      CoglFixed maximum;
      CoglFixed default_value;
    } ClutterParamSpecFixed;

GParamSpec subclass for fixed point based properties

CoglFixed `minimum`; | lower boundary
CoglFixed `maximum`; | higher boundary
CoglFixed `default_value`; | default value

Since 0.8

### clutter_param_spec_fixed ()

    GParamSpec *        clutter_param_spec_fixed            (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             CoglFixed minimum,
                                                             CoglFixed maximum,
                                                             CoglFixed default_value,
                                                             GParamFlags flags);

Creates a GParamSpec for properties using CoglFixed values

`name` : | name of the property
`nick` : | short name
`blurb` : | description (can be translatable)
`minimum` : | lower boundary
`maximum` : | higher boundary
`default_value` : | default value
`flags` : | flags for the param spec
Returns : | the newly created GParamSpec

Since 0.8

### CLUTTER_VALUE_HOLDS_FIXED()

    #define CLUTTER_VALUE_HOLDS_FIXED(x)    (G_VALUE_HOLDS ((x), COGL_TYPE_FIXED))

Evaluates to `TRUE` if `x` holds a CoglFixed .

`x` : | a GValue

Since 0.8

### clutter_value_set_fixed ()

    void                clutter_value_set_fixed             (GValue *value,
                                                             CoglFixed fixed_);

Sets `value` to `fixed_`.

`value` : | a GValue initialized to `COGL_TYPE_FIXED`
`fixed_` : | the fixed point value to set

Since 0.8

### clutter_value_get_fixed ()

    CoglFixed           clutter_value_get_fixed             (const GValue *value);

Gets the fixed point value stored inside `value`.

`value` : | a GValue initialized to `COGL_TYPE_FIXED`
Returns : | the value inside the passed GValue

Since 0.8