Clutter Reference Manual: Utilities

## Utilities Utilities — Utility functions |

## Functions

gint | clutter_util_next_p2 ()
ClutterTimeoutPool * | clutter_timeout_pool_new ()
guint | clutter_timeout_pool_add ()
void | clutter_timeout_pool_remove ()
guint | clutter_frame_source_add ()
guint | clutter_frame_source_add_full ()
GParamSpec * | clutter_param_spec_fixed ()
#define | CLUTTER_VALUE_HOLDS_FIXED()
void | clutter_value_set_fixed ()
CoglFixed | clutter_value_get_fixed ()

## Types and Values

struct | ClutterParamSpecFixed

## Description

Various miscellaneous utilility functions.

## Functions

### clutter_util_next_p2 ()

    gint
    clutter_util_next_p2 (gint a);

`clutter_util_next_p2` has been deprecated since version 1.2 and should not be used in newly-written code.

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

#### Parameters

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

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

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.

#### Parameters

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

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

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

#### Parameters

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`. | [closure]
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_);

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

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

#### Parameters

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

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

Simple wrapper around `clutter_frame_source_add_full()`.

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

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

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

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.

Rename to: clutter_frame_source_add

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

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

Use GParamSpecInt instead.

Creates a GParamSpec for properties using CoglFixed values

#### Parameters

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.

[transfer full]

Since 0.8

### CLUTTER_VALUE_HOLDS_FIXED()

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

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

Use `G_VALUE_HOLDS_INT` instead

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

#### Parameters

x | a GValue |

Since 0.8

### clutter_value_set_fixed ()

    void
    clutter_value_set_fixed (GValue *value,
                             CoglFixed fixed_);

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

Use `g_value_set_int()` instead.

Sets `value` to `fixed_` .

#### Parameters

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

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

Use `g_value_get_int()` instead.

Gets the fixed point value stored inside `value` .

#### Parameters

value | a GValue initialized to `COGL_TYPE_FIXED` |

#### Returns

the value inside the passed GValue

Since 0.8

## Types and Values

### struct ClutterParamSpecFixed

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

`ClutterParamSpecFixed` is deprecated and should not be used in newly-written code.

Use GParamSpecInt instead

GParamSpec subclass for fixed point based properties

#### Members

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

Since 0.8