token_value_map/
lib.rs

1//! A time-based data mapping library for animation and interpolation.
2//!
3//! This crate provides types for storing and manipulating data that changes
4//! over time. It supports both uniform (static) and animated (time-varying)
5//! values with automatic interpolation between keyframes.
6//!
7//! # Core Types
8//!
9//! - [`Value`]: A value that can be either uniform or animated over time.
10//! - [`Data`]: A variant enum containing all supported data types.
11//! - [`AnimatedData`]: Time-indexed data with interpolation support.
12//! - [`TimeDataMap`]: A mapping from time to data values.
13//! - [`TokenValueMap`]: A collection of named values indexed by tokens.
14//!
15//! # Data Types
16//!
17//! The library supports scalar types ([`Boolean`], [`Integer`], [`Real`],
18//! [`String`]), vector types ([`Vector2`], [`Vector3`], [`Color`],
19//! [`Matrix3`]), and collections of these types ([`BooleanVec`],
20//! [`IntegerVec`], etc.).
21//!
22//! # Motion Blur Sampling
23//!
24//! Use the [`Sample`] trait with a [`Shutter`] to generate motion blur samples
25//! for animated values during rendering.
26//!
27//! # Interpolation (Optional Feature)
28//!
29//! When the `interpolation` feature is enabled, [`TimeDataMap`] supports
30//! advanced interpolation modes including bezier curves with tangent control.
31//! This enables integration with professional animation systems like Dopamine.
32//!
33//! # Examples
34//!
35//! ```rust
36//! use frame_tick::Tick;
37//! use token_value_map::*;
38//!
39//! // Create a uniform value.
40//! let uniform = Value::uniform(42.0);
41//!
42//! // Create an animated value.
43//! let animated =
44//!     Value::animated(vec![(Tick::new(0), 0.0), (Tick::new(10), 10.0)])
45//!         .unwrap();
46//!
47//! // Sample at a specific time.
48//! let interpolated = animated.interpolate(Tick::new(5));
49//! ```
50
51use anyhow::{Result, anyhow};
52use function_name::named;
53#[cfg(feature = "serde")]
54use serde::{Deserialize, Serialize};
55use smallvec::SmallVec;
56use std::{
57    fmt::Debug,
58    hash::{Hash, Hasher},
59};
60
61mod macros;
62use macros::impl_sample_for_value;
63
64mod animated_data;
65mod data;
66mod data_types;
67#[cfg(feature = "interpolation")]
68mod interpolation;
69#[cfg(feature = "lua")]
70mod lua;
71mod shutter;
72mod time_data_map;
73mod token_value_map;
74mod value;
75
76pub use animated_data::*;
77pub use data::*;
78pub use data_types::*;
79#[cfg(feature = "interpolation")]
80pub use interpolation::*;
81#[cfg(feature = "lua")]
82pub use lua::*;
83pub use shutter::*;
84pub use time_data_map::*;
85pub use token_value_map::*;
86pub use value::*;
87
88/// A time value represented as a fixed-point [`Tick`](frame_tick::Tick).
89pub type Time = frame_tick::Tick;
90
91/// Trait for getting data type information.
92pub trait DataTypeOps {
93    /// Returns the [`DataType`] variant for this value.
94    fn data_type(&self) -> DataType;
95    /// Returns a string name for this data type.
96    fn type_name(&self) -> &'static str;
97}
98
99impl DataTypeOps for Value {
100    fn data_type(&self) -> DataType {
101        match self {
102            Value::Uniform(data) => data.data_type(),
103            Value::Animated(animated_data) => animated_data.data_type(),
104        }
105    }
106
107    fn type_name(&self) -> &'static str {
108        match self {
109            Value::Uniform(data) => data.type_name(),
110            Value::Animated(animated_data) => animated_data.type_name(),
111        }
112    }
113}
token_value_map/lib.rs

token_value_map/
lib.rs
