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
//! [RLX](https://crates.io/crates/rlx) — an ML compiler and runtime — as a
//! neighbour of the renderer.
//!
//! Nothing here changes how threers draws. The bridge is data conversion in
//! both directions and a thin wrapper around compiling a graph: vertex
//! attributes and pixels become tensors of a declared shape, tensors become
//! attributes and textures, and [`crate::rlx::GraphRunner`] compiles once so a per-frame
//! filter does not pay for the compiler sixty times a second.
//!
//! Two flags, two independent subjects:
//!
//! | Feature | Module | What it adds | Crate |
//! |---------|--------|--------------|-------|
//! | `rlx` | this one | Tensors ↔ geometry and pixels, [`crate::rlx::GraphRunner`], [`crate::rlx::FrameFilter`] | [`rlx`](https://crates.io/crates/rlx) |
//! | `rlx-geo` | [`crate::rlx::geo`] | Exact Delaunay + discrete Voronoi as geometry and textures | [`rlx-geo`](https://crates.io/crates/rlx-geo) |
//!
//! `rlx-geo` does *not* imply `rlx`: it is that crate's pure-geometry layer,
//! which needs no part of the graph runtime to do its job.
//!
//! # What is here
//!
//! The bridge itself is [`crate::rlx::Tensor`] and the conversions around it, plus
//! [`crate::rlx::GraphRunner`] and [`crate::rlx::FrameFilter`] for running a graph you wrote. On top
//! of those sit the things worth having pre-built:
//!
//! | | | |
//! |---|---|---|
//! | [`crate::rlx::ConvFilter`], [`crate::rlx::Kernel3x3`] | blur, sharpen, Sobel, emboss over a frame | `rlx` |
//! | [`crate::rlx::Diffusion`] | iterated `h ← h + κ∇²h` over a height grid | `rlx` |
//! | [`crate::rlx::mesh::laplacian_smooth`], [`crate::rlx::mesh::taubin_smooth`] | smoothing as a graph over `[n, 3]` positions | `rlx` |
//! | [`crate::rlx::ColorGrade`] | a colour transform *fitted* to a reference by autodiff | `rlx` |
//! | [`crate::rlx::Palette`] | k-means over pixels, assignment on the device | `rlx` |
//! | [`crate::rlx::geo::heightfield_geometry`], [`crate::rlx::geo::refine_heightfield`] | scattered samples → mesh, and where to sample next | `rlx-geo` |
//! | [`crate::rlx::geo::voronoi_labels`], [`crate::rlx::geo::voronoi_wall_distance`], [`crate::rlx::geo::normal_map_from_height`] | cell textures and the maps built from them | `rlx-geo` |
//!
//! Every one of these compiles for wasm32 as well as native, and `RLX=1
//! web/build.sh` (plus `RLX_GEO=1`) exports them to JavaScript as
//! `rlxConvolve`, `rlxSmoothMesh`, `rlxFitGrade`, `geoHeightfield` and the
//! rest. Nothing in this module needs a filesystem, a thread or a clock; the
//! examples that drive it do — they render headlessly and write PNGs — which
//! is why they are examples and this is a module.
//!
//! # Running a graph over a frame
//!
//! ```no_run
//! use threers::cameras::PerspectiveCamera;
//! use threers::renderer::HeadlessRenderer;
//! use threers::rlx::{preferred_device, FrameFilter};
//! use threers::Scene;
//! # fn my_graph() -> ::rlx::Graph { unimplemented!() }
//!
//! let mut headless = HeadlessRenderer::builder().size(256, 256).build().unwrap();
//! let mut scene = Scene::new();
//! let camera = PerspectiveCamera::new(50.0, 1.0, 0.1, 100.0);
//!
//! let frame = headless.render_to_rgba(&mut scene, &camera);
//! let mut filter = FrameFilter::new(my_graph(), preferred_device(), "frame");
//! let denoised = filter.apply_to_texture(&frame, 256, 256).unwrap();
//! ```
//!
//! # Building a graph
//!
//! The rlx API needed to build one is re-exported here, so a dependent does
//! not have to name a second copy of rlx in its own manifest and keep the two
//! versions in step:
//!
//! ```
//! use threers::rlx::prelude::*;
//! use threers::rlx::{preferred_device, GraphRunner, Tensor};
//!
//! let mut g = Graph::new("scale");
//! let x = g.input("x", Shape::new(&[1, 4], DType::F32));
//! let two = g.constant(2.0, DType::F32);
//! let y = g.mul(x, two);
//! g.set_outputs(vec![y]);
//!
//! let mut runner = GraphRunner::new(g, preferred_device());
//! let input = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[1, 4]).unwrap();
//! let out = runner.run(&[("x", &input)]);
//! assert_eq!(out[0].data(), &[2.0, 4.0, 6.0, 8.0]);
//! assert_eq!(out[0].dims(), &[1, 4]);
//! ```
//!
//! # Devices
//!
//! On native the dependency carries rlx's `cpu`, `tensor` and `gpu` backends.
//! rlx's `gpu` is its own wgpu, a different major version than the renderer's:
//! a graph running there has its own device, its own queue and its own copy of
//! the data. Tensors cross between the two through host memory, which is what
//! the conversions in this module do.
//!
//! **[`crate::rlx::preferred_device`] returns the CPU**, and the table in its
//! documentation is why: at the sizes this bridge works on, the GPU loses
//! every operation here — by 60× on the iterative fit, which is four hundred
//! dependent round trips. Convolution crosses over around four megapixels;
//! pass [`crate::rlx::Device::Gpu`] explicitly above that. The GPU that matters for a
//! renderer is the one drawing the frame, and this module deliberately leaves
//! it alone.
//!
//! **On wasm32 the `gpu` backend is left out, and the browser gets rlx's CPU
//! backend.** Not a policy choice — two wgpu majors in one wasm binary both
//! generate `#[wasm_bindgen]` bindings for the same WebGPU interfaces, and
//! `wasm-bindgen` rejects the result ("duplicate string enums:
//! `GpuAutoLayoutMode`"). The Rust compiles; the bindgen step is what fails, so
//! a browser build with both would produce no payload at all. The renderer
//! keeps WebGPU, rlx gets the CPU, and `rlxDevices()` reports what a page
//! actually has rather than what it hoped for.
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
// ── The rlx API, re-exported ────────────────────────────────────────────
//
// Enough of rlx to build, compile, run and differentiate a graph without a
// second dependency edge. What is not here is what this build of rlx does not
// have: GGUF, ONNX, FPGA export and the rest sit behind rlx features threers
// does not enable, and a caller who wants them wants their own `rlx`
// dependency with those flags on.
/// Star-import for graph building — `Graph`, `Shape`, `DType`, `Session`,
/// `Device`, the tensor DSL, autodiff and the compile options.
pub use prelude;
/// `grad`, `jvp`, `hvp`, `vmap` and the higher-order helpers.
pub use autodiff;
/// `CompileOptions`, `Precision`, fusion policy.
pub use compile;
/// The `Device` enum and the backend registries.
pub use driver;
/// Tensor IR: ops, shapes, the graph builder.
pub use ir;
/// The op-builder enums: activations, binary ops, reductions, interpolation.
pub use ops;
/// Graph rewrites, autodiff, `vmap`.
pub use opt;
/// Quantisation metadata carried by the IR.
pub use quant;
/// `Session`, `CompiledGraph`, device discovery.
pub use runtime;
/// The types most call sites touch, without the star import.
pub use ;
/// The sRGB transfer function and its inverse, in the piecewise form wgpu's
/// `*UnormSrgb` sampling uses — so a texture that round-trips through this
/// module samples the same as it did before.
///
/// Shared by every submodule here rather than per-file, because a bridge whose
/// two halves disagree about the encoding is a bridge that quietly changes
/// every colour that crosses it.
// Only the tensor conversions decode; `geo` produces colour and never reads it
// back.