ph-curves

no_std, zero-allocation curve lookup tables and tickless scheduling for embedded Rust.

Features

Static LUTs — curves are pre-computed at build time into static arrays, so evaluation is a single index into a &'static [u8; 256] (or [u16; 65536]).
no_std / no_alloc — the library itself has zero runtime allocation. Only the fixed crate is required at runtime (fixed-point math).
Tickless scheduling — computes the next wall-clock deadline where the quantized output value changes, so your firmware can sleep instead of polling.
Code-gen CLI — a companion binary (ph-curves-gen) reads a simple TOML file and emits the Rust source for all your curves.

Quick start

1. Define curves in TOML

Create a file (e.g. assets/curves.toml):

[curves.ease_in_quad]

builtin = "ease_in_quad"



[curves.gamma_22]

formula = "pow(t, 2.2)"



[curves.contrast_boost]

points = [[0, 0], [64, 32], [128, 128], [192, 224], [255, 255]]

Each curve uses exactly one of three definition styles:

Style	Description
`builtin`	Name of a built-in easing function (14 available)
`formula`	Math expression in `t` (0→1), evaluated at build time
`points`	Piecewise-linear control points `[input, output]`

Set monotonic = false to skip inverse-LUT generation (default is true).

2. Generate Rust source

cargo install --path . --features gen


ph-curves-gen --input assets/curves.toml --output src/curves.rs

This produces a .rs file with static arrays and const curve values ready to include! or copy into your crate.

For 16-bit resolution:

ph-curves-gen --input assets/curves.toml --output src/curves.rs \

    --value-type u16 --lut-size 65536

3. Use in firmware

use ph_curves::{Curve, MonotonicCurve, Tickless, Rounding};

include!("curves.rs");

// Simple evaluation — one table lookup.
let brightness: u8 = GAMMA_22.eval(input);

// Tickless scheduling — sleep until the next value change.
let schedule = EASE_IN_QUAD.tickless_schedule(
    0,           // t0_ms: start time
    1000,        // duration_ms
    0,           // start value
    255,         // end value
    10,          // step (quantization)
    Rounding::Nearest,
    0,           // min_dt_ms
);

for deadline in schedule.iter(0) {
    set_timer(deadline.deadline_ms);
    set_output(deadline.current_val);
}

Built-in curves

Name	Formula	Description
`linear`	`t`	Identity / straight line
`ease_in_quad`	`t²`	Quadratic ease-in
`ease_out_quad`	`1-(1-t)²`	Quadratic ease-out
`ease_in_out_quad`	piecewise quadratic	Quadratic ease-in-out
`ease_in_cubic`	`t³`	Cubic ease-in
`ease_out_cubic`	`1-(1-t)³`	Cubic ease-out
`ease_in_out_cubic`	piecewise cubic	Cubic ease-in-out
`ease_in_quart`	`t⁴`	Quartic ease-in
`ease_out_quart`	`1-(1-t)⁴`	Quartic ease-out
`ease_in_out_quart`	piecewise quartic	Quartic ease-in-out
`ease_in_expo`	`2^(10(t-1))`	Exponential ease-in
`ease_out_expo`	`1-2^(-10t)`	Exponential ease-out
`smoothstep`	`3t²-2t³`	Hermite smoothstep
`smoother_step`	`6t⁵-15t⁴+10t³`	Ken Perlin's improved smoothstep

Legacy aliases: ease_in, ease_out, ease_in_out (mapped to the quad variants).

Formula syntax

Formulas are math expressions over the variable t (0.0 to 1.0).

Operators: + - * / ^ (or **), unary -, parentheses.

Functions: pow(x,y) sqrt(x) abs(x) min(x,y) max(x,y) clamp(x,lo,hi) sin(x) cos(x) tan(x) exp(x) ln(x) log2(x)

Constants: pi e

[curves.cie_lightness]

formula = "pow((t + 0.16) / 1.16, 3.0)"

Library API

Core types

Type	Description
`CurveLut<I,V,N,M>`	Forward LUT + optional inverse LUT
`MonotonicCurveLut<I,V,N,M>`	Forward + required inverse LUT
`CurveLut256`	Type alias: `CurveLut<u8, u8, 256>`
`MonotonicCurveLut256`	Type alias: `MonotonicCurveLut<u8, u8, 256>`
`CurveLut65536`	Type alias: `CurveLut<u16, u16, 65536>`
`MonotonicCurveLut65536`	Type alias: `MonotonicCurveLut<u16, u16, 65536>`

Traits

Curve<I, V> — eval(u: I) -> V — single table lookup.
MonotonicCurve<I, V> — adds inv(w: V) -> I — inverse lookup.
Tickless<T> — adds tickless_schedule(...) to any MonotonicCurve.
UnitValue — implemented for u8 and u16; maps the unit interval onto a discrete integer range with fixed-point helpers.

Tickless scheduling

TicklessSchedule computes the exact deadline (in milliseconds) at which the quantized output value will next change. This lets interrupt-driven firmware sleep between value changes instead of polling at a fixed tick rate.

Supports RepeatMode::Once, RepeatMode::Repeat, and RepeatMode::PingPong.

Math helpers

lerp_u8(a, b, w) / lerp_u16(a, b, w) — interpolate with u8 weight.
map_u8_to_u16(w, max) — scale a u8 into a u16 range.
quantize(value, step, rounding) — snap to a step size.
next_target_value(current, end, step, increasing) — next quantized target.

Minimum supported Rust version

Rust 1.92.0 (edition 2024).

Contributing

Contributions are welcome! Please read the contributing guide before opening a pull request.

This project follows the Contributor Covenant Code of Conduct. By participating you agree to uphold it.

For security issues, see our security policy.

License

MIT

ph-curves 0.1.1