threers 0.0.4

Drop-in three.js replacement for Rust and WebAssembly (wgpu) — THREE.* API, scene graph, PBR, post-fx, mesh BVH, CSG, an OpenSCAD front end with a watertight exact-CSG kernel, headless render, and native media codecs
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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
// threers — Metal Shading Language backend.
//
// One uber-shader over the material kinds the backend supports, compiled at
// startup by `MetalDevice::new`. The layouts below are ABI: every struct here
// has a `#[repr(C)]` twin in `renderer.rs`, and `tests/metal_backend.rs` checks
// the sizes agree. Keep all members 16-byte aligned (float4 / float4x4 / uint4)
// so the two layouts cannot drift apart on padding.
//
// Conventions match the wgpu backend so a scene renders the same on either:
//   - clip space z in [0, 1]; counter-clockwise front faces
//   - directional `direction` is the direction light *travels*, so L = -direction
//   - light colours arrive premultiplied by intensity
//   - punctual attenuation follows three.js `getDistanceAttenuation`
//   - UVs are top-left origin; `Texture::flip_y` is applied on the CPU at upload

#include <metal_stdlib>
using namespace metal;

// ---------------------------------------------------------------- vertex data

// 48 bytes. `packed_float3` so the layout is exactly the Rust `Vertex`.
struct Vertex {
    packed_float3 position;
    packed_float3 normal;
    float2        uv;
    packed_float3 color;
    float         _pad;
};

// ------------------------------------------------------------------ uniforms

struct DirLight {
    float4 direction;   // xyz = direction of travel
    float4 color;       // rgb premultiplied by intensity
};

struct PointLight {
    float4 position;
    float4 color;
    float4 params;      // x = cutoff distance (0 = none), y = decay
};

struct SpotLight {
    float4 position;
    float4 direction;
    float4 color;
    float4 params;      // x = distance, y = decay, z = cos(outer), w = cos(inner)
};

struct HemiLight {
    float4 sky;
    float4 ground;
    float4 up;
};

// Per-view state. One view is a plain camera; two are the eyes of a headset,
// and the vertex stage picks between them from the instance id.
constant uint MAX_VIEWS = 2u;

struct Frame {
    float4x4   view_proj[MAX_VIEWS];
    float4x4   view[MAX_VIEWS];
    float4     camera_pos[MAX_VIEWS];
    float4     ambient;
    float4     fog_color;   // rgb, w = mode (0 off, 1 linear, 2 exp2)
    float4     fog_params;  // near, far, density
    float4     viewport;    // width, height, 1/width, 1/height
    uint4      counts;      // dir, point, spot, hemi
    uint4      view_info;   // view count, then unused
    DirLight   dir[4];
    PointLight pts[8];
    SpotLight  spots[4];
    HemiLight  hemis[2];
};

struct Draw {
    float4x4 model;
    float4x4 normal_mat;
    float4   base_color;   // rgb, a = opacity
    float4   emissive;     // rgb
    float4   specular;     // rgb, w = shininess
    float4   pbr;          // roughness, metalness, alpha_test, toon steps
    float4   uv_transform; // offset.xy, repeat.xy
    float4   misc;         // uv rotation, point size, depth near, depth far
    uint4    flags;        // kind, has_map, has_vertex_color, instanced
};

// Material kinds — `crate::materials::MaterialKind` values, not renumberable.
constant uint KIND_BASIC      = 0u;
constant uint KIND_LAMBERT    = 1u;
constant uint KIND_PHONG      = 2u;
constant uint KIND_STANDARD   = 3u;
constant uint KIND_PHYSICAL   = 4u;
constant uint KIND_NORMAL     = 5u;
constant uint KIND_DEPTH      = 6u;
constant uint KIND_TOON       = 7u;
constant uint KIND_MATCAP     = 8u;
constant uint KIND_DISTANCE   = 12u;

// The interpolants, shared by the single-view and layered outputs. A macro
// because Metal has no struct inheritance and the fragment stage matches its
// inputs to the vertex outputs by declaration order — the two lists have to
// stay identical, and this is the only way to make that structural rather than
// a comment asking future edits to remember.
#define VOUT_INTERPOLANTS                                                      \
    float4 position [[position]];                                              \
    float3 world_pos;                                                          \
    float3 normal;                                                             \
    float2 uv;                                                                 \
    float3 color;                                                              \
    float  view_dist;                                                          \
    /* Which eye this vertex belongs to; the fragment stage needs it for the */ \
    /* view vector. Flat because it is an index, not a quantity.             */ \
    uint   view_index [[flat]];

/// What the fragment stage receives — the interpolants and nothing else. The
/// builtins below are vertex outputs only.
struct FIn {
    VOUT_INTERPOLANTS
};

/// Single-view output. `point_size` is harmless for triangles here because a
/// pipeline that names no topology class may write it.
struct VOut {
    VOUT_INTERPOLANTS
    float point_size [[point_size]];
};

// Layered outputs carry the array slice to render into. They are separate
// structs for two reasons Metal enforces: a pipeline whose vertex function
// writes `render_target_array_index` must declare its topology class, and a
// pipeline that declares `triangle` must then *not* write `point_size`.
struct VOutLayered {
    VOUT_INTERPOLANTS
    uint layer [[render_target_array_index]];
};

struct VOutLayeredPoint {
    VOUT_INTERPOLANTS
    float point_size [[point_size]];
    uint  layer [[render_target_array_index]];
};

#define COPY_INTERPOLANTS(out, v)                                              \
    out.position = v.position;                                                 \
    out.world_pos = v.world_pos;                                               \
    out.normal = v.normal;                                                     \
    out.uv = v.uv;                                                             \
    out.color = v.color;                                                       \
    out.view_dist = v.view_dist;                                               \
    out.view_index = v.view_index;                                             \
    out.layer = v.view_index; /* one eye per slice */

static inline VOutLayered to_layered(VOut v) {
    VOutLayered out;
    COPY_INTERPOLANTS(out, v)
    return out;
}

static inline VOutLayeredPoint to_layered_point(VOut v) {
    VOutLayeredPoint out;
    COPY_INTERPOLANTS(out, v)
    out.point_size = v.point_size;
    return out;
}

// --------------------------------------------------------------------- vertex

static inline float2 apply_uv_transform(float2 uv, float4 xform, float rotation) {
    float2 t = uv * xform.zw + xform.xy;
    if (rotation != 0.0) {
        float s = sin(rotation);
        float c = cos(rotation);
        float2 p = t - float2(0.5);
        t = float2(p.x * c - p.y * s, p.x * s + p.y * c) + float2(0.5);
    }
    return t;
}

static inline float4x4 model_matrix(constant Draw &draw,
                                    device const float4x4 *instances,
                                    uint iid) {
    // Only pay for the instance multiply when there is an instance to apply;
    // a 4x4 product per vertex is not free at scene scale.
    return draw.flags.w == 1u ? draw.model * instances[iid] : draw.model;
}

static inline VOut transform(Vertex v,
                             float4x4 model,
                             float3x3 nrm,
                             constant Frame &frame,
                             constant Draw &draw,
                             uint view_index) {
    VOut out;
    float4 world = model * float4(float3(v.position), 1.0);
    out.position = frame.view_proj[view_index] * world;
    out.world_pos = world.xyz;
    out.normal = nrm * float3(v.normal);
    out.uv = apply_uv_transform(v.uv, draw.uv_transform, draw.misc.x);
    out.color = draw.flags.z == 1u ? float3(v.color) : float3(1.0);
    out.view_dist = length(frame.camera_pos[view_index].xyz - world.xyz);
    out.point_size = 1.0;
    out.view_index = view_index;
    return out;
}

static inline float3x3 normal_basis(constant Draw &draw, float4x4 model) {
    if (draw.flags.w == 1u) {
        // Instanced: the per-instance matrix is not known on the CPU side of
        // the uniform, so use the composed model's upper 3x3. Correct for
        // rigid and uniformly scaled instances; non-uniform instance scale
        // skews normals (documented in `MetalRenderer`).
        return float3x3(model[0].xyz, model[1].xyz, model[2].xyz);
    }
    return float3x3(draw.normal_mat[0].xyz,
                    draw.normal_mat[1].xyz,
                    draw.normal_mat[2].xyz);
}

static inline VOut point_size_for(VOut out, constant Frame &frame, constant Draw &draw) {
    float size = draw.misc.y;
    if (draw.misc.z > 0.5) {
        // three.js size attenuation: gl_PointSize = size * (h/2) / -mvPosition.z
        float view_z =
            max(-(frame.view[out.view_index] * float4(out.world_pos, 1.0)).z, 1e-4);
        size *= (frame.viewport.y * 0.5) / view_z;
    }
    out.point_size = clamp(size, 1.0, 255.0);
    return out;
}

vertex VOut vs_mesh(uint vid [[vertex_id]],
                    uint iid [[instance_id]],
                    device const Vertex   *verts     [[buffer(0)]],
                    constant Frame        &frame     [[buffer(1)]],
                    constant Draw         &draw      [[buffer(2)]],
                    device const float4x4 *instances [[buffer(3)]]) {
    float4x4 model = model_matrix(draw, instances, iid);
    return transform(verts[vid], model, normal_basis(draw, model), frame, draw, 0u);
}

vertex VOut vs_point(uint vid [[vertex_id]],
                     uint iid [[instance_id]],
                     device const Vertex   *verts     [[buffer(0)]],
                     constant Frame        &frame     [[buffer(1)]],
                     constant Draw         &draw      [[buffer(2)]],
                     device const float4x4 *instances [[buffer(3)]]) {
    float4x4 model = model_matrix(draw, instances, iid);
    VOut out = transform(verts[vid], model, normal_basis(draw, model), frame, draw, 0u);
    return point_size_for(out, frame, draw);
}

// ------------------------------------------------------------ layered stereo
//
// Both eyes in one pass, into one texture array. The draw is issued with
// `instanceCount * view_count` instances and each vertex reads its eye out of
// the instance id, writing `render_target_array_index` to pick the slice — so a
// headset frame costs one traversal of the scene, not two.

static inline uint view_of(uint iid, constant Frame &frame) {
    return frame.view_info.x > 1u ? iid % frame.view_info.x : 0u;
}

static inline uint instance_of(uint iid, constant Frame &frame) {
    return frame.view_info.x > 1u ? iid / frame.view_info.x : iid;
}

vertex VOutLayered vs_mesh_layered(uint vid [[vertex_id]],
                                   uint iid [[instance_id]],
                                   device const Vertex   *verts     [[buffer(0)]],
                                   constant Frame        &frame     [[buffer(1)]],
                                   constant Draw         &draw      [[buffer(2)]],
                                   device const float4x4 *instances [[buffer(3)]]) {
    uint view = view_of(iid, frame);
    float4x4 model = model_matrix(draw, instances, instance_of(iid, frame));
    return to_layered(
        transform(verts[vid], model, normal_basis(draw, model), frame, draw, view));
}

vertex VOutLayeredPoint vs_point_layered(uint vid [[vertex_id]],
                                    uint iid [[instance_id]],
                                    device const Vertex   *verts     [[buffer(0)]],
                                    constant Frame        &frame     [[buffer(1)]],
                                    constant Draw         &draw      [[buffer(2)]],
                                    device const float4x4 *instances [[buffer(3)]]) {
    uint view = view_of(iid, frame);
    float4x4 model = model_matrix(draw, instances, instance_of(iid, frame));
    VOut out = transform(verts[vid], model, normal_basis(draw, model), frame, draw, view);
    return to_layered_point(point_size_for(out, frame, draw));
}

// ------------------------------------------------------------------- lighting

static inline float punctual_attenuation(float d, float max_d, float decay) {
    // three.js `getDistanceAttenuation`, matched to the wgpu backend.
    float att = 1.0 / max(pow(d, decay), 0.01);
    if (max_d > 0.0) {
        float t = clamp(1.0 - pow(d / max_d, 4.0), 0.0, 1.0);
        att *= t * t;
    }
    return att;
}

struct Surface {
    float3 n;
    float3 v;        // surface -> camera
    float3 albedo;
    float3 specular;
    float  shininess;
    float  roughness;
    float  metalness;
    uint   kind;
    float  toon_steps;
};

static inline float3 diffuse_term(Surface s, float ndl) {
    if (s.kind == KIND_TOON && s.toon_steps > 0.5) {
        float q = floor(ndl * s.toon_steps + 0.5) / s.toon_steps;
        return s.albedo * clamp(q, 0.0, 1.0);
    }
    return s.albedo * ndl;
}

// Blinn-Phong specular, for KIND_PHONG.
static inline float3 phong_specular(Surface s, float3 l, float ndl) {
    if (s.kind != KIND_PHONG || ndl <= 0.0) {
        return float3(0.0);
    }
    float3 h = normalize(l + s.v);
    float spec = pow(max(dot(s.n, h), 0.0), max(s.shininess, 1.0));
    return s.specular * spec;
}

// Cook-Torrance GGX, for KIND_STANDARD / KIND_PHYSICAL.
static inline float3 pbr_direct(Surface s, float3 l, float ndl) {
    float rough = clamp(s.roughness, 0.045, 1.0);
    float a = rough * rough;
    float3 h = normalize(l + s.v);
    float ndh = max(dot(s.n, h), 0.0);
    float ndv = max(dot(s.n, s.v), 1e-4);
    float vdh = max(dot(s.v, h), 1e-4);

    float a2 = a * a;
    float denom = ndh * ndh * (a2 - 1.0) + 1.0;
    float d = a2 / max(M_PI_F * denom * denom, 1e-7);

    float k = a * 0.5;
    float gv = ndv / (ndv * (1.0 - k) + k);
    float gl = ndl / (ndl * (1.0 - k) + k);
    float g = gv * gl;

    float3 f0 = mix(float3(0.04), s.albedo, s.metalness);
    float3 f = f0 + (float3(1.0) - f0) * pow(1.0 - vdh, 5.0);

    float3 spec = (d * g * f) / max(4.0 * ndv * ndl, 1e-4) * ndl;
    float3 kd = (float3(1.0) - f) * (1.0 - s.metalness);
    return kd * s.albedo * ndl + spec;
}

static inline float3 shade_one(Surface s, float3 l, float3 light_color, float attenuation) {
    float ndl = max(dot(s.n, l), 0.0);
    if (attenuation <= 0.0) {
        return float3(0.0);
    }
    float3 contrib;
    if (s.kind == KIND_STANDARD || s.kind == KIND_PHYSICAL) {
        contrib = pbr_direct(s, l, ndl);
    } else {
        contrib = diffuse_term(s, ndl) + phong_specular(s, l, ndl);
    }
    return contrib * light_color * attenuation;
}

static inline float3 shade(Surface s, float3 world_pos, constant Frame &frame) {
    float3 lit = s.albedo * frame.ambient.rgb;

    for (uint i = 0u; i < frame.counts.w && i < 2u; ++i) {
        HemiLight h = frame.hemis[i];
        float t = dot(s.n, normalize(h.up.xyz)) * 0.5 + 0.5;
        lit += s.albedo * mix(h.ground.rgb, h.sky.rgb, t);
    }
    for (uint i = 0u; i < frame.counts.x && i < 4u; ++i) {
        DirLight d = frame.dir[i];
        lit += shade_one(s, normalize(-d.direction.xyz), d.color.rgb, 1.0);
    }
    for (uint i = 0u; i < frame.counts.y && i < 8u; ++i) {
        PointLight p = frame.pts[i];
        float3 to_light = p.position.xyz - world_pos;
        float dist = length(to_light);
        lit += shade_one(s, to_light / max(dist, 1e-4), p.color.rgb,
                         punctual_attenuation(dist, p.params.x, p.params.y));
    }
    for (uint i = 0u; i < frame.counts.z && i < 4u; ++i) {
        SpotLight sp = frame.spots[i];
        float3 to_light_vec = sp.position.xyz - world_pos;
        float dist = length(to_light_vec);
        float3 to_light = to_light_vec / max(dist, 1e-4);
        float cos_angle = dot(-to_light, normalize(sp.direction.xyz));
        float cone = cos_angle > sp.params.z
                   ? smoothstep(sp.params.z, sp.params.w, cos_angle)
                   : 0.0;
        lit += shade_one(s, to_light, sp.color.rgb,
                         punctual_attenuation(dist, sp.params.x, sp.params.y) * cone);
    }
    return lit;
}

static inline float3 apply_fog(float3 color, float view_dist, constant Frame &frame) {
    uint mode = uint(frame.fog_color.w + 0.5);
    if (mode == 0u) {
        return color;
    }
    float f;
    if (mode == 2u) {
        float d = frame.fog_params.z * view_dist;
        f = 1.0 - exp(-d * d);
    } else {
        f = (view_dist - frame.fog_params.x) /
            max(frame.fog_params.y - frame.fog_params.x, 1e-4);
    }
    return mix(color, frame.fog_color.rgb, clamp(f, 0.0, 1.0));
}

// ------------------------------------------------------------------- fragment

static inline float4 sample_base(constant Draw &draw,
                                 texture2d<float> base_map,
                                 sampler samp,
                                 float2 uv) {
    float4 base = draw.base_color;
    if (draw.flags.y == 1u) {
        base *= base_map.sample(samp, uv);
    }
    return base;
}

fragment float4 fs_mesh(FIn in [[stage_in]],
                        bool front_facing [[front_facing]],
                        constant Frame   &frame    [[buffer(0)]],
                        constant Draw    &draw     [[buffer(1)]],
                        texture2d<float>  base_map [[texture(0)]],
                        sampler           samp     [[sampler(0)]]) {
    uint kind = draw.flags.x;
    float3 n = normalize(in.normal);
    if (!front_facing) {
        n = -n;   // double-sided lighting, as three.js does for BackSide/DoubleSide
    }

    if (kind == KIND_NORMAL) {
        return float4(n * 0.5 + 0.5, draw.base_color.a);
    }
    if (kind == KIND_DEPTH || kind == KIND_DISTANCE) {
        float near = draw.misc.z;
        float far = max(draw.misc.w, near + 1e-4);
        float d = clamp((in.view_dist - near) / (far - near), 0.0, 1.0);
        return float4(float3(1.0 - d), draw.base_color.a);
    }

    float4 base = sample_base(draw, base_map, samp, in.uv);
    base.rgb *= in.color;
    if (base.a < draw.pbr.z) {
        discard_fragment();
    }

    if (kind == KIND_MATCAP) {
        float3 view_n = normalize((frame.view[in.view_index] * float4(n, 0.0)).xyz);
        float2 muv = view_n.xy * 0.5 + 0.5;
        float3 matcap = draw.flags.y == 1u ? base_map.sample(samp, muv).rgb : float3(1.0);
        return float4(apply_fog(draw.base_color.rgb * matcap * in.color, in.view_dist, frame),
                      base.a);
    }

    bool lit_kind = kind == KIND_LAMBERT || kind == KIND_PHONG || kind == KIND_STANDARD
                 || kind == KIND_PHYSICAL || kind == KIND_TOON;
    float3 color;
    if (lit_kind) {
        Surface s;
        s.n = n;
        s.v = normalize(frame.camera_pos[in.view_index].xyz - in.world_pos);
        s.albedo = base.rgb;
        s.specular = draw.specular.rgb;
        s.shininess = draw.specular.w;
        s.roughness = draw.pbr.x;
        s.metalness = draw.pbr.y;
        s.kind = kind;
        s.toon_steps = draw.pbr.w;
        color = shade(s, in.world_pos, frame) + draw.emissive.rgb;
    } else {
        // Unlit: Basic, Line, Points, Sprite, Sky, Mirror, Shader, Atmosphere.
        color = base.rgb + draw.emissive.rgb;
    }

    return float4(apply_fog(color, in.view_dist, frame), base.a);
}

fragment float4 fs_point(FIn in [[stage_in]],
                         float2 point_coord [[point_coord]],
                         constant Frame   &frame    [[buffer(0)]],
                         constant Draw    &draw     [[buffer(1)]],
                         texture2d<float>  base_map [[texture(0)]],
                         sampler           samp     [[sampler(0)]]) {
    // three.js PointsMaterial samples its map with gl_PointCoord, not the
    // vertex UV — the point is a screen-space quad.
    float4 base = draw.base_color;
    if (draw.flags.y == 1u) {
        base *= base_map.sample(samp, point_coord);
    }
    base.rgb *= in.color;
    if (base.a < max(draw.pbr.z, 1e-4)) {
        discard_fragment();
    }
    return float4(apply_fog(base.rgb, in.view_dist, frame), base.a);
}