ClutterAlpha

## ClutterAlpha ClutterAlpha — A class for calculating a value as a function of time |

## Synopsis

                        ClutterAlpha;
    struct              ClutterAlphaClass;
    gdouble             (*ClutterAlphaFunc)                 (ClutterAlpha *alpha,
                                                             gpointer user_data);
    ClutterAlpha *      clutter_alpha_new                   (void);
    ClutterAlpha *      clutter_alpha_new_full              (ClutterTimeline *timeline,
                                                             gulong mode);
    ClutterAlpha *      clutter_alpha_new_with_func         (ClutterTimeline *timeline,
                                                             ClutterAlphaFunc func,
                                                             gpointer data,
                                                             GDestroyNotify destroy);
    void                clutter_alpha_set_timeline          (ClutterAlpha *alpha,
                                                             ClutterTimeline *timeline);
    ClutterTimeline *   clutter_alpha_get_timeline          (ClutterAlpha *alpha);
    void                clutter_alpha_set_mode              (ClutterAlpha *alpha,
                                                             gulong mode);
    gulong              clutter_alpha_get_mode              (ClutterAlpha *alpha);
    gdouble             clutter_alpha_get_alpha             (ClutterAlpha *alpha);

    void                clutter_alpha_set_func              (ClutterAlpha *alpha,
                                                             ClutterAlphaFunc func,
                                                             gpointer data,
                                                             GDestroyNotify destroy);
    void                clutter_alpha_set_closure           (ClutterAlpha *alpha,
                                                             GClosure *closure);

    gulong              clutter_alpha_register_closure      (GClosure *closure);
    gulong              clutter_alpha_register_func         (ClutterAlphaFunc func,
                                                             gpointer data);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterAlpha

## Implemented Interfaces

ClutterAlpha implements ClutterScriptable.

## Properties

      "alpha"                    gdouble               : Read
      "mode"                     gulong                : Read / Write / Construct
      "timeline"                 ClutterTimeline*      : Read / Write

## Description

ClutterAlpha is a class for calculating an floating point value dependent only on the position of a ClutterTimeline.

### Warning

For newly written code, it is recommended to use the "progress-mode" property of ClutterTimeline, or the `clutter_timeline_set_progress_func()` function instead of ClutterAlpha. The ClutterAlpha class will be deprecated in the future, and will not be available any more in the next major version of Clutter.

A ClutterAlpha binds a ClutterTimeline to a progress function which translates the time T into an adimensional factor alpha. The factor can then be used to drive a ClutterBehaviour, which will translate the alpha value into something meaningful for a ClutterActor.

You should provide a ClutterTimeline and bind it to the ClutterAlpha instance using `clutter_alpha_set_timeline()`. You should also set an "animation mode", either by using the ClutterAnimationMode values that Clutter itself provides or by registering custom functions using `clutter_alpha_register_func()`.

Instead of a ClutterAnimationMode you may provide a function returning the alpha value depending on the progress of the timeline, using `clutter_alpha_set_func()` or `clutter_alpha_set_closure()`. The alpha function will be executed each time a new frame in the ClutterTimeline is reached.

Since the alpha function is controlled by the timeline instance, you can pause, stop or resume the ClutterAlpha from calling the alpha function by using the appropriate functions of the ClutterTimeline object.

ClutterAlpha is used to "drive" a ClutterBehaviour instance, and it is internally used by the ClutterAnimation API.

Figure 8. Easing modes provided by Clutter

### ClutterAlpha custom properties for ClutterScript

ClutterAlpha defines a custom "function" property for ClutterScript which allows to reference a custom alpha function available in the source code. Setting the "function" property is equivalent to calling `clutter_alpha_set_func()` with the specified function name. No user data or GDestroyNotify is available to be passed.

Example 10. Defining a ClutterAlpha in ClutterScript

The following JSON fragment defines a ClutterAlpha using a ClutterTimeline with id "sine-timeline" and an alpha function called `my_sine_alpha`. The defined ClutterAlpha instance can be reused in multiple ClutterBehaviour definitions or for ClutterAnimation definitions.

    {
      "id" : "sine-alpha",
      "timeline" : {
        "id" : "sine-timeline",
        "duration" : 500,
        "loop" : true
      },
      "function" : "my_sine_alpha"
    }

For the way to define the "mode" property inside a ClutterScript fragment, see the corresponding section in ClutterAnimation.

## Details

### ClutterAlpha

    typedef struct _ClutterAlpha ClutterAlpha;

ClutterAlpha combines a ClutterTimeline and a function. The contents of the ClutterAlpha structure are private and should only be accessed using the provided API.

Since 0.2

### struct ClutterAlphaClass

    struct ClutterAlphaClass {
    };

Base class for ClutterAlpha

Since 0.2

### ClutterAlphaFunc ()

    gdouble             (*ClutterAlphaFunc)                 (ClutterAlpha *alpha,
                                                             gpointer user_data);

A function returning a value depending on the position of the ClutterTimeline bound to `alpha`.

`alpha` : | a ClutterAlpha
`user_data` : | user data passed to the function
Returns : | a floating point value

Since 0.2

### clutter_alpha_new ()

    ClutterAlpha *      clutter_alpha_new                   (void);

Creates a new ClutterAlpha instance. You must set a function to compute the alpha value using `clutter_alpha_set_func()` and bind a ClutterTimeline object to the ClutterAlpha instance using `clutter_alpha_set_timeline()`.

You should use the newly created ClutterAlpha instance inside a ClutterBehaviour object.

Returns : | the newly created empty ClutterAlpha instance.

Since 0.2

### clutter_alpha_new_full ()

    ClutterAlpha *      clutter_alpha_new_full              (ClutterTimeline *timeline,
                                                             gulong mode);

Creates a new ClutterAlpha instance and sets the timeline and animation mode.

See also `clutter_alpha_set_timeline()` and `clutter_alpha_set_mode()`.

`timeline` : | ClutterTimeline timeline
`mode` : | animation mode
Returns : | the newly created ClutterAlpha

Since 1.0

### clutter_alpha_new_with_func ()

    ClutterAlpha *      clutter_alpha_new_with_func         (ClutterTimeline *timeline,
                                                             ClutterAlphaFunc func,
                                                             gpointer data,
                                                             GDestroyNotify destroy);

Creates a new ClutterAlpha instances and sets the timeline and the alpha function.

This function will not register `func` as a global alpha function.

See also `clutter_alpha_set_timeline()` and `clutter_alpha_set_func()`.

`timeline` : | a ClutterTimeline
`func` : | a ClutterAlphaFunc
`data` : | data to pass to the function, or `NULL`
`destroy` : | function to call when removing the alpha function, or `NULL`
Returns : | the newly created ClutterAlpha

Since 1.0

### clutter_alpha_set_timeline ()

    void                clutter_alpha_set_timeline          (ClutterAlpha *alpha,
                                                             ClutterTimeline *timeline);

Binds `alpha` to `timeline`.

`alpha` : | A ClutterAlpha
`timeline` : | A ClutterTimeline

Since 0.2

### clutter_alpha_get_timeline ()

    ClutterTimeline *   clutter_alpha_get_timeline          (ClutterAlpha *alpha);

Gets the ClutterTimeline bound to `alpha`.

`alpha` : | A ClutterAlpha
Returns : | a ClutterTimeline instance. [transfer none]

Since 0.2

### clutter_alpha_set_mode ()

    void                clutter_alpha_set_mode              (ClutterAlpha *alpha,
                                                             gulong mode);

Sets the progress function of `alpha` using the symbolic value of `mode`, as taken by the ClutterAnimationMode enumeration or using the value returned by `clutter_alpha_register_func()`.

`alpha` : | a ClutterAlpha
`mode` : | a ClutterAnimationMode

Since 1.0

### clutter_alpha_get_mode ()

    gulong              clutter_alpha_get_mode              (ClutterAlpha *alpha);

Retrieves the ClutterAnimationMode used by `alpha`.

`alpha` : | a ClutterAlpha
Returns : | the animation mode

Since 1.0

### clutter_alpha_get_alpha ()

    gdouble             clutter_alpha_get_alpha             (ClutterAlpha *alpha);

Query the current alpha value.

`alpha` : | A ClutterAlpha
Returns : | The current alpha value for the alpha

Since 0.2

### clutter_alpha_set_func ()

    void                clutter_alpha_set_func              (ClutterAlpha *alpha,
                                                             ClutterAlphaFunc func,
                                                             gpointer data,
                                                             GDestroyNotify destroy);

Sets the ClutterAlphaFunc function used to compute the alpha value at each frame of the ClutterTimeline bound to `alpha`.

This function will not register `func` as a global alpha function.

`alpha` : | A ClutterAlpha
`func` : | A ClutterAlphaFunc
`data` : | user data to be passed to the alpha function, or `NULL`
`destroy` : | notify function used when disposing the alpha function

Since 0.2

### clutter_alpha_set_closure ()

    void                clutter_alpha_set_closure           (ClutterAlpha *alpha,
                                                             GClosure *closure);

Sets the GClosure used to compute the alpha value at each frame of the ClutterTimeline bound to `alpha`.

`alpha` : | A ClutterAlpha
`closure` : | A GClosure

Since 0.8

### clutter_alpha_register_closure ()

    gulong              clutter_alpha_register_closure      (GClosure *closure);

GClosure variant of `clutter_alpha_register_func()`.

Registers a global alpha function and returns its logical id to be used by `clutter_alpha_set_mode()` or by ClutterAnimation.

The logical id is always greater than `CLUTTER_ANIMATION_LAST`.

Rename to: clutter_alpha_register_func

`closure` : | a GClosure
Returns : | the logical id of the alpha function

Since 1.0

### clutter_alpha_register_func ()

    gulong              clutter_alpha_register_func         (ClutterAlphaFunc func,
                                                             gpointer data);

Registers a global alpha function and returns its logical id to be used by `clutter_alpha_set_mode()` or by ClutterAnimation.

The logical id is always greater than `CLUTTER_ANIMATION_LAST`.

`func` : | a ClutterAlphaFunc
`data` : | user data to pass to `func`, or `NULL`
Returns : | the logical id of the alpha function

Since 1.0

## Property Details

### The `"alpha"` property

      "alpha"                    gdouble               : Read

The alpha value as computed by the alpha function. The linear interval is 0.0 to 1.0, but the Alpha allows overshooting by one unit in each direction, so the valid interval is -1.0 to 2.0.

Allowed values: [-1,2]

Default value: 0

Since 0.2

### The `"mode"` property

      "mode"                     gulong                : Read / Write / Construct

The progress function logical id - either a value from the ClutterAnimationMode enumeration or a value returned by `clutter_alpha_register_func()`.

If `CLUTTER_CUSTOM_MODE` is used then the function set using `clutter_alpha_set_closure()` or `clutter_alpha_set_func()` will be used.

Since 1.0

### The `"timeline"` property

      "timeline"                 ClutterTimeline*      : Read / Write

A ClutterTimeline instance used to drive the alpha function.

Since 0.2