isa/mutter
1
0
Fork 0
mirror of https://github.com/brl/mutter.git synced 2024-11-22 16:10:41 -05:00
Code Issues Packages Projects Releases Wiki Activity

2008-05-12 Robert Bragg <bob@openedhand.com>

Browse Source 
* clutter/clutter-timeline.c:
	Adds clutter-timeline documentation RE: r2337, explaining
	the current timeline semantics.
This commit is contained in:
Robert Bragg 2008-05-12 15:18:38 +00:00
parent 6fa7aeef85
commit c76e576141
2 changed files with 53 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
ChangeLog
View File

@ -1,3 +1,9 @@
2008-05-12 Robert Bragg <bob@openedhand.com>
* clutter/clutter-timeline.c:
Adds clutter-timeline documentation RE: r2337, explaining
the current timeline semantics.
2008-05-12 Emmanuele Bassi <ebassi@openedhand.com>
* HACKING.backends: Update documentation.

55
clutter/clutter-timeline.c
View File

@ -31,13 +31,52 @@
* as animations.
*
* Every timeline shares the same #ClutterTimeoutPool to decrease the
* possibility of starvating the main loop when using many timelines
* 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 starts with
* clutter_timeline_get_current_frame() == 0.
*
* After starting a timeline, the first timeout is for current_frame_num == 1
* (Notably it isn't 0 since there is a delay before the first timeout signals
* so re-asserting the starting frame (0) wouldn't make sense.)
* Notably, this implies that actors you intend to be affected by the
* timeline's progress, should be manually primed/positioned for frame 0 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
* current_frame_num == @n_frames
*
* For a looping timeline the timeout for current_frame_num == @n_frames would
* be followed by a timeout for current_frame_num == 1 (remember frame 0 is
* considered == frame (@n_frames)).
*
* 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
* current_frame_num == @n_frames will always be signaled, but notably frame 1
* can be interpolated past and so never signaled.
*
*/
#ifdef HAVE_CONFIG_H
@ -397,7 +436,7 @@ clutter_timeline_class_init (ClutterTimelineClass *klass)
CLUTTER_PARAM_READWRITE));
/**
* ClutterTimeline:direction:
*
*
* The direction of the timeline, either %CLUTTER_TIMELINE_FORWARD or
* %CLUTTER_TIMELINE_BACKWARD.
*
@ -415,7 +454,7 @@ clutter_timeline_class_init (ClutterTimelineClass *klass)
/**
* ClutterTimeline::new-frame:
* @timeline: the timeline which received the signal
* @frame_num: the number of the new frame between 0 and
* @frame_num: the number of the new frame between 0 and
* ClutterTimeline:num-frames
*
* The ::new-frame signal is emitted each time a new frame in the
@ -609,7 +648,7 @@ timeline_timeout_func (gpointer data)
{
gint frame_num = priv->current_frame_num - i;
GSList *markers, *l;
markers = g_hash_table_lookup (priv->markers_by_frame,
GUINT_TO_POINTER (frame_num));
for (l = markers; l; l = l->next)
@ -641,7 +680,7 @@ timeline_timeout_func (gpointer data)
ClutterTimelineDirection saved_direction = priv->direction;
guint overflow_frame_num = priv->current_frame_num;
gint end_frame;
/* In case the signal handlers want to take a peek... */
if (priv->direction == CLUTTER_TIMELINE_FORWARD)
priv->current_frame_num = priv->n_frames;
@ -674,7 +713,7 @@ timeline_timeout_func (gpointer data)
if (!priv->loop && priv->timeout_id)
{
/* We remove the timeout now, so that the completed signal handler
* may choose to re-start the timeline
* may choose to re-start the timeline
*
* ** Perhaps we should remove this earlier, and regardless
* of priv->loop. Are we limiting the things that could be done in
@ -688,7 +727,7 @@ timeline_timeout_func (gpointer data)
/* Again check to see if the user has manually played with
* current_frame_num, before we finally stop or loop the timeline */
if (priv->current_frame_num != end_frame &&
if (priv->current_frame_num != end_frame &&
!(/* Except allow moving from frame 0 -> n_frame (or vica-versa)
since these are considered equivalent */
(priv->current_frame_num == 0 && end_frame == priv->n_frames) ||
@ -1135,7 +1174,7 @@ clutter_timeline_clone (ClutterTimeline *timeline)
*
* Creates a new #ClutterTimeline with a duration of @msecs using
* the value of the ClutterTimeline:fps property to compute the
* equivalent number of frames.
* equivalent number of frames.
*
* Return value: the newly created #ClutterTimeline
*