mirror of
https://github.com/visgl/luma.gl.git
synced 2025-12-08 17:36:19 +00:00
115 lines
3.6 KiB
Markdown
115 lines
3.6 KiB
Markdown
# Timeline
|
|
|
|
Manages an animation timeline, with multiple channels that can be running at different rates, durations, etc. Many methods (`play`, `pause`) assume that the `update` method is being called once per frame with a "global time". This automatically done for `AnimationLoop.timeline` object.
|
|
|
|
## Parallel Times
|
|
|
|
The key concept at work in the `Timeline` is running multiple time frames in parallel:
|
|
|
|
- Global Time: The "system time" as determined by the application. Used by `Timeline` to determine the rate at which to play.
|
|
- Timeline Time: The "parent" time of all channels on the timeline. Can be played at the same rate as "Global Time" or manipulated manually.
|
|
- Channel Time: Will update in lock step with "Timeline Time", but may move at different rates, loop, etc. depending on channel parameters.
|
|
|
|
## Usage
|
|
|
|
Automatic update usage (assume `update` method is being called once per frame):
|
|
|
|
```typescript
|
|
animationLoop.attachTimeline(new Timeline());
|
|
const timeline = animationLoop.timeline;
|
|
const channel1 = timeline.addChannel({
|
|
rate: 0.5,
|
|
duration: 4000,
|
|
repeat: Number.POSITIVE_INFINITY
|
|
});
|
|
const channel2 = timeline.addChannel({
|
|
rate: 2,
|
|
delay: 500,
|
|
duration: 1000,
|
|
repeat: 3
|
|
});
|
|
|
|
timeline.pause();
|
|
timeline.play();
|
|
|
|
model.setUniforms({
|
|
uValue1: timeline.getTime(channel1);
|
|
uValue2: timeline.getTime(channel2);
|
|
});
|
|
```
|
|
|
|
Manual usage:
|
|
|
|
```typescript
|
|
const timeline = new Timeline();
|
|
const channel1 = timeline.addChannel({
|
|
rate: 0.5,
|
|
duration: 4000,
|
|
repeat: Number.POSITIVE_INFINITY
|
|
});
|
|
const channel2 = timeline.addChannel({
|
|
rate: 2,
|
|
delay: 500,
|
|
duration: 1000,
|
|
repeat: 3
|
|
});
|
|
timeline.setTime(500);
|
|
|
|
model.setUniforms({
|
|
uValue1: timeline.getTime(channel1);
|
|
uValue2: timeline.getTime(channel2);
|
|
});
|
|
```
|
|
|
|
## Methods
|
|
|
|
### addChannel([props: Object]) : number
|
|
|
|
Add a new channel to the timeline. Returns a handle to the channel that can be use for subsequent interactions. Valid propeties are:
|
|
|
|
- `rate` the speed of the channel's time relative to timeline time.
|
|
- `delay` offset into timeline time at which channel time starts elapsing, in timeline time units.
|
|
- `duration` the length of the channel time frame, in timeline time units.
|
|
- `repeat` how many time to repeat channel time's timeline. Only meaningful if `duration` is finite.
|
|
|
|
### removeChannel(handle : number)
|
|
|
|
Remove a channel from the timeline. `handle` should be a value that was returned by `addChannel`.
|
|
|
|
### isFinished(handle : number) : Boolean
|
|
|
|
Returns whether the channel's time has completely elapsed.
|
|
|
|
### getTime([handle : number]) : number
|
|
|
|
Return the current time of the channel indicated by `handle`. If no handle is provided, return timeline time.
|
|
|
|
### setTime(time : number)
|
|
|
|
Set the timeline time to the given value.
|
|
|
|
### play
|
|
|
|
Allow timeline time to be updated by calls to `update`.
|
|
|
|
### pause
|
|
|
|
Prevent timeline time from being updated by calls to `update`.
|
|
|
|
### reset
|
|
|
|
Reset timeline time to `0`.
|
|
|
|
### attachAnimation(animation: Object, [channelHandle : number]) : number
|
|
|
|
Attach an animation object (can be any object with a `setTime` method, e.g. [KeyFrames](/docs/api-reference/engine/animation/key-frames), `GLTFAnimator`) to the timeline, optionally attached to a specific channel referenced by `channelHandle`.
|
|
The animation object's time will be updated whenever the timeline updates. Returns a handle that can be used to reference the animation attachement.
|
|
|
|
### detachAnimation(handle : number)
|
|
|
|
Detach an animation object from the timeline. `handle` should be a value that was returned by `attachAnimation`.
|
|
|
|
### update(globalTime : number)
|
|
|
|
Expected to be called once per frame, with whatever is considered the "system time". Required for `play` and `pause` to work properly.
|