brl/mutter
1
0
Fork 0
Code Issues Pull Requests 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> 2008-05-12 Emmanuele Bassi <ebassi@openedhand.com>
* HACKING.backends: Update documentation. * HACKING.backends: Update documentation.

41
clutter/clutter-timeline.c
View File

@ -31,13 +31,52 @@
* as animations. * as animations.
* *
* Every timeline shares the same #ClutterTimeoutPool to decrease the * 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 * 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. * 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 * In that case you might disable the common timeline pool by setting
* the %CLUTTER_TIMELINE=no-pool environment variable prior to launching * the %CLUTTER_TIMELINE=no-pool environment variable prior to launching
* your application. * 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 #ifdef HAVE_CONFIG_H