Crate token_value_map

Expand description

A time-based data mapping library for animation and interpolation.

This crate provides types for storing and manipulating data that changes over time. It supports both uniform (static) and animated (time-varying) values with automatic interpolation between keyframes.

§Core Types

Token: A string key type wrapping Ustr (with ustr feature) or String (without) used for lookups.
Value: A value that can be either uniform or animated over time.
Data: A variant enum containing all supported data types.
AnimatedData: Time-indexed data with interpolation support.
TimeDataMap: A mapping from time to data values.
TokenValueMap: A collection of named values indexed by tokens.

§Data Types

The library supports scalar types (Boolean, Integer, Real, String), vector types (Vector2, [Vector3], Color, Matrix3), and collections of these types (BooleanVec, IntegerVec, etc.).

§Motion Blur Sampling

Use the Sample trait with a Shutter to generate motion blur samples for animated values during rendering.

§Interpolation (Optional Feature)

When the interpolation feature is enabled, TimeDataMap supports advanced interpolation modes including bezier curves with tangent control. This enables integration with professional animation systems like Dopamine.

§Curve Types (Optional `curves` Feature)

When the curves feature is enabled (on by default), the crate provides RealCurve and ColorCurve types for position-keyed parameter mappings. These use KeyDataMap<Position, T> under the hood, where Position is a normalized [0, 1] key type.

use token_value_map::*;

// Create a falloff curve: ramps linearly from 0 → 1.
let curve = RealCurve::linear();
assert_eq!(curve.evaluate(0.0), 0.0);
assert_eq!(curve.evaluate(1.0), 1.0);

// Create a black-to-white color gradient.
let gradient = ColorCurve::black_to_white();
let mid = gradient.evaluate(0.5);  // ~[0.5, 0.5, 0.5, 1.0]
assert!(mid[0] > 0.4 && mid[0] < 0.6);

§Examples

use frame_tick::Tick;
use token_value_map::*;

// Create a uniform value.
let uniform = Value::uniform(42.0);

// Create an animated value.
let animated =
    Value::animated(vec![(Tick::new(0), 0.0), (Tick::new(10), 10.0)])
        .unwrap();

// Sample at a specific time.
let interpolated = animated.interpolate(Tick::new(5));

Modules§

math: Math backend implementations.

Macros§

define_data_types: Define a custom data type system with full interpolation support.

Structs§

Boolean: A boolean value wrapper.
BooleanVec: A vector of boolean values.
Color: A 4-component RGBA color value.
ColorCurve: A color-valued curve mapping Position → Color.
ColorVec: A vector of color values.
GenericTokenValueMap: A collection of named values indexed by string tokens.
Integer: A 64-bit signed integer wrapper.
IntegerVec: A vector of integer values.
KeyDataMap: A generic key-value data map with interpolation support.
Matrix3: A 3×3 transformation matrix.
Matrix3Vec: A vector of transformation matrices.
Position: A normalized position in [0, 1] for curve stop domains.
Real: A 64-bit floating-point number wrapper.
RealCurve: A real-valued curve mapping Position → Real.
RealVec: A vector of real values.
Shutter: Shutter timing for motion blur sampling.
String: A UTF-8 string wrapper.
StringVec: A vector of string values.
Token: A string token used as a key in TokenValueMap and GenericTokenValueMap.
TokenValueMap: A collection of named values indexed by string tokens.
Vector2: A 2D vector.
Vector2Vec: A vector of 2D vectors.

Enums§

AnimatedData: Time-indexed data with interpolation support.
Data: A variant enum containing all supported data types.
DataType
Error: Error type for token-value-map operations.
GenericValue: A value that can be either uniform or animated over time.
Value: A value that can be either uniform or animated over time.

Traits§

AnimatedDataOps: Common operations trait for animated data types.
AnimatedDataSystem: Animated data container for a DataSystem.
DataSystem: A complete data type system.
DataTypeOps: Trait for getting data type information.
Interpolatable: Marker trait for types that support time-based interpolation.
Sample: trait for generating motion blur samples with shutter timing.
TimeDataMapControl: Control operations trait for time data maps.
ToF32: Trait for converting data types to f32 for curve editing.

Type Aliases§

Result: Result type alias using the crate’s Error type.
SampleWeight: Weight value for motion blur sampling.
Time: A time value represented as a fixed-point Tick.
TimeDataMap: A time-keyed data map. Alias for KeyDataMap<Time, V>.