ClutterTimeline

ClutterTimeline — A class for time-based events

Synopsis

                    ClutterTimeline;
                    ClutterTimelineClass;
ClutterTimeline *   clutter_timeline_new                (guint msecs);
ClutterTimeline *   clutter_timeline_clone              (ClutterTimeline *timeline);

void                clutter_timeline_set_duration       (ClutterTimeline *timeline,
                                                         guint msecs);
guint               clutter_timeline_get_duration       (ClutterTimeline *timeline);
void                clutter_timeline_set_loop           (ClutterTimeline *timeline,
                                                         gboolean loop);
gboolean            clutter_timeline_get_loop           (ClutterTimeline *timeline);
void                clutter_timeline_set_delay          (ClutterTimeline *timeline,
                                                         guint msecs);
guint               clutter_timeline_get_delay          (ClutterTimeline *timeline);
enum                ClutterTimelineDirection;
void                clutter_timeline_set_direction      (ClutterTimeline *timeline,
                                                         ClutterTimelineDirection direction);
ClutterTimelineDirection  clutter_timeline_get_direction
                                                        (ClutterTimeline *timeline);

void                clutter_timeline_start              (ClutterTimeline *timeline);
void                clutter_timeline_pause              (ClutterTimeline *timeline);
void                clutter_timeline_stop               (ClutterTimeline *timeline);
void                clutter_timeline_rewind             (ClutterTimeline *timeline);
void                clutter_timeline_skip               (ClutterTimeline *timeline,
                                                         guint msecs);
void                clutter_timeline_advance            (ClutterTimeline *timeline,
                                                         guint msecs);
guint               clutter_timeline_get_elapsed_time   (ClutterTimeline *timeline);
guint               clutter_timeline_get_delta          (ClutterTimeline *timeline);
gdouble             clutter_timeline_get_progress       (ClutterTimeline *timeline);
CoglFixed           clutter_timeline_get_progressx      (ClutterTimeline *timeline);
gboolean            clutter_timeline_is_playing         (ClutterTimeline *timeline);

void                clutter_timeline_add_marker_at_time (ClutterTimeline *timeline,
                                                         const gchar *marker_name,
                                                         guint msecs);
gboolean            clutter_timeline_has_marker         (ClutterTimeline *timeline,
                                                         const gchar *marker_name);
gchar **            clutter_timeline_list_markers       (ClutterTimeline *timeline,
                                                         gint msecs,
                                                         gsize *n_markers);
void                clutter_timeline_remove_marker      (ClutterTimeline *timeline,
                                                         const gchar *marker_name);
void                clutter_timeline_advance_to_marker  (ClutterTimeline *timeline,
                                                         const gchar *marker_name);

Object Hierarchy

  GObject
   +----ClutterTimeline

Properties

  "delay"                    guint                 : Read / Write
  "direction"                ClutterTimelineDirection  : Read / Write
  "duration"                 guint                 : Read / Write
  "loop"                     gboolean              : Read / Write

Signals

  "completed"                                      : Run Last
  "marker-reached"                                 : Run Last / No Recursion / Has Details / No Hooks
  "new-frame"                                      : Run Last
  "paused"                                         : Run Last
  "started"                                        : Run Last

Description

ClutterTimeline is a base class for managing time based events such as animations.

Every timeline shares the same ClutterTimeoutPool to decrease the possibility of starving the main loop when using many timelines at the same time; this might cause problems if you are also using a library making heavy use of threads with no GLib main loop integration.

In that case you might disable the common timeline pool by setting the CLUTTER_TIMELINE=no-pool environment variable prior to launching your application.

One way to visualise a timeline is as a path with marks along its length. When creating a timeline of N frames via clutter_timeline_new(), then the number of frames can be seen as the paths length, and each unit of length (each frame) is delimited by a mark.

For a non looping timeline there will be (N frames + 1) marks along its length. For a looping timeline, the two ends are joined with one mark. Technically this mark represents two discrete frame numbers, but for a looping timeline the start and end frame numbers are considered equivalent.

When you create a timeline it will be initialized so that the current frame, as returned by clutter_timeline_get_current_frame(), will be 0.

After starting a timeline, the first timeout is for frame number one (notably it isn't zero since there is a delay before the first "new-frame" signal, so re-asserting the frame number zero wouldn't make sense).

This implies that actors you intend to be affected by the timeline's progress should be manually primed or positioned for frame zero which will be displayed before the first timeout (if you are not careful about this point you will likely see flashes of incorrect actor state in your program).

For a non looping timeline the last timeout would be for the number of frames in the timeline, as returned by clutter_timeline_get_n_frames().

For a looping timeline the timeout for the last frame would be followed by a timeout for frame number 1.

There may be times when a system is not able to meet the frame rate requested for a timeline, and in this case the frame number will be interpolated at the next timeout event. The interpolation is calculated from the time that the timeline was started, not from the time of the last timeout, so a given timeline should basically elapse in the same - real world - time on any given system. An invariable here though is that the last frame will always be signaled, but notably frame number 1 can be interpolated past and thus never signaled.

Details

ClutterTimeline

typedef struct _ClutterTimeline ClutterTimeline;

The ClutterTimeline structure contains only private data and should be accessed using the provided API

Since 0.2


ClutterTimelineClass

typedef struct {
  void (*started)        (ClutterTimeline *timeline);
  void (*completed)      (ClutterTimeline *timeline);
  void (*paused)         (ClutterTimeline *timeline);
  
  void (*new_frame)      (ClutterTimeline *timeline,
		          gint             frame_num);

  void (*marker_reached) (ClutterTimeline *timeline,
                          const gchar     *marker_name,
                          gint             frame_num);
} ClutterTimelineClass;

The ClutterTimelineClass structure contains only private data

started ()

handler for the "started" signal

completed ()

handler for the "completed" signal

paused ()

handler for the "paused" signal

new_frame ()

handler for the "new-frame" signal

marker_reached ()

handler for the "marker-reached" signal

Since 0.2


clutter_timeline_new ()

ClutterTimeline *   clutter_timeline_new                (guint msecs);

msecs :

Returns :


clutter_timeline_clone ()

ClutterTimeline *   clutter_timeline_clone              (ClutterTimeline *timeline);

Create a new ClutterTimeline instance which has property values matching that of supplied timeline. The cloned timeline will not be started and will not be positioned to the current position of timeline: you will have to start it with clutter_timeline_start().

timeline :

ClutterTimeline to duplicate.

Returns :

a new ClutterTimeline, cloned from timeline

Since 0.4


clutter_timeline_set_duration ()

void                clutter_timeline_set_duration       (ClutterTimeline *timeline,
                                                         guint msecs);

Sets the duration of the timeline, in milliseconds. The speed of the timeline depends on the ClutterTimeline:fps setting.

timeline :

a ClutterTimeline

msecs :

duration of the timeline in milliseconds

Since 0.6


clutter_timeline_get_duration ()

guint               clutter_timeline_get_duration       (ClutterTimeline *timeline);

Retrieves the duration of a ClutterTimeline in milliseconds. See clutter_timeline_set_duration().

timeline :

a ClutterTimeline

Returns :

the duration of the timeline, in milliseconds.

Since 0.6


clutter_timeline_set_loop ()

void                clutter_timeline_set_loop           (ClutterTimeline *timeline,
                                                         gboolean loop);

Sets whether timeline should loop.

timeline :

a ClutterTimeline

loop :

TRUE for enable looping

clutter_timeline_get_loop ()

gboolean            clutter_timeline_get_loop           (ClutterTimeline *timeline);

Gets whether timeline is looping

timeline :

a ClutterTimeline

Returns :

TRUE if the timeline is looping

clutter_timeline_set_delay ()

void                clutter_timeline_set_delay          (ClutterTimeline *timeline,
                                                         guint msecs);

Sets the delay, in milliseconds, before timeline should start.

timeline :

a ClutterTimeline

msecs :

delay in milliseconds

Since 0.4


clutter_timeline_get_delay ()

guint               clutter_timeline_get_delay          (ClutterTimeline *timeline);

Retrieves the delay set using clutter_timeline_set_delay().

timeline :

a ClutterTimeline

Returns :

the delay in milliseconds.

Since 0.4


enum ClutterTimelineDirection

typedef enum {
  CLUTTER_TIMELINE_FORWARD,
  CLUTTER_TIMELINE_BACKWARD
} ClutterTimelineDirection;

The direction of a ClutterTimeline

CLUTTER_TIMELINE_FORWARD

forward direction for a timeline

CLUTTER_TIMELINE_BACKWARD

backward direction for a timeline

Since 0.6


clutter_timeline_set_direction ()

void                clutter_timeline_set_direction      (ClutterTimeline *timeline,
                                                         ClutterTimelineDirection direction);

Sets the direction of timeline, either CLUTTER_TIMELINE_FORWARD or CLUTTER_TIMELINE_BACKWARD.

timeline :

a ClutterTimeline

direction :

the direction of the timeline

Since 0.6


clutter_timeline_get_direction ()

ClutterTimelineDirection  clutter_timeline_get_direction
                                                        (ClutterTimeline *timeline);

Retrieves the direction of the timeline set with clutter_timeline_set_direction().

timeline :

a ClutterTimeline

Returns :

the direction of the timeline

Since 0.6


clutter_timeline_start ()

void                clutter_timeline_start              (ClutterTimeline *timeline);

Starts the ClutterTimeline playing.

timeline :

A ClutterTimeline

clutter_timeline_pause ()

void                clutter_timeline_pause              (ClutterTimeline *timeline);

Pauses the ClutterTimeline on current frame

timeline :

A ClutterTimeline

clutter_timeline_stop ()

void                clutter_timeline_stop               (ClutterTimeline *timeline);

Stops the ClutterTimeline and moves to frame 0

timeline :

A ClutterTimeline

clutter_timeline_rewind ()

void                clutter_timeline_rewind             (ClutterTimeline *timeline);

Rewinds ClutterTimeline to the first frame if its direction is CLUTTER_TIMELINE_FORWARD and the last frame if it is CLUTTER_TIMELINE_BACKWARD.

timeline :

A ClutterTimeline

clutter_timeline_skip ()

void                clutter_timeline_skip               (ClutterTimeline *timeline,
                                                         guint msecs);

Advance timeline by the requested time in milliseconds

timeline :

A ClutterTimeline

msecs :

Amount of time to skip

clutter_timeline_advance ()

void                clutter_timeline_advance            (ClutterTimeline *timeline,
                                                         guint msecs);

Advance timeline to the requested point. The point is given as a time in milliseconds since the timeline started.

Note

The timeline will not emit the "new-frame" signal for the given time. The first ::new-frame signal after the call to clutter_timeline_advance() will be emit the skipped markers.

timeline :

A ClutterTimeline

msecs :

Time to advance to

clutter_timeline_get_elapsed_time ()

guint               clutter_timeline_get_elapsed_time   (ClutterTimeline *timeline);

Request the current time position of the timeline.

timeline :

A ClutterTimeline

Returns :

current elapsed time in milliseconds.

clutter_timeline_get_delta ()

guint               clutter_timeline_get_delta          (ClutterTimeline *timeline);

Retrieves the amount of time elapsed since the last ClutterTimeline::new-frame signal.

This function is only useful inside handlers for the ::new-frame signal, and its behaviour is undefined if the timeline is not playing.

timeline :

a ClutterTimeline

Returns :

the amount of time in milliseconds elapsed since the last frame

Since 0.6


clutter_timeline_get_progress ()

gdouble             clutter_timeline_get_progress       (ClutterTimeline *timeline);

The position of the timeline in a [0, 1] interval.

timeline :

a ClutterTimeline

Returns :

the position of the timeline.

Since 0.6


clutter_timeline_get_progressx ()

CoglFixed           clutter_timeline_get_progressx      (ClutterTimeline *timeline);

Fixed point version of clutter_timeline_get_progress().

timeline :

a ClutterTimeline

Returns :

the position of the timeline as a fixed point value

Since 0.6


clutter_timeline_is_playing ()

gboolean            clutter_timeline_is_playing         (ClutterTimeline *timeline);

Queries state of a ClutterTimeline.

timeline :

A ClutterTimeline

Returns :

TRUE if timeline is currently playing

clutter_timeline_add_marker_at_time ()

void                clutter_timeline_add_marker_at_time (ClutterTimeline *timeline,
                                                         const gchar *marker_name,
                                                         guint msecs);

Adds a named marker that will be hit when the timeline has been running for msecs milliseconds. Markers are unique string identifiers for a given time. Once timeline reaches msecs, it will emit a ::marker-reached signal for each marker attached to that time.

A marker can be removed with clutter_timeline_remove_marker(). The timeline can be advanced to a marker using clutter_timeline_advance_to_marker().

timeline :

a ClutterTimeline

marker_name :

the unique name for this marker

msecs :

position of the marker in milliseconds

Since 0.8


clutter_timeline_has_marker ()

gboolean            clutter_timeline_has_marker         (ClutterTimeline *timeline,
                                                         const gchar *marker_name);

Checks whether timeline has a marker set with the given name.

timeline :

a ClutterTimeline

marker_name :

the name of the marker

Returns :

TRUE if the marker was found

Since 0.8


clutter_timeline_list_markers ()

gchar **            clutter_timeline_list_markers       (ClutterTimeline *timeline,
                                                         gint msecs,
                                                         gsize *n_markers);

Retrieves the list of markers at time msecs. If frame_num is a negative integer, all the markers attached to timeline will be returned.

timeline :

a ClutterTimeline

msecs :

the time to check, or -1

n_markers :

the number of markers returned

Returns :

array zero-terminated=1 length=n_markers. array zero-terminated=1 length=n_markers.

Since 0.8


clutter_timeline_remove_marker ()

void                clutter_timeline_remove_marker      (ClutterTimeline *timeline,
                                                         const gchar *marker_name);

Removes marker_name, if found, from timeline.

timeline :

a ClutterTimeline

marker_name :

the name of the marker to remove

Since 0.8


clutter_timeline_advance_to_marker ()

void                clutter_timeline_advance_to_marker  (ClutterTimeline *timeline,
                                                         const gchar *marker_name);

Advances timeline to the time of the given marker_name.

Note

Like clutter_timeline_advance(), this function will not emit the "new-frame" for the time where marker_name is set, nor it will emit "marker-reached" for marker_name.

timeline :

a ClutterTimeline

marker_name :

the name of the marker

Since 0.8

Property Details

The "delay" property

  "delay"                    guint                 : Read / Write

A delay, in milliseconds, that should be observed by the timeline before actually starting.

Default value: 0

Since 0.4


The "direction" property

  "direction"                ClutterTimelineDirection  : Read / Write

The direction of the timeline, either CLUTTER_TIMELINE_FORWARD or CLUTTER_TIMELINE_BACKWARD.

Default value: CLUTTER_TIMELINE_FORWARD

Since 0.6


The "duration" property

  "duration"                 guint                 : Read / Write

Duration of the timeline in milliseconds, depending on the ClutterTimeline:fps value.

Default value: 1000

Since 0.6


The "loop" property

  "loop"                     gboolean              : Read / Write

Whether the timeline should automatically rewind and restart.

Default value: FALSE

Signal Details

The "completed" signal

void                user_function                      (ClutterTimeline *timeline,
                                                        gpointer         user_data)      : Run Last

The ::completed signal is emitted when the timeline reaches the number of frames specified by the ClutterTimeline:num-frames property.

timeline :

the ClutterTimeline which received the signal

user_data :

user data set when the signal handler was connected.

The "marker-reached" signal

void                user_function                      (ClutterTimeline *timeline,
                                                        gchar           *marker_name,
                                                        gint             msecs,
                                                        gpointer         user_data)        : Run Last / No Recursion / Has Details / No Hooks

The ::marker-reached signal is emitted each time a timeline reaches a marker set with clutter_timeline_add_marker_at_time(). This signal is detailed with the name of the marker as well, so it is possible to connect a callback to the ::marker-reached signal for a specific marker with:

  clutter_timeline_add_marker_at_time (timeline, "foo", 500);
  clutter_timeline_add_marker_at_time (timeline, "bar", 750);
  g_signal_connect (timeline, "marker-reached",
                    G_CALLBACK (each_marker_reached), NULL);
  g_signal_connect (timeline, "marker-reached::foo",
                    G_CALLBACK (foo_marker_reached), NULL);
  g_signal_connect (timeline, "marker-reached::bar",
                    G_CALLBACK (bar_marker_reached), NULL);

In the example, the first callback will be invoked for both the "foo" and "bar" marker, while the second and third callbacks will be invoked for the "foo" or "bar" markers, respectively.

timeline :

the ClutterTimeline which received the signal

marker_name :

the name of the marker reached

msecs :

the elapsed time

user_data :

user data set when the signal handler was connected.

Since 0.8


The "new-frame" signal

void                user_function                      (ClutterTimeline *timeline,
                                                        gint             msecs,
                                                        gpointer         user_data)      : Run Last

The ::new-frame signal is emitted for each timeline running timeline before a new frame is drawn to give animations a chance to update the scene.

timeline :

the timeline which received the signal

msecs :

the elapsed time between 0 and duration

user_data :

user data set when the signal handler was connected.

The "paused" signal

void                user_function                      (ClutterTimeline *timeline,
                                                        gpointer         user_data)      : Run Last

The ::paused signal is emitted when clutter_timeline_pause() is invoked.

timeline :

the ClutterTimeline which received the signal

user_data :

user data set when the signal handler was connected.

The "started" signal

void                user_function                      (ClutterTimeline *timeline,
                                                        gpointer         user_data)      : Run Last

The ::started signal is emitted when the timeline starts its run. This might be as soon as clutter_timeline_start() is invoked or after the delay set in the ClutterTimeline:delay property has expired.

timeline :

the ClutterTimeline which received the signal

user_data :

user data set when the signal handler was connected.