tempa 0.1.6

A no_std temporal system for animation and simulation, providing time, duration, time ranges, frame rates, and deterministic frame-index stepping.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

# Tempa

[![Tag](https://img.shields.io/github/v/tag/tailflare/tempa)](https://github.com/tailflare/tempa/tags)
[![Crates.io Version](https://img.shields.io/crates/v/tempa)](https://crates.io/crates/tempa)
[![docs.rs](https://img.shields.io/docsrs/tempa)](https://docs.rs/tempa)
[![Main CI Build Status](https://img.shields.io/github/actions/workflow/status/tailflare/tempa/ci.yml?label=main%20build)](https://github.com/tailflare/tempa/actions/workflows/ci.yml)
[![License](https://img.shields.io/crates/l/tempa)](#license)


A no_std library for working with time in animation and real-time systems.

It provides a small set of temporal primitives: time, duration, time ranges, frame rates, and frame-based stepping. Designed around deterministic conversion between continuous time and discrete frame indices.

This makes it suitable for animation systems, simulations, and engine tooling where frame-accurate behavior matters.

## Status

⚠️ Experimental / Work in Progress

The API is still evolving and may change significantly.

## Features

- no_std compatible
- Time and Duration types
- Frame rate representation
- Time ranges and range operations
- Deterministic frame <-> time conversion
- Frame-based stepping utilities

## Usage
### std
```toml
tempa = "0.1.4"
```

### no_std
```toml
tempa = { version = "0.1.4", default-features = false }
```

### Example
```rust
// Create a frame stepper running at 60 FPS and a simple 10-second clip.
let rate = FrameRate::from_fps(60.0);
let mut stepper = FrameStepper::new(rate);
let clip = TimeRange::new(Time::from_seconds(0.0), Time::from_seconds(10.0));

// Advance the playhead by 120 frames (2 seconds at 60 FPS).
stepper.step(120);
assert_eq!(stepper.current(), FrameIndex::new(120));
assert_abs_diff_eq!(stepper.current_time().seconds(), 2.0, epsilon = 1e-12);

// Convert explicitly between discrete frames and continuous time.
let frame = conversion::frame_from_time(Time::from_seconds(1.25), rate);
assert_eq!(frame, FrameIndex::new(75));

let time = conversion::time_from_frame(frame, rate);
assert_abs_diff_eq!(time.seconds(), 1.25, epsilon = 1e-12);

// Seek to an arbitrary time. Times between frame boundaries are rounded
// down to the frame currently containing that instant.
stepper.seek_time(Time::from_seconds(2.75));
assert_eq!(stepper.current(), FrameIndex::new(165));
assert_abs_diff_eq!(stepper.current_time().seconds(), 2.75, epsilon = 1e-12);

// Normalize the playhead position within the clip.
let u = clip.normalize_time(stepper.current_time());
assert_abs_diff_eq!(u, 0.275, epsilon = 1e-12);

// Remap the same normalized position into another time range.
let outro = TimeRange::new(Time::from_seconds(8.0), Time::from_seconds(10.0));
let outro_time = clip.remap_time(stepper.current_time(), &outro);
assert_abs_diff_eq!(outro_time.seconds(), 8.55, epsilon = 1e-12);

// Construct ranges directly from scalar seconds.
let window: TimeRange<f64> = (1.0..3.5).into();
assert_abs_diff_eq!(window.duration().seconds(), 2.5, epsilon = 1e-12);

// Merge overlapping ranges, for example when combining timeline edits.
let a = TimeRange::new(Time::from_seconds(1.0), Time::from_seconds(4.0));
let b = TimeRange::new(Time::from_seconds(3.5), Time::from_seconds(6.0));
let merged = a.union(&b);
assert_eq!(merged, TimeRange::new(Time::from_seconds(1.0), Time::from_seconds(6.0)));

// Stepping past the beginning of the timeline saturates at frame zero.
stepper.step(-10_000);
assert_eq!(stepper.current(), FrameIndex::ZERO);
assert_abs_diff_eq!(stepper.current_time().seconds(), 0.0, epsilon = 1e-12);
```

## License

The Tempa project is licensed under either the Apache License, Version 2.0 or the MIT license, at your option.

See [LICENSE-APACHE](./LICENSE-APACHE) and [LICENSE-MIT](./LICENSE-MIT) for details.