reflow_components 0.2.0

Standard component catalog for Reflow — procedural, media, GPU, animation, I/O, and stream actors.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170

//! CPU skinning actor — linear blend skinning.
//!
//! Caches mesh, skin descriptor, and weights in state on first receipt.
//! Fires on every `bone_transforms` input once static data is cached.
//! Outputs deformed mesh in standard 24-byte stride (pos3+normal3).

use crate::{Actor, ActorBehavior, Message, Port};
use anyhow::{Error, Result};
use reflow_actor::{message::EncodableValue, ActorContext};
use reflow_actor_macro::actor;
use serde_json::{json, Value};
use std::collections::HashMap;

#[actor(
    SkinningActor,
    inports::<10>(mesh, skinned_mesh, bone_transforms, skin),
    outports::<1>(deformed_mesh, metadata),
    state(MemoryState),
    await_inports(bone_transforms)
)]
pub async fn skinning_actor(ctx: ActorContext) -> Result<HashMap<String, Message>, Error> {
    let payload = ctx.get_payload();
    let config = ctx.get_config_hashmap();

    let stride = config.get("stride").and_then(|v| v.as_u64()).unwrap_or(24) as usize;

    // Cache static inputs on first receipt
    if let Some(Message::Bytes(b)) = payload.get("mesh") {
        ctx.pool_upsert("_cache", "mesh_b64", json!(b64_encode(&b)));
    }
    if let Some(Message::Bytes(b)) = payload.get("skinned_mesh") {
        ctx.pool_upsert("_cache", "weights_b64", json!(b64_encode(&b)));
    }
    if let Some(Message::Object(obj)) = payload.get("skin") {
        let v: Value = obj.as_ref().clone().into();
        ctx.pool_upsert("_cache", "skin", v);
    }

    // bone_transforms is the per-frame trigger (guaranteed present via await_inports)
    let bone_bytes = match payload.get("bone_transforms") {
        Some(Message::Bytes(b)) => b.to_vec(),
        _ => unreachable!("await_inports guarantees bone_transforms"),
    };

    // Retrieve cached data (mesh + skinned_mesh arrive once, cached in pool)
    let cache: HashMap<String, Value> = ctx.get_pool("_cache").into_iter().collect();

    let mesh_bytes = match cache.get("mesh_b64").and_then(|v| v.as_str()) {
        Some(s) => b64_decode(s),
        None => return Ok(HashMap::new()), // Not arrived yet
    };
    let skin_bytes = match cache.get("weights_b64").and_then(|v| v.as_str()) {
        Some(s) => b64_decode(s),
        None => return Ok(HashMap::new()), // Not arrived yet
    };
    let skin_info = cache
        .get("skin")
        .cloned()
        .unwrap_or(json!({"maxInfluences": 4}));

    let vertex_count = mesh_bytes.len() / stride;
    let max_influences = skin_info
        .get("maxInfluences")
        .and_then(|v| v.as_u64())
        .unwrap_or(4) as usize;
    let bone_count = bone_bytes.len() / 64;

    // Parse bone matrices (safe LE decode into aligned arrays)
    let mut bone_matrices: Vec<[f32; 16]> = Vec::with_capacity(bone_count);
    for i in 0..bone_count {
        let off = i * 64;
        let mut m = [0.0f32; 16];
        for j in 0..16 {
            m[j] = f32::from_le_bytes(bone_bytes[off + j * 4..off + j * 4 + 4].try_into().unwrap());
        }
        bone_matrices.push(m);
    }

    let entry_size = 6; // u16 + f32
    let weights_per_vertex = max_influences * entry_size;

    // Pre-allocate output (single alloc, no per-vertex extend_from_slice)
    let mut output = vec![0u8; vertex_count * stride];

    for i in 0..vertex_count {
        let mesh_off = i * stride;
        let skin_off = i * weights_per_vertex;

        let px = f32::from_le_bytes(mesh_bytes[mesh_off..mesh_off + 4].try_into().unwrap());
        let py = f32::from_le_bytes(mesh_bytes[mesh_off + 4..mesh_off + 8].try_into().unwrap());
        let pz = f32::from_le_bytes(mesh_bytes[mesh_off + 8..mesh_off + 12].try_into().unwrap());
        let nx = f32::from_le_bytes(mesh_bytes[mesh_off + 12..mesh_off + 16].try_into().unwrap());
        let ny = f32::from_le_bytes(mesh_bytes[mesh_off + 16..mesh_off + 20].try_into().unwrap());
        let nz = f32::from_le_bytes(mesh_bytes[mesh_off + 20..mesh_off + 24].try_into().unwrap());

        // Blend bone matrices (unrolled for auto-vectorization)
        let mut blended = [0.0f32; 16];
        let mut total_weight = 0.0f32;
        for j in 0..max_influences {
            let w_off = skin_off + j * entry_size;
            if w_off + entry_size > skin_bytes.len() {
                break;
            }
            let bone_idx =
                u16::from_le_bytes(skin_bytes[w_off..w_off + 2].try_into().unwrap()) as usize;
            let weight = f32::from_le_bytes(skin_bytes[w_off + 2..w_off + 6].try_into().unwrap());
            if weight < 1e-6 || bone_idx >= bone_count {
                continue;
            }
            let m = &bone_matrices[bone_idx];
            for k in 0..16 {
                blended[k] += m[k] * weight;
            }
            total_weight += weight;
        }

        if total_weight < 1e-6 {
            blended = super::math_helpers::MAT4_IDENTITY;
        }

        // Inline transform (avoids function call overhead)
        let npx = blended[0] * px + blended[4] * py + blended[8] * pz + blended[12];
        let npy = blended[1] * px + blended[5] * py + blended[9] * pz + blended[13];
        let npz = blended[2] * px + blended[6] * py + blended[10] * pz + blended[14];
        let tnx = blended[0] * nx + blended[4] * ny + blended[8] * nz;
        let tny = blended[1] * nx + blended[5] * ny + blended[9] * nz;
        let tnz = blended[2] * nx + blended[6] * ny + blended[10] * nz;
        let nlen = (tnx * tnx + tny * tny + tnz * tnz).sqrt().max(1e-8);

        // Write to pre-allocated output (indexed, not extend_from_slice)
        let out_off = i * stride;
        output[out_off..out_off + 4].copy_from_slice(&npx.to_le_bytes());
        output[out_off + 4..out_off + 8].copy_from_slice(&npy.to_le_bytes());
        output[out_off + 8..out_off + 12].copy_from_slice(&npz.to_le_bytes());
        output[out_off + 12..out_off + 16].copy_from_slice(&(tnx / nlen).to_le_bytes());
        output[out_off + 16..out_off + 20].copy_from_slice(&(tny / nlen).to_le_bytes());
        output[out_off + 20..out_off + 24].copy_from_slice(&(tnz / nlen).to_le_bytes());

        // Pass through extra bytes (UV, color, etc.)
        if stride > 24 && mesh_off + stride <= mesh_bytes.len() {
            output[out_off + 24..out_off + stride]
                .copy_from_slice(&mesh_bytes[mesh_off + 24..mesh_off + stride]);
        }
    }

    let mut out = HashMap::new();
    out.insert("deformed_mesh".to_string(), Message::bytes(output));
    out.insert(
        "metadata".to_string(),
        Message::object(EncodableValue::from(json!({
            "vertexCount": vertex_count,
            "boneCount": bone_count,
            "stride": stride,
            "format": if stride > 24 { "pos3_normal3_color3_f32" } else { "pos3_normal3_f32" },
        }))),
    );
    Ok(out)
}

fn b64_encode(data: &[u8]) -> String {
    use base64::Engine;
    base64::engine::general_purpose::STANDARD.encode(data)
}

fn b64_decode(s: &str) -> Vec<u8> {
    use base64::Engine;
    base64::engine::general_purpose::STANDARD
        .decode(s)
        .unwrap_or_default()
}