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};
52#[cfg(feature = "facet")]
53use facet::Facet;
54use function_name::named;
55#[cfg(feature = "serde")]
56use serde::{Deserialize, Serialize};
57use smallvec::SmallVec;
58use std::{
59    fmt::Debug,
60    hash::{Hash, Hasher},
61};
62
63mod macros;
64use macros::impl_sample_for_value;
65
66mod animated_data;
67mod data;
68mod data_types;
69#[cfg(feature = "interpolation")]
70mod interpolation;
71#[cfg(feature = "lua")]
72mod lua;
73mod shutter;
74mod time_data_map;
75mod token_value_map;
76mod value;
77
78pub use animated_data::*;
79pub use data::*;
80pub use data_types::*;
81#[cfg(feature = "interpolation")]
82pub use interpolation::*;
83#[cfg(feature = "lua")]
84pub use lua::*;
85pub use shutter::*;
86pub use time_data_map::*;
87pub use token_value_map::*;
88pub use value::*;
89
90/// A time value represented as a fixed-point [`Tick`](frame_tick::Tick).
91pub type Time = frame_tick::Tick;
92
93/// Trait for getting data type information.
94pub trait DataTypeOps {
95    /// Returns the [`DataType`] variant for this value.
96    fn data_type(&self) -> DataType;
97    /// Returns a string name for this data type.
98    fn type_name(&self) -> &'static str;
99}
100
101impl DataTypeOps for Value {
102    fn data_type(&self) -> DataType {
103        match self {
104            Value::Uniform(data) => data.data_type(),
105            Value::Animated(animated_data) => animated_data.data_type(),
106        }
107    }
108
109    fn type_name(&self) -> &'static str {
110        match self {
111            Value::Uniform(data) => data.type_name(),
112            Value::Animated(animated_data) => animated_data.type_name(),
113        }
114    }
115}
token_value_map/lib.rs

token_value_map/
lib.rs
