
@c %start of fragment

@node ClutterAlpha
@chapter ClutterAlpha
A class for calculating a value as a function of time

@section Overview
@code{<clutter-alpha>} is a class for calculating an floating point
value dependent only on the position of a @code{<clutter-timeline>}.

@c (warning "For newly written code, it is recommended to use the\n"
(code "<\"progress-mode\">") " property of " (code "<clutter-timeline>")
", or the\n" (code "clutter-timeline-set-progress-func") " function
instead of " (code "<clutter-alpha>") ".\nThe " (code "<clutter-alpha>")
" class will be deprecated in the future, and will not\nbe available any
more in the next major version of Clutter.")

A @code{<clutter-alpha>} binds a @code{<clutter-timeline>} to a progress
function which translates the time T into an adimensional factor alpha.
The factor can then be used to drive a @code{<clutter-behaviour>}, which
will translate the alpha value into something meaningful for a
@code{<clutter-actor>}.

You should provide a @code{<clutter-timeline>} and bind it to the
@code{<clutter-alpha>} instance using @code{clutter-alpha-set-timeline}.
You should also set an "animation mode", either by using the
@code{<clutter-animation-mode>} values that Clutter itself provides or
by registering custom functions using
@code{clutter-alpha-register-func}.

Instead of a @code{<clutter-animation-mode>} you may provide a function
returning the alpha value depending on the progress of the timeline,
using @code{clutter-alpha-set-func} or @code{clutter-alpha-set-closure}.
The alpha function will be executed each time a new frame in the
@code{<clutter-timeline>} is reached.

Since the alpha function is controlled by the timeline instance, you can
pause, stop or resume the @code{<clutter-alpha>} from calling the alpha
function by using the appropriate functions of the
@code{<clutter-timeline>} object.

@code{<clutter-alpha>} is used to "drive" a @code{<clutter-behaviour>}
instance, and it is internally used by the @code{<clutter-animation>}
API.

(The missing figure, easing-modes

@c (title "Easing modes provided by Clutter")
@section ClutterAlpha custom properties for @code{<clutter-script>}
@code{<clutter-alpha>} defines a custom "function" property for
@code{<clutter-script>} which allows to reference a custom alpha
function available in the source code. Setting the "function" property
is equivalent to calling @code{clutter-alpha-set-func} with the
specified function name. No user data or @code{<g-destroy-notify>} is
available to be passed.

@c (example (@ (id "ClutterAlpha-script-example")))
@c (title "Defining a ClutterAlpha in ClutterScript")
The following JSON fragment defines a @code{<clutter-alpha>} using a
@code{<clutter-timeline>} with id "sine-timeline" and an alpha function
called @code{my-sine-alpha}. The defined @code{<clutter-alpha>} instance
can be reused in multiple @code{<clutter-behaviour>} definitions or for
@code{<clutter-animation>} definitions.

@example 

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

For the way to define the @code{<"mode">} property inside a
ClutterScript fragment, see the corresponding section in
@code{<clutter-animation>}.

@section Usage
@include defuns-clutter-alpha.xml.texi

@c %end of fragment
