ClutterAlpha: Clutter Reference Manual

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

## Functions

gdouble | (*ClutterAlphaFunc) ()
ClutterAlpha * | clutter_alpha_new ()
ClutterAlpha * | clutter_alpha_new_full ()
ClutterAlpha * | clutter_alpha_new_with_func ()
void | clutter_alpha_set_timeline ()
ClutterTimeline * | clutter_alpha_get_timeline ()
void | clutter_alpha_set_mode ()
gulong | clutter_alpha_get_mode ()
gdouble | clutter_alpha_get_alpha ()
void | clutter_alpha_set_func ()
void | clutter_alpha_set_closure ()
gulong | clutter_alpha_register_closure ()
gulong | clutter_alpha_register_func ()

## Properties

gdouble | alpha | Read
gulong | mode | Read / Write / Construct
ClutterTimeline * | timeline | Read / Write

## Types and Values

| ClutterAlpha
struct | ClutterAlphaClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterAlpha

## Implemented Interfaces

ClutterAlpha implements ClutterScriptable.

## Description

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

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.

ClutterAlpha is available since Clutter 0.2.

ClutterAlpha is deprecated since Clutter 1.12. ClutterTimeline and the “progress-mode” property replace this whole class.

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

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.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    {
      "id" : "sine-alpha",
      "timeline" : {
        "id" : "sine-timeline",
        "duration" : 500,
        "loop" : true
      },
      "function" : "my_sine_alpha"
    }

## Functions

### ClutterAlphaFunc ()

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

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

Use ClutterTimelineProgressFunc instead.

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

#### Parameters

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

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

Use ClutterTimeline instead

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

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

Use ClutterTimeline instead

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

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

#### Parameters

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

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

Use ClutterTimeline instead

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

#### Parameters

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

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

Use ClutterTimeline directly

Binds `alpha` to `timeline` .

#### Parameters

alpha | A ClutterAlpha |
timeline | A ClutterTimeline |

Since: 0.2

### clutter_alpha_get_timeline ()

    ClutterTimeline *
    clutter_alpha_get_timeline (ClutterAlpha *alpha);

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

Use ClutterTimeline directlry

Gets the ClutterTimeline bound to `alpha` .

#### Parameters

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

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

Use ClutterTimeline and `clutter_timeline_set_progress_mode()` instead

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

#### Parameters

alpha | a ClutterAlpha |
mode | a ClutterAnimationMode |

Since: 1.0

### clutter_alpha_get_mode ()

    gulong
    clutter_alpha_get_mode (ClutterAlpha *alpha);

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

Use ClutterTimeline instead

Retrieves the ClutterAnimationMode used by `alpha` .

#### Parameters

alpha | a ClutterAlpha |

#### Returns

the animation mode

Since: 1.0

### clutter_alpha_get_alpha ()

    gdouble
    clutter_alpha_get_alpha (ClutterAlpha *alpha);

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

Use `clutter_timeline_get_progress()`

Query the current alpha value.

#### Parameters

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

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

Use `clutter_timeline_set_progress_func()`

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.

#### Parameters

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

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

Use `clutter_timeline_set_progress_func()`

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

#### Parameters

alpha | A ClutterAlpha |
closure | A GClosure |

Since: 0.8

### clutter_alpha_register_closure ()

    gulong
    clutter_alpha_register_closure (GClosure *closure);

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

There is no direct replacement for this function. Use `clutter_timeline_set_progress_func()` on each specific ClutterTimeline instance

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]

#### Parameters

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

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

There is no direct replacement for this function. Use `clutter_timeline_set_progress_func()` on each specific ClutterTimeline instance

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

[skip]

#### Parameters

func | a ClutterAlphaFunc |
data | user data to pass to `func` , or `NULL` |

#### Returns

the logical id of the alpha function

Since: 1.0

## Types and Values

### ClutterAlpha

    typedef struct _ClutterAlpha ClutterAlpha;

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

Use ClutterTimeline instead

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 {
    };

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

Use ClutterTimeline instead

Base class for ClutterAlpha

Since: 0.2

## Property Details

### The `“alpha”` property

      “alpha”                    gdouble

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.

`ClutterAlpha:alpha` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “new-frame” and `clutter_timeline_get_progress()` instead

Flags: Read

Allowed values: [-1,2]

Default value: 0

Since: 0.2

### The `“mode”` property

      “mode”                     gulong

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.

`ClutterAlpha:mode` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “progress-mode”

Flags: Read / Write / Construct

Since: 1.0

### The `“timeline”` property

      “timeline”                 ClutterTimeline *

A ClutterTimeline instance used to drive the alpha function.

`ClutterAlpha:timeline` has been deprecated since version 1.12 and should not be used in newly-written code.

Flags: Read / Write

Since: 0.2