tiny.rig.curve

1pub const ParameterMachine = struct {2    states: []ParameterState,3    state_count: usize,4    state_capacity: usize,5    transitions: []Transition,6    transition_count: usize,7    transition_capacity: usize,8    mixer: *ParameterMixer,910    current: ?usize = null,11    current_layer: ?usize = null,1213    target: ?usize = null,14    target_layer: ?usize = null,15    blend_duration: f32 = 0,16    blend_elapsed: f32 = 0,1718    pub fn init(19        allocator: Allocator,20        mixer: *ParameterMixer,21        max_states: usize,22        max_transitions: usize,23    ) !ParameterMachine {24        const states = try allocator.alloc(ParameterState, max_states);25        const transitions = try allocator.alloc(Transition, max_transitions);26        return .{27            .states = states,28            .state_count = 0,29            .state_capacity = max_states,30            .transitions = transitions,31            .transition_count = 0,32            .transition_capacity = max_transitions,33            .mixer = mixer,34        };35    }3637    pub fn deinit(self: *ParameterMachine, allocator: Allocator) void {38        allocator.free(self.states);39        allocator.free(self.transitions);40        self.* = undefined;41    }4243    pub fn addState(self: *ParameterMachine, clip: *const ParameterClip, state_name: []const u8, opts: struct {44        speed: f32 = 1.0,45        loop: bool = true,46    }) !usize {47        if (self.state_count >= self.state_capacity) return error.TooManyStates;48        const idx = self.state_count;49        var state = ParameterState{50            .clip = clip,51            .speed = opts.speed,52            .loop = opts.loop,53        };54        const copy_len = @min(state_name.len, 32);55        @memcpy(state.name_buf[0..copy_len], state_name[0..copy_len]);56        state.name_len = copy_len;57        self.states[idx] = state;58        self.state_count += 1;59        return idx;60    }6162    pub fn setInitialState(self: *ParameterMachine, state_idx: usize) !void {63        if (state_idx >= self.state_count) return error.InvalidState;64        self.resetRuntimeState();65        const st = &self.states[state_idx];66        const layer = self.mixer.addLayer(st.clip, .{67            .speed = st.speed,68            .loop = st.loop,69        }) catch return error.MixerFull;70        self.current = state_idx;71        self.current_layer = layer;72    }7374    pub fn addTransition(self: *ParameterMachine, tr: Transition) !void {75        if (self.transition_count >= self.transition_capacity) return error.TooManyTransitions;76        self.transitions[self.transition_count] = tr;77        self.transition_count += 1;78    }7980    pub fn isTransitioning(self: *const ParameterMachine) bool {81        return self.target != null;82    }8384    pub fn currentState(self: *const ParameterMachine) ?usize {85        return self.current;86    }8788    pub fn fireTrigger(self: *ParameterMachine, trigger_name: []const u8) void {89        const cur = self.current orelse return;90        if (self.isTransitioning()) return;9192        for (self.transitions[0..self.transition_count]) |*tr| {93            if (tr.from_state != cur) continue;94            const tr_trigger = tr.trigger() orelse continue;95            if (!std.mem.eql(u8, tr_trigger, trigger_name)) continue;96            if (tr.condition) |cond| {97                if (!cond()) continue;98            }99            self.beginTransition(tr);100            return;101        }102    }103104    pub fn update(self: *ParameterMachine, dt: f32) void {105        if (self.current == null) return;106        self.mixer.advance(dt);107108        if (self.isTransitioning()) {109            self.advanceBlend(dt);110        } else {111            self.checkAutoTransitions();112            self.checkConditionTransitions();113        }114    }115116    fn beginTransition(self: *ParameterMachine, tr: *const Transition) void {117        const st = &self.states[tr.to_state];118        const target_layer = self.mixer.addLayer(st.clip, .{119            .weight = 0.0,120            .speed = st.speed,121            .loop = st.loop,122        }) catch return;123        self.target = tr.to_state;124        self.blend_duration = tr.blend_duration;125        self.blend_elapsed = 0;126        self.target_layer = target_layer;127    }128129    fn advanceBlend(self: *ParameterMachine, dt: f32) void {130        self.blend_elapsed += dt;131        if (self.blend_duration <= 0 or self.blend_elapsed >= self.blend_duration) {132            if (self.current_layer) |cl| self.mixer.removeLayer(cl);133            if (self.target_layer) |tl| {134                self.mixer.layers[tl].weight = 1.0;135            }136            self.current = self.target;137            self.current_layer = self.target_layer;138            self.target = null;139            self.target_layer = null;140            self.blend_duration = 0;141            self.blend_elapsed = 0;142        } else {143            const t = self.blend_elapsed / self.blend_duration;144            if (self.current_layer) |cl| {145                self.mixer.layers[cl].weight = 1.0 - t;146            }147            if (self.target_layer) |tl| {148                self.mixer.layers[tl].weight = t;149            }150        }151    }152153    fn resetRuntimeState(self: *ParameterMachine) void {154        if (self.current_layer) |layer| {155            self.mixer.removeLayer(layer);156        }157        if (self.target_layer) |layer| {158            if (self.current_layer) |current_layer| {159                if (current_layer != layer) {160                    self.mixer.removeLayer(layer);161                }162            } else {163                self.mixer.removeLayer(layer);164            }165        }166        self.current = null;167        self.current_layer = null;168        self.target = null;169        self.target_layer = null;170        self.blend_duration = 0;171        self.blend_elapsed = 0;172    }173174    fn checkAutoTransitions(self: *ParameterMachine) void {175        const cur = self.current orelse return;176        const cl = self.current_layer orelse return;177        const layer = &self.mixer.layers[cl];178        if (layer.loop or layer.time < layer.clip.duration) return;179180        for (self.transitions[0..self.transition_count]) |*tr| {181            if (tr.from_state != cur) continue;182            if (tr.has_trigger or tr.condition != null) continue;183            self.beginTransition(tr);184            return;185        }186    }187188    fn checkConditionTransitions(self: *ParameterMachine) void {189        const cur = self.current orelse return;190191        for (self.transitions[0..self.transition_count]) |*tr| {192            if (tr.from_state != cur) continue;193            if (tr.has_trigger) continue;194            const cond = tr.condition orelse continue;195            if (cond()) {196                self.beginTransition(tr);197                return;198            }199        }200    }201};

1pub const ParameterState = struct {2    name_buf: [32]u8 = undefined,3    name_len: usize = 0,4    clip: *const ParameterClip,5    speed: f32 = 1.0,6    loop: bool = true,78    pub fn name(self: *const ParameterState) []const u8 {9        return self.name_buf[0..self.name_len];10    }11};

1pub const Transition = struct {2    from_state: usize,3    to_state: usize,4    trigger_buf: [32]u8 = undefined,5    trigger_len: usize = 0,6    has_trigger: bool = false,7    blend_duration: f32 = 0.2,8    condition: ?ConditionFn = null,910    pub fn trigger(self: *const Transition) ?[]const u8 {11        if (self.has_trigger) return self.trigger_buf[0..self.trigger_len];12        return null;13    }14};

1pub const MixerLayer = struct {2    clip: *const ParameterClip,3    weight: f32 = 1.0,4    time: f32 = 0.0,5    speed: f32 = 1.0,6    loop: bool = false,7    active: bool = true,8};

1pub const ParameterMixer = struct {2    layers: []MixerLayer,3    layer_count: usize,4    capacity: usize,56    pub fn init(allocator: Allocator, max_layers: usize) !ParameterMixer {7        const layers = try allocator.alloc(MixerLayer, max_layers);8        return .{ .layers = layers, .layer_count = 0, .capacity = max_layers };9    }1011    pub fn deinit(self: *ParameterMixer, allocator: Allocator) void {12        allocator.free(self.layers);13        self.* = undefined;14    }1516    pub fn addLayer(self: *ParameterMixer, clip: *const ParameterClip, opts: struct {17        weight: f32 = 1.0,18        speed: f32 = 1.0,19        loop: bool = false,20    }) !usize {21        for (0..self.layer_count) |i| {22            if (!self.layers[i].active) {23                self.layers[i] = .{24                    .clip = clip,25                    .weight = opts.weight,26                    .speed = opts.speed,27                    .loop = opts.loop,28                };29                return i;30            }31        }32        if (self.layer_count >= self.capacity) return error.TooManyLayers;33        const idx = self.layer_count;34        self.layers[idx] = .{35            .clip = clip,36            .weight = opts.weight,37            .speed = opts.speed,38            .loop = opts.loop,39        };40        self.layer_count += 1;41        return idx;42    }4344    pub fn removeLayer(self: *ParameterMixer, index: usize) void {45        if (index < self.layer_count) {46            self.layers[index].active = false;47        }48    }4950    pub fn advance(self: *ParameterMixer, dt: f32) void {51        for (self.layers[0..self.layer_count]) |*layer| {52            if (!layer.active) continue;53            layer.time += dt * layer.speed;54            if (layer.loop and layer.clip.duration > 0) {55                layer.time = @mod(layer.time, layer.clip.duration);56            }57        }58    }5960    pub fn blendSlot(61        self: *const ParameterMixer,62        slot_idx: usize,63        blend_mode: SlotBlendMode,64        out: []f32,65        tmp: []f32,66    ) void {67        const dim = out.len;68        for (out) |*v| v.* = 0;69        var weight_sum: f32 = 0;70        var first = true;7172        for (self.layers[0..self.layer_count]) |*layer| {73            if (!layer.active or layer.weight <= 0) continue;74            if (slot_idx >= layer.clip.curve_count) continue;7576            layer.clip.evalSlot(slot_idx, layer.time, tmp[0..dim]);77            weight_sum += layer.weight;7879            if (dim == 1 and blend_mode == .slerp) {80                if (first) {81                    out[0] = tmp[0];82                    first = false;83                } else {84                    const t_blend = layer.weight / weight_sum;85                    out[0] = angleSlerp(out[0], tmp[0], t_blend);86                }87            } else {88                for (0..dim) |d| {89                    out[d] += layer.weight * tmp[d];90                }91            }92        }9394        if (blend_mode != .slerp or dim != 1) {95            if (weight_sum > 0) {96                for (0..dim) |d| {97                    out[d] /= weight_sum;98                }99            }100        }101    }102};

1pub const SlotBlendMode = enum {2    lerp,3    slerp,4};

1pub const ParameterClip = struct {2    name_buf: [64]u8 = undefined,3    name_len: usize = 0,4    duration: f32,5    curves: []SlotCurve,6    curve_count: usize,7    capacity: usize,89    pub fn init(allocator: Allocator, clip_name: []const u8, duration: f32, max_curves: usize) !ParameterClip {10        const curves = try allocator.alloc(SlotCurve, max_curves);11        var clip = ParameterClip{12            .duration = duration,13            .curves = curves,14            .curve_count = 0,15            .capacity = max_curves,16        };17        const copy_len = @min(clip_name.len, 64);18        @memcpy(clip.name_buf[0..copy_len], clip_name[0..copy_len]);19        clip.name_len = copy_len;20        return clip;21    }2223    pub fn deinit(self: *ParameterClip, allocator: Allocator) void {24        for (self.curves[0..self.curve_count]) |*c| {25            var spline = c.spline;26            spline.deinit(allocator);27        }28        allocator.free(self.curves);29        self.* = undefined;30    }3132    pub fn name(self: *const ParameterClip) []const u8 {33        return self.name_buf[0..self.name_len];34    }3536    pub fn addCurve(37        self: *ParameterClip,38        allocator: Allocator,39        times: []const f32,40        values: []const f32,41        dim: usize,42    ) !usize {43        if (self.curve_count >= self.capacity) return error.TooManyCurves;44        const n_kf = times.len;45        if (n_kf < 2) return error.TooFewKeyframes;46        const spline = try CatmullRomSpline.init(allocator, values, dim);47        const n_seg = n_kf - 1;48        const t_span = times[n_kf - 1] - times[0];49        const time_scale: f32 = if (t_span > 0) @as(f32, @floatFromInt(n_seg)) / t_span else 0.0;50        const idx = self.curve_count;51        self.curves[idx] = .{ .spline = spline, .time_scale = time_scale, .dim = dim };52        self.curve_count += 1;53        return idx;54    }5556    pub fn evalSlot(self: *const ParameterClip, slot_idx: usize, t: f32, out: []f32) void {57        const curve = &self.curves[slot_idx];58        const clamped = clamp(t, 0.0, self.duration);59        const spline_t = clamped * curve.time_scale;60        curve.spline.eval(spline_t, out);61    }62};

1pub const SlotCurve = struct {2    spline: CatmullRomSpline,3    time_scale: f32,4    dim: usize,5};

1pub const BlendSample = struct {2    clip: *const ParameterClip,3    parameter: f32,4    speed: f32 = 1.0,5};

1pub const BlendSpace1D = struct {2    samples: std.ArrayListUnmanaged(BlendSample) = .empty,3    capacity: usize,45    pub fn init(capacity: usize) BlendSpace1D {6        return .{ .capacity = capacity };7    }89    pub fn deinit(self: *BlendSpace1D, allocator: Allocator) void {10        self.samples.deinit(allocator);11        self.* = .{12            .capacity = 0,13        };14    }1516    pub fn sampleCount(self: *const BlendSpace1D) u32 {17        return @intCast(self.samples.items.len);18    }1920    pub fn addSample(21        self: *BlendSpace1D,22        allocator: Allocator,23        clip: *const ParameterClip,24        parameter: f32,25        speed: f32,26    ) !void {27        if (self.samples.items.len >= self.capacity) return error.TooManySamples;28        try self.samples.append(allocator, .{29            .clip = clip,30            .parameter = parameter,31            .speed = speed,32        });33        std.mem.sort(BlendSample, self.samples.items, {}, blendSampleLessThan);34    }3536    pub fn evaluateSlot(37        self: *const BlendSpace1D,38        parameter: f32,39        slot_idx: usize,40        time: f32,41        blend_mode: SlotBlendMode,42        out: []f32,43        tmp: []f32,44    ) !void {45        if (self.samples.items.len == 0) return error.EmptyBlendSpace;46        if (out.len == 0 or tmp.len < out.len) return error.BufferTooSmall;4748        const sample_pair = self.findPair(parameter);49        const left = sample_pair.left;50        const right = sample_pair.right;5152        if (slot_idx >= left.clip.curve_count) return error.InvalidSlot;53        left.clip.evalSlot(slot_idx, time * left.speed, out);5455        if (left.clip == right.clip and sample_pair.alpha == 0.0) return;56        if (slot_idx >= right.clip.curve_count) return error.InvalidSlot;57        right.clip.evalSlot(slot_idx, time * right.speed, tmp[0..out.len]);5859        if (out.len == 1 and blend_mode == .slerp) {60            out[0] = angleSlerp(out[0], tmp[0], sample_pair.alpha);61            return;62        }63        for (out, tmp[0..out.len]) |*dst, src| {64            dst.* = (1.0 - sample_pair.alpha) * dst.* + sample_pair.alpha * src;65        }66    }6768    fn findPair(self: *const BlendSpace1D, parameter: f32) BlendPair {69        const items = self.samples.items;70        if (items.len == 1 or parameter <= items[0].parameter) {71            return .{ .left = items[0], .right = items[0], .alpha = 0.0 };72        }73        if (parameter >= items[items.len - 1].parameter) {74            const tail = items[items.len - 1];75            return .{ .left = tail, .right = tail, .alpha = 0.0 };76        }7778        for (items[0 .. items.len - 1], items[1..]) |left, right| {79            if (parameter < left.parameter or parameter > right.parameter) continue;80            const span = right.parameter - left.parameter;81            const alpha = if (@abs(span) <= 1e-6)82                0.083            else84                clamp01((parameter - left.parameter) / span);85            return .{86                .left = left,87                .right = right,88                .alpha = alpha,89            };90        }9192        const tail = items[items.len - 1];93        return .{ .left = tail, .right = tail, .alpha = 0.0 };94    }95};

1pub const NotifyEvent = struct {2    id: u32,3    time: f32,4};

1pub const NotifyTrack = struct {2    events: std.ArrayListUnmanaged(NotifyEvent) = .empty,3    capacity: usize,45    pub fn init(capacity: usize) NotifyTrack {6        return .{ .capacity = capacity };7    }89    pub fn deinit(self: *NotifyTrack, allocator: Allocator) void {10        self.events.deinit(allocator);11        self.* = .{12            .capacity = 0,13        };14    }1516    pub fn addNotify(17        self: *NotifyTrack,18        allocator: Allocator,19        event_id: u32,20        time: f32,21    ) !void {22        if (self.events.items.len >= self.capacity) return error.TooManyEvents;23        try self.events.append(allocator, .{24            .id = event_id,25            .time = time,26        });27        std.mem.sort(NotifyEvent, self.events.items, {}, notifyEventLessThan);28    }2930    pub fn queryRange(31        self: *const NotifyTrack,32        start_time: f32,33        end_time: f32,34        duration: f32,35        loop: bool,36        out_ids: []u32,37        out_times: []f32,38    ) !u32 {39        if (out_ids.len != out_times.len) return error.BufferTooSmall;40        if (loop and duration <= 0.0) return error.InvalidDuration;4142        var count: usize = 0;43        if (!loop or end_time >= start_time) {44            try collectRange(self.events.items, start_time, end_time, out_ids, out_times, &count);45            return @intCast(count);46        }4748        try collectRange(self.events.items, start_time, duration, out_ids, out_times, &count);49        try collectRange(self.events.items, 0.0, end_time, out_ids, out_times, &count);50        return @intCast(count);51    }52};

1pub const CatmullRomSpline = struct {2    data: []f32,3    dim: usize,4    n_points: usize,56    pub fn init(allocator: Allocator, points: []const f32, dim: usize) !CatmullRomSpline {7        const n = points.len / dim;8        if (n < 2) return error.TooFewPoints;9        const total = n * dim * 2;10        const data = try allocator.alloc(f32, total);11        @memcpy(data[0 .. n * dim], points);12        const tangent_base = n * dim;13        for (0..n) |i| {14            const dst = data[tangent_base + i * dim ..][0..dim];15            if (i == 0) {16                const p0 = data[0..dim];17                const p1 = data[dim .. 2 * dim];18                for (0..dim) |d| dst[d] = p1[d] - p0[d];19            } else if (i == n - 1) {20                const pm = data[(n - 2) * dim ..][0..dim];21                const pl = data[(n - 1) * dim ..][0..dim];22                for (0..dim) |d| dst[d] = pl[d] - pm[d];23            } else {24                const pp = data[(i - 1) * dim ..][0..dim];25                const pn = data[(i + 1) * dim ..][0..dim];26                for (0..dim) |d| dst[d] = 0.5 * (pn[d] - pp[d]);27            }28        }29        return .{ .data = data, .dim = dim, .n_points = n };30    }3132    pub fn deinit(self: *CatmullRomSpline, allocator: Allocator) void {33        allocator.free(self.data);34        self.* = undefined;35    }3637    fn pointSlice(self: CatmullRomSpline, i: usize) []const f32 {38        return self.data[i * self.dim ..][0..self.dim];39    }4041    fn tangentSlice(self: CatmullRomSpline, i: usize) []const f32 {42        const base = self.n_points * self.dim;43        return self.data[base + i * self.dim ..][0..self.dim];44    }4546    fn segment(self: CatmullRomSpline, i: usize) CubicHermiteSegment {47        return .{48            .p0 = self.pointSlice(i),49            .m0 = self.tangentSlice(i),50            .p1 = self.pointSlice(i + 1),51            .m1 = self.tangentSlice(i + 1),52            .dim = self.dim,53        };54    }5556    pub fn eval(self: CatmullRomSpline, t: f32, out: []f32) void {57        const n_seg = self.n_points - 1;58        const n_seg_f: f32 = @floatFromInt(n_seg);59        if (t <= 0.0) {60            @memcpy(out[0..self.dim], self.pointSlice(0));61            return;62        }63        if (t >= n_seg_f) {64            @memcpy(out[0..self.dim], self.pointSlice(self.n_points - 1));65            return;66        }67        var seg_idx: usize = @intFromFloat(t);68        if (seg_idx >= n_seg) seg_idx = n_seg - 1;69        const local_t = t - @as(f32, @floatFromInt(seg_idx));70        self.segment(seg_idx).eval(local_t, out);71    }72};

1pub const CubicHermiteSegment = struct {2    p0: []const f32,3    m0: []const f32,4    p1: []const f32,5    m1: []const f32,6    dim: usize,78    pub fn eval(self: CubicHermiteSegment, t: f32, out: []f32) void {9        const t2 = t * t;10        const t3 = t2 * t;11        const h00 = 2.0 * t3 - 3.0 * t2 + 1.0;12        const h10 = t3 - 2.0 * t2 + t;13        const h01 = -2.0 * t3 + 3.0 * t2;14        const h11 = t3 - t2;15        for (0..self.dim) |i| {16            out[i] = h00 * self.p0[i] + h10 * self.m0[i] + h01 * self.p1[i] + h11 * self.m1[i];17        }18    }19};

1pub const ConditionFn = *const fn () bool;

1pub fn inferBlendMode(param_name: []const u8) SlotBlendMode {2    if (std.mem.eql(u8, param_name, "angle")) return .slerp;3    return .lerp;4}

1pub fn PeriodicSpline(comptime point_count: usize, comptime dimension: usize) type {2    if (point_count < 4) @compileError("periodic splines require at least four points");3    if (dimension == 0) @compileError("periodic splines require at least one dimension");4    return struct {5        points: [point_count][dimension]f32,67        pub fn sample(self: @This(), phase: f32) [dimension]f32 {8            std.debug.assert(std.math.isFinite(phase));9            const wrapped = phase - @floor(phase);10            const scaled = wrapped * @as(f32, @floatFromInt(point_count));11            const segment: usize = @intFromFloat(scaled);12            const local = scaled - @as(f32, @floatFromInt(segment));13            const p0 = self.points[(segment + point_count - 1) % point_count];14            const p1 = self.points[segment];15            const p2 = self.points[(segment + 1) % point_count];16            const p3 = self.points[(segment + 2) % point_count];17            const local2 = local * local;18            const local3 = local2 * local;19            var result: [dimension]f32 = undefined;20            for (0..dimension) |axis| {21                result[axis] = 0.5 * (2.0 * p1[axis] +22                    (-p0[axis] + p2[axis]) * local +23                    (2.0 * p0[axis] - 5.0 * p1[axis] + 4.0 * p2[axis] - p3[axis]) * local2 +24                    (-p0[axis] + 3.0 * p1[axis] - 3.0 * p2[axis] + p3[axis]) * local3);25            }26            return result;27        }28    };29}

1pub fn angleSlerp(a: f32, b: f32, t: f32) f32 {2    const two_pi: f32 = 2.0 * math.pi;3    var diff = @mod(b - a, two_pi);4    if (diff > math.pi) {5        diff -= two_pi;6    }7    return a + diff * t;8}

1pub fn scalarLerp(a: f32, b: f32, t: f32) f32 {2    return a + (b - a) * t;3}

1pub fn vec3Lerp(a: [3]f32, b: [3]f32, t: f32) [3]f32 {2    return .{3        a[0] + (b[0] - a[0]) * t,4        a[1] + (b[1] - a[1]) * t,5        a[2] + (b[2] - a[2]) * t,6    };7}

1//! Parameter curves: clips of plain values that drive shape and material2//! parameters, with a mixer, a state machine, a blend space and notify3//! tracks over them. Joint poses are `rig.JointClip`'s; these clips carry4//! no joints.56const machine = @import("machine.zig");7const mixer = @import("mixer.zig");8const parameter = @import("parameter.zig");9const space = @import("space.zig");10const spline = @import("spline.zig");1112pub const scalarLerp = spline.scalarLerp;13pub const angleSlerp = spline.angleSlerp;14pub const vec3Lerp = spline.vec3Lerp;15pub const PeriodicSpline = spline.PeriodicSpline;16pub const CubicHermiteSegment = spline.CubicHermiteSegment;17pub const CatmullRomSpline = spline.CatmullRomSpline;18pub const SlotCurve = parameter.SlotCurve;19pub const ParameterClip = parameter.ParameterClip;20pub const SlotBlendMode = mixer.SlotBlendMode;21pub const inferBlendMode = mixer.inferBlendMode;22pub const MixerLayer = mixer.MixerLayer;23pub const ParameterMixer = mixer.ParameterMixer;24pub const ConditionFn = machine.ConditionFn;25pub const Transition = machine.Transition;26pub const ParameterState = machine.ParameterState;27pub const ParameterMachine = machine.ParameterMachine;28pub const BlendSample = space.BlendSample;29pub const BlendSpace1D = space.BlendSpace1D;30pub const NotifyEvent = space.NotifyEvent;31pub const NotifyTrack = space.NotifyTrack;

1pub const curve = @import("curve/root.zig");