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
//! A physically-based path tracer, beside the rasteriser rather than inside it.
//!
//! [`Renderer`](crate::renderer::Renderer) draws a scene the way a GPU
//! pipeline does: project the triangles, shade each fragment from a fixed set
//! of lights, and approximate everything else — shadows with a depth map,
//! reflections by marching the screen, ambient occlusion from the depth buffer.
//! Those approximations are what make it run at 60 fps and what make it wrong
//! in specific, familiar ways: light does not bounce, a mirror cannot show what
//! is behind the camera, and a glass ball does not bend the room.
//!
//! This module answers the same question by simulating light transport
//! directly. Rays leave the camera, scatter off surfaces according to their
//! BSDF, and either find a light or die trying; the image is the average of
//! millions of such paths. Global illumination, soft shadows, glossy
//! interreflection, refraction with optional RGB dispersion, and depth of
//! field all fall out of that rather than being features — they are what the
//! integral says. The cost is time: a frame is seconds to minutes, not
//! milliseconds.
//!
//! # Quick start
//!
//! ```no_run
//! use threers::raytrace::{RaytraceRenderer, RaytraceSettings};
//! # use threers::{Scene, PerspectiveCamera};
//! # let mut scene = Scene::new();
//! # let camera = PerspectiveCamera::new(50.0, 1.0, 0.1, 100.0);
//! let mut renderer = RaytraceRenderer::new(800, 600);
//! renderer.set_settings(RaytraceSettings::default().with_samples(128));
//! let rgba = renderer.render_to_rgba(&mut scene, &camera);
//! std::fs::write("out.png", threers::encode_png(800, 600, &rgba)).unwrap();
//! ```
//!
//! The scene is an ordinary [`Scene`](crate::Scene) — the same one the raster
//! renderer takes, with the same [`Material`](crate::materials::Material)s and
//! [`Light`](crate::lights::Light)s. Nothing needs to be authored twice.
//!
//! # Progressive rendering
//!
//! Prepare once, then add samples in batches and resolve whenever you want to
//! show progress:
//!
//! ```no_run
//! # use threers::raytrace::RaytraceRenderer;
//! # use threers::{Scene, PerspectiveCamera};
//! # let mut scene = Scene::new();
//! # let camera = PerspectiveCamera::new(50.0, 1.0, 0.1, 100.0);
//! let mut renderer = RaytraceRenderer::new(800, 600);
//! renderer.prepare(&mut scene, &camera);
//! for _ in 0..20 {
//! renderer.accumulate(8).unwrap();
//! let preview = renderer.resolve_rgba(); // refines each time
//! # let _ = preview;
//! }
//! ```
//!
//! # Backends
//!
//! [`CpuBackend`] is the reference: portable, `wasm32` included, and the
//! definition of correct for everything here. [`crate::raytrace::gpu::GpuBackend`] runs the same
//! integrator as a wgpu compute kernel over the same
//! [`RaytraceScene`] — typically one to two orders of magnitude faster on a
//! discrete GPU. Both implement [`RaytraceBackend`], so switching is one line:
//!
//! ```text
//! use threers::raytrace::{gpu::GpuBackend, RaytraceRenderer};
//! let backend = GpuBackend::headless().expect("no GPU");
//! let mut renderer = RaytraceRenderer::with_backend(800, 600, Box::new(backend));
//! ```
//!
//! # What is and is not simulated
//!
//! Simulated: multi-bounce diffuse and glossy global illumination; the
//! principled BSDF (Lambert + anisotropic GGX + rough dielectric transmission +
//! clearcoat + Charlie sheen + thin-film iridescence + RGB dispersion in
//! transmission + grazing subsurface boost) with Kulla–Conty energy compensation;
//! emissive geometry as area lights; `Directional`/`Point`/`Spot`/`RectArea`
//! lights (with layer masks), soft shadows; `Ambient` and `Hemisphere` lights;
//! `scene.environment` as image-based lighting; `scene.fog` as a participating
//! medium along camera rays; alpha cutouts; Beer–Lambert absorption inside
//! transmissive solids; displacement maps at build time; lines/points/sprites
//! thin-lens camera with optional motion blur (CPU and GPU); progressive film
//! checkpointing and EXR export; tile/region accumulation for viewports with
//! noise-priority scheduling, soft time budgets, adaptive early stop, and
//! deferred GPU readback (one full sync at resolve instead of per-tile copies).
//! [`gpu::GpuCaps`] validates storage-buffer, uniform, texture, and film
//! sizes against wgpu limits (downlevel/WebGL2, shared raster devices, and
//! native Metal/Vulkan/CUDA stacks all differ).
//! Per-pixel variance for adaptive sampling and denoising uses Welford `M₂`
//! with firefly-capped updates (CPU and GPU). The À-Trous filter compares
//! neighbours in log-luminance, blends output with log-lum + linear-chroma, and
//! weights by measured variance and sample counts.
//!
//! Not simulated: full spectral rendering, bidirectional caustics (optional
//! `caustic_glass_shadows` is a biased approximation on CPU and GPU), and a
//! native Metal compute backend separate from wgpu. Subsurface uses a short
//! random walk plus the grazing boost in the BSDF, not a full volumetric
//! BSSRDF. CPU and GPU still differ in per-pixel noise at low spp but converge
//! to the same mean. Sample redistribution pools the batch budget within each
//! 8×8 workgroup on the GPU (CPU does it per row/chunk).
//!
//! Materials with no physical reading — `MeshNormalMaterial`,
//! `MeshToonMaterial`, `ShaderMaterial` and friends — are mapped to the nearest
//! surface that does have one, and each choice is recorded in
//! [`crate::raytrace::BuildReport::approximated`] rather than made silently.
pub use ;
pub use ;
pub use ;
pub use RtCamera;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use SceneFingerprint;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;