use std::collections::HashMap;
use std::sync::Arc;
use crate::core::{Layers, ObjectKind};
use crate::lights::Light;
use crate::materials::Material;
use crate::math::{Color, Matrix3, Matrix4, Vector2, Vector3};
use crate::scene::Scene;
use crate::textures::CubeTexture;
use super::bvh::RtBvh;
use super::distribution::EnvDistribution;
use super::sampler::{cosine_hemisphere, Onb};
use super::settings::{BackgroundMode, RaytraceSettings};
use super::texture::{CpuTexture, TextureCache};
#[derive(Debug, Clone)]
pub struct RtMaterial {
pub base_color: Vector3,
pub base_color_map: Option<Arc<CpuTexture>>,
pub opacity: f32,
pub alpha_test: f32,
pub roughness: f32,
pub roughness_map: Option<Arc<CpuTexture>>,
pub metallic: f32,
pub metallic_map: Option<Arc<CpuTexture>>,
pub emission: Vector3,
pub emissive_map: Option<Arc<CpuTexture>>,
pub normal_map: Option<Arc<CpuTexture>>,
pub normal_scale: Vector2,
pub transmission: f32,
pub ior: f32,
pub attenuation_color: Vector3,
pub attenuation_distance: f32,
pub clearcoat: f32,
pub clearcoat_roughness: f32,
pub specular_tint: Vector3,
pub anisotropy: f32,
pub anisotropy_rotation: f32,
pub unlit: bool,
}
impl Default for RtMaterial {
fn default() -> Self {
Self {
base_color: Vector3::new(1.0, 1.0, 1.0),
base_color_map: None,
opacity: 1.0,
alpha_test: 0.0,
roughness: 1.0,
roughness_map: None,
metallic: 0.0,
metallic_map: None,
emission: Vector3::ZERO,
emissive_map: None,
normal_map: None,
normal_scale: Vector2::new(1.0, 1.0),
transmission: 0.0,
ior: 1.5,
attenuation_color: Vector3::new(1.0, 1.0, 1.0),
attenuation_distance: 0.0,
clearcoat: 0.0,
clearcoat_roughness: 0.0,
specular_tint: Vector3::new(1.0, 1.0, 1.0),
anisotropy: 0.0,
anisotropy_rotation: 0.0,
unlit: false,
}
}
}
impl RtMaterial {
pub fn is_shadow_transparent(&self) -> bool {
self.opacity < 1.0
|| self.alpha_test > 0.0
|| self.transmission > 0.0
|| self
.base_color_map
.as_ref()
.is_some_and(|m| m.has_transparency())
}
pub fn is_emissive(&self) -> bool {
self.emission.x > 0.0 || self.emission.y > 0.0 || self.emission.z > 0.0
}
}
#[derive(Debug, Clone, Copy)]
pub enum RtLight {
Directional {
direction: Vector3,
radiance: Vector3,
angular_radius: f32,
},
Point {
position: Vector3,
intensity: Vector3,
radius: f32,
distance: f32,
decay: f32,
},
Spot {
position: Vector3,
direction: Vector3,
intensity: Vector3,
radius: f32,
distance: f32,
decay: f32,
cos_outer: f32,
cos_inner: f32,
},
Rect {
position: Vector3,
right: Vector3,
up: Vector3,
radiance: Vector3,
},
}
#[derive(Debug, Clone, Copy)]
pub struct RtHemisphere {
pub sky: Vector3,
pub ground: Vector3,
pub up: Vector3,
}
#[derive(Debug, Clone)]
pub struct World {
pub background: Vector3,
pub background_alpha: f32,
pub environment: Option<Arc<CubeTexture>>,
pub environment_intensity: f32,
pub ambient: Vector3,
pub hemispheres: Vec<RtHemisphere>,
pub mode: BackgroundMode,
env_faces: Option<Box<[CpuTexture; 6]>>,
env_distribution: Option<EnvDistribution>,
}
impl Default for World {
fn default() -> Self {
Self {
background: Vector3::ZERO,
background_alpha: 1.0,
environment: None,
environment_intensity: 1.0,
ambient: Vector3::ZERO,
hemispheres: Vec::new(),
mode: BackgroundMode::Color,
env_faces: None,
env_distribution: None,
}
}
}
impl World {
pub fn lighting_radiance(&self, dir: Vector3) -> Vector3 {
let mut l = self.ambient;
for h in &self.hemispheres {
let t = 0.5 * dir.dot(h.up) + 0.5;
l = l + h.ground.lerp(h.sky, t.clamp(0.0, 1.0));
}
if let Some(faces) = &self.env_faces {
l = l + sample_cube(faces, dir) * self.environment_intensity;
}
l
}
pub fn camera_radiance(&self, dir: Vector3) -> (Vector3, f32) {
match self.mode {
BackgroundMode::Transparent => (Vector3::ZERO, 0.0),
BackgroundMode::Environment => match &self.env_faces {
Some(faces) => (
sample_cube(faces, dir) * self.environment_intensity,
self.background_alpha,
),
None => (self.background, self.background_alpha),
},
BackgroundMode::Color => (self.background, self.background_alpha),
}
}
const ENV_STRATEGY: f32 = 0.5;
pub fn sample_direction(
&self,
normal: Vector3,
pick: f32,
u1: f32,
u2: f32,
) -> Option<(Vector3, f32)> {
let dir = match &self.env_distribution {
Some(d) if pick < Self::ENV_STRATEGY => d.sample(u1, u2).0,
_ => Onb::new(normal).to_world(cosine_hemisphere(u1, u2)),
};
let pdf = self.direction_pdf(normal, dir);
(pdf > 1e-9).then_some((dir, pdf))
}
pub fn direction_pdf(&self, normal: Vector3, dir: Vector3) -> f32 {
let cosine = (normal.dot(dir) / std::f32::consts::PI).max(0.0);
match &self.env_distribution {
Some(d) => Self::ENV_STRATEGY * d.pdf(dir) + (1.0 - Self::ENV_STRATEGY) * cosine,
None => cosine,
}
}
pub fn env_distribution(&self) -> Option<&EnvDistribution> {
self.env_distribution.as_ref()
}
pub fn has_environment(&self) -> bool {
self.env_faces.is_some()
}
pub fn env_faces(&self) -> Option<&[CpuTexture; 6]> {
self.env_faces.as_deref()
}
pub fn is_black(&self) -> bool {
self.env_faces.is_none()
&& self.hemispheres.is_empty()
&& self.ambient.x <= 0.0
&& self.ambient.y <= 0.0
&& self.ambient.z <= 0.0
}
}
#[derive(Debug, Clone, Copy)]
pub struct TriShading {
pub normals: [Vector3; 3],
pub uvs: [Vector2; 3],
pub material: u32,
}
#[derive(Debug, Clone, Copy)]
pub struct EmissiveTri {
pub triangle: u32,
pub area: f32,
pub cdf: f32,
}
#[derive(Debug, Clone, Default)]
pub struct EmissiveSet {
pub tris: Vec<EmissiveTri>,
slot_of: Vec<u32>,
total_weight: f32,
}
impl EmissiveSet {
pub fn is_empty(&self) -> bool {
self.tris.is_empty()
}
pub fn len(&self) -> usize {
self.tris.len()
}
pub fn sample(&self, u: f32) -> Option<(&EmissiveTri, f32)> {
if self.tris.is_empty() {
return None;
}
let i = self
.tris
.partition_point(|e| e.cdf <= u)
.min(self.tris.len() - 1);
let prev = if i == 0 { 0.0 } else { self.tris[i - 1].cdf };
let p = (self.tris[i].cdf - prev).max(1e-9);
Some((&self.tris[i], p))
}
pub fn probability_of(&self, tri: u32) -> f32 {
let slot = match self.slot_of.get(tri as usize) {
Some(&s) if s != u32::MAX => s as usize,
_ => return 0.0,
};
let prev = if slot == 0 {
0.0
} else {
self.tris[slot - 1].cdf
};
(self.tris[slot].cdf - prev).max(0.0)
}
pub fn total_weight(&self) -> f32 {
self.total_weight
}
pub fn slot_of(&self, triangle: u32) -> Option<u32> {
match self.slot_of.get(triangle as usize) {
Some(&s) if s != u32::MAX => Some(s),
_ => None,
}
}
pub fn slots(&self) -> &[u32] {
&self.slot_of
}
}
#[derive(Debug, Clone, Default)]
pub struct BuildReport {
pub triangles: usize,
pub meshes: usize,
pub materials: usize,
pub lights: usize,
pub emissive_triangles: usize,
pub textures_decoded: usize,
pub approximated: Vec<String>,
pub skipped: Vec<String>,
}
impl BuildReport {
pub fn summary(&self) -> String {
format!(
"{} triangles from {} meshes, {} materials, {} lights, {} emissive triangles, {} textures",
self.triangles,
self.meshes,
self.materials,
self.lights,
self.emissive_triangles,
self.textures_decoded,
)
}
}
#[derive(Debug, Clone, Default)]
pub struct RaytraceScene {
pub tris: Vec<[Vector3; 3]>,
pub shading: Vec<TriShading>,
pub materials: Vec<RtMaterial>,
pub lights: Vec<RtLight>,
pub emissive: EmissiveSet,
pub world: World,
pub bvh: RtBvh,
pub report: BuildReport,
pub(crate) shadows_all_opaque: bool,
}
impl RaytraceScene {
pub fn build(scene: &mut Scene, settings: &RaytraceSettings) -> Self {
Self::build_for_layers(scene, settings, {
let mut l = Layers::default();
l.enable_all();
l
})
}
pub fn build_for_layers(
scene: &mut Scene,
settings: &RaytraceSettings,
layers: Layers,
) -> Self {
scene
.arena
.update_world_matrices(scene.root, Matrix4::identity());
let mut out = RaytraceScene {
world: World {
background: v3(scene.background),
background_alpha: scene.background_alpha,
environment: scene.environment.clone(),
environment_intensity: settings.environment_intensity,
ambient: Vector3::ZERO,
hemispheres: Vec::new(),
mode: settings.background,
env_faces: None,
env_distribution: None,
},
..Default::default()
};
let mut cache = TextureCache::new();
let mut material_slots: HashMap<usize, u32> = HashMap::new();
let mut collected: Vec<(Arc<crate::core::BufferGeometry>, Matrix4, Arc<Material>)> =
Vec::new();
let root = scene.root;
scene.arena.traverse_visible(root, &mut |_id, obj| {
if !layers.test(&obj.layers) {
return;
}
match &obj.kind {
ObjectKind::Mesh(mesh) => {
collected.push((
mesh.geometry.clone(),
obj.matrix_world,
mesh.material.clone(),
));
}
ObjectKind::SkinnedMesh(sm) => {
match skin_geometry(&sm.geometry, &sm.skeleton) {
Some(geom) => {
collected.push((Arc::new(geom), obj.matrix_world, sm.material.clone()))
}
None => out.report.skipped.push(format!(
"skinned mesh '{}': missing joint/weight attributes",
obj.name
)),
}
}
ObjectKind::InstancedMesh(im) => {
for t in &im.transforms {
collected.push((
im.geometry.clone(),
obj.matrix_world.multiply(t),
im.material.clone(),
));
}
}
ObjectKind::Light(light) => match light {
Light::Ambient(l) => {
out.world.ambient = out.world.ambient + v3(l.color) * l.intensity;
}
Light::Hemisphere(l) => {
out.world.hemispheres.push(RtHemisphere {
sky: v3(l.sky_color) * l.intensity,
ground: v3(l.ground_color) * l.intensity,
up: transform_direction(&obj.matrix_world, Vector3::UP).normalize(),
});
}
Light::Directional(l) => {
let pos = obj.world_position();
let d = Vector3::new(-pos.x, -pos.y, -pos.z);
let direction = if d.length_sq() > 1e-8 {
d.normalize()
} else {
transform_direction(&obj.matrix_world, l.direction).normalize()
};
out.lights.push(RtLight::Directional {
direction,
radiance: v3(l.color) * l.intensity,
angular_radius: settings.sun_angular_radius,
});
}
Light::Point(l) => out.lights.push(RtLight::Point {
position: obj.world_position(),
intensity: v3(l.color) * l.intensity,
radius: settings.light_radius,
distance: l.distance,
decay: l.decay,
}),
Light::Spot(l) => out.lights.push(RtLight::Spot {
position: obj.world_position(),
direction: transform_direction(&obj.matrix_world, l.direction).normalize(),
intensity: v3(l.color) * l.intensity,
radius: settings.light_radius,
distance: l.distance,
decay: l.decay,
cos_outer: l.angle.cos(),
cos_inner: (l.angle * (1.0 - l.penumbra)).cos(),
}),
Light::RectArea(l) => out.lights.push(RtLight::Rect {
position: obj.world_position(),
right: transform_direction(
&obj.matrix_world,
Vector3::new(l.width * 0.5, 0.0, 0.0),
),
up: transform_direction(
&obj.matrix_world,
Vector3::new(0.0, l.height * 0.5, 0.0),
),
radiance: v3(l.color) * l.intensity,
}),
},
ObjectKind::LineSegments(_) | ObjectKind::Points(_) | ObjectKind::Sprite(_) => {
out.report.skipped.push(format!(
"'{}': lines, points and sprites have no surface to trace",
obj.name
));
}
ObjectKind::Group => {}
}
});
for (geometry, world, material) in collected {
let slot = *material_slots
.entry(Arc::as_ptr(&material) as usize)
.or_insert_with(|| {
let (m, note) = convert_material(&material, &mut cache);
if let Some(note) = note {
out.report.approximated.push(note);
}
out.materials.push(m);
(out.materials.len() - 1) as u32
});
let before = out.tris.len();
out.append_geometry(&geometry, &world, slot);
if out.tris.len() > before {
out.report.meshes += 1;
}
}
out.world.env_faces = out
.world
.environment
.as_ref()
.and_then(|c| decode_cube(c))
.map(Box::new);
out.world.env_distribution = out
.world
.env_faces
.as_ref()
.and_then(|faces| EnvDistribution::build(|d| sample_cube(faces, d)));
out.shadows_all_opaque = !out.materials.iter().any(|m| m.is_shadow_transparent());
out.build_emissive_set();
out.bvh = RtBvh::build(&out.tris);
out.report.triangles = out.tris.len();
out.report.materials = out.materials.len();
out.report.lights = out.lights.len();
out.report.emissive_triangles = out.emissive.len();
out.report.textures_decoded = cache.len();
out
}
pub fn bounds(&self) -> (Vector3, Vector3) {
self.bvh.bounds()
}
pub fn scale(&self) -> f32 {
let (min, max) = self.bounds();
let d = (max - min).length();
if d.is_finite() && d > 0.0 {
d
} else {
1.0
}
}
pub fn has_light(&self) -> bool {
!self.lights.is_empty() || !self.emissive.is_empty() || !self.world.is_black()
}
fn append_geometry(
&mut self,
geometry: &crate::core::BufferGeometry,
world: &Matrix4,
material: u32,
) {
let Some(pos) = geometry.get_attribute("position") else {
return;
};
if pos.item_size < 3 {
return;
}
let vertex_count = pos.count();
let normal_attr = geometry
.get_attribute("normal")
.filter(|a| a.item_size >= 3);
let uv_attr = geometry.get_attribute("uv").filter(|a| a.item_size >= 2);
let normal_matrix = Matrix3::normal_matrix(world);
let read_pos = |i: usize| -> Vector3 {
let b = i * pos.item_size;
Vector3::new(pos.array[b], pos.array[b + 1], pos.array[b + 2]).apply_matrix4(world)
};
let read_normal = |i: usize| -> Option<Vector3> {
let a = normal_attr?;
let b = i * a.item_size;
let n = Vector3::new(a.array[b], a.array[b + 1], a.array[b + 2]);
Some(apply_matrix3(&normal_matrix, n))
};
let read_uv = |i: usize| -> Vector2 {
match uv_attr {
Some(a) => {
let b = i * a.item_size;
Vector2::new(a.array[b], a.array[b + 1])
}
None => Vector2::new(0.0, 0.0),
}
};
let push = |a: usize, b: usize, c: usize, s: &mut Self| {
if a >= vertex_count || b >= vertex_count || c >= vertex_count {
return;
}
let p = [read_pos(a), read_pos(b), read_pos(c)];
let face = (p[1] - p[0]).cross(p[2] - p[0]);
if face.length_sq() <= 0.0 || !face.x.is_finite() {
return;
}
let face = face.normalize();
let n = match (read_normal(a), read_normal(b), read_normal(c)) {
(Some(na), Some(nb), Some(nc)) => [
normalize_or(na, face),
normalize_or(nb, face),
normalize_or(nc, face),
],
_ => [face; 3],
};
s.tris.push(p);
s.shading.push(TriShading {
normals: n,
uvs: [read_uv(a), read_uv(b), read_uv(c)],
material,
});
};
match &geometry.index {
Some(idx) => {
for t in idx.chunks_exact(3) {
push(t[0] as usize, t[1] as usize, t[2] as usize, self);
}
}
None => {
for i in 0..vertex_count / 3 {
push(i * 3, i * 3 + 1, i * 3 + 2, self);
}
}
}
}
fn build_emissive_set(&mut self) {
let mut slot_of = vec![u32::MAX; self.tris.len()];
let mut tris: Vec<EmissiveTri> = Vec::new();
let mut total = 0.0f32;
for (i, sh) in self.shading.iter().enumerate() {
let m = &self.materials[sh.material as usize];
if !m.is_emissive() {
continue;
}
let t = &self.tris[i];
let area = 0.5 * (t[1] - t[0]).cross(t[2] - t[0]).length();
if area <= 0.0 {
continue;
}
let w = area * luminance(m.emission);
if w <= 0.0 {
continue;
}
total += w;
slot_of[i] = tris.len() as u32;
tris.push(EmissiveTri {
triangle: i as u32,
area,
cdf: total,
});
}
if total > 0.0 {
for e in &mut tris {
e.cdf /= total;
}
if let Some(last) = tris.last_mut() {
last.cdf = 1.0;
}
}
self.emissive = EmissiveSet {
tris,
slot_of,
total_weight: total,
};
}
}
fn convert_material(material: &Material, cache: &mut TextureCache) -> (RtMaterial, Option<String>) {
let mut tex = |t: &Option<Arc<crate::textures::Texture>>| t.as_ref().and_then(|t| cache.get(t));
match material {
Material::Standard(m) => (
RtMaterial {
base_color: v3(m.color),
base_color_map: tex(&m.map),
opacity: m.opacity,
roughness: m.roughness,
roughness_map: tex(&m.roughness_map),
metallic: m.metalness,
metallic_map: tex(&m.metalness_map),
emission: v3(m.emissive) * m.emissive_intensity,
emissive_map: tex(&m.emissive_map),
normal_map: tex(&m.normal_map),
normal_scale: m.normal_scale,
..Default::default()
},
None,
),
Material::Physical(m) => (
RtMaterial {
base_color: v3(m.color),
base_color_map: tex(&m.map),
opacity: m.opacity,
roughness: m.roughness,
roughness_map: tex(&m.roughness_map),
metallic: m.metalness,
metallic_map: tex(&m.metalness_map),
emission: v3(m.emissive) * m.emissive_intensity,
emissive_map: tex(&m.emissive_map),
normal_map: tex(&m.normal_map),
normal_scale: m.normal_scale,
transmission: m.transmission,
ior: m.ior,
attenuation_color: v3(m.attenuation_color),
attenuation_distance: m.attenuation_distance,
clearcoat: m.clearcoat,
clearcoat_roughness: m.clearcoat_roughness,
anisotropy: m.anisotropy,
anisotropy_rotation: m.anisotropy_rotation,
..Default::default()
},
unsupported_physical(m),
),
Material::Lambert(m) => (
RtMaterial {
base_color: v3(m.color),
opacity: m.opacity,
roughness: 1.0,
metallic: 0.0,
emission: v3(m.emissive),
..Default::default()
},
None,
),
Material::Phong(m) => {
let alpha = (2.0 / (m.shininess.max(0.0) + 2.0)).sqrt();
(
RtMaterial {
base_color: v3(m.color),
opacity: m.opacity,
roughness: alpha.sqrt().clamp(0.02, 1.0),
metallic: 0.0,
specular_tint: v3(m.specular),
emission: v3(m.emissive),
..Default::default()
},
Some(format!(
"MeshPhongMaterial: shininess {} mapped to GGX roughness {:.3}, and `specular` \
becomes the dielectric F0 tint",
m.shininess,
alpha.sqrt()
)),
)
}
Material::Toon(m) => (
RtMaterial {
base_color: v3(m.color),
opacity: m.opacity,
roughness: 1.0,
..Default::default()
},
Some("MeshToonMaterial: the ramp is a raster effect; traced as a matte diffuse surface"
.into()),
),
Material::Matcap(m) => (
RtMaterial {
base_color: v3(m.color),
opacity: m.opacity,
roughness: 0.5,
..Default::default()
},
Some(
"MeshMatcapMaterial: the capture bakes in a light rig; traced as a mid-gloss dielectric"
.into(),
),
),
Material::Basic(m) => (
RtMaterial {
base_color: Vector3::ZERO,
base_color_map: tex(&m.map),
emission: v3(m.color),
emissive_map: tex(&m.map),
opacity: m.opacity,
alpha_test: m.alpha_test,
unlit: true,
..Default::default()
},
Some(
"MeshBasicMaterial: unlit, so traced as a pure emitter of its own colour — it lights the scene"
.into(),
),
),
Material::Mirror(m) => (
RtMaterial {
base_color: v3(m.color),
roughness: 0.0,
metallic: 1.0,
..Default::default()
},
Some("MirrorMaterial: traced as a smooth metal instead of a projected render target".into()),
),
Material::Normal(_) => (
RtMaterial {
base_color: Vector3::new(0.5, 0.5, 0.5),
roughness: 1.0,
..Default::default()
},
Some("MeshNormalMaterial: a debug view with no BSDF; traced as 50% grey".into()),
),
Material::Depth(_) => (
RtMaterial {
base_color: Vector3::new(0.5, 0.5, 0.5),
roughness: 1.0,
..Default::default()
},
Some("MeshDepthMaterial: a debug view with no BSDF; traced as 50% grey".into()),
),
Material::Line(_)
| Material::Points(_)
| Material::Sprite(_)
| Material::Distance(_) => (
RtMaterial {
base_color: Vector3::new(0.8, 0.8, 0.8),
..Default::default()
},
Some("line/point/sprite/distance material on a mesh: traced as a plain diffuse surface".into()),
),
Material::Sky(_) => (
RtMaterial {
base_color: Vector3::ZERO,
emission: Vector3::new(0.4, 0.6, 1.0),
unlit: true,
..Default::default()
},
Some(
"SkyMaterial: the Preetham model is not evaluated here; traced as a flat blue emitter"
.into(),
),
),
Material::Atmosphere(_) => (
RtMaterial {
base_color: Vector3::new(0.6, 0.75, 1.0),
transmission: 1.0,
ior: 1.0003,
roughness: 0.0,
..Default::default()
},
Some(
"AtmosphereMaterial: analytic scattering is not evaluated here; traced as a clear tinted shell"
.into(),
),
),
Material::Shader(_) => (
RtMaterial {
base_color: Vector3::new(0.8, 0.8, 0.8),
roughness: 0.8,
..Default::default()
},
Some(
"ShaderMaterial: custom WGSL cannot run on the CPU tracer; traced as a rough dielectric"
.into(),
),
),
}
}
fn unsupported_physical(m: &crate::materials::PhysicalMaterial) -> Option<String> {
let mut missing: Vec<&str> = Vec::new();
if m.sheen > 0.0 {
missing.push("sheen");
}
if m.iridescence > 0.0 {
missing.push("iridescence");
}
if m.dispersion > 0.0 {
missing.push("dispersion (the tracer is not spectral)");
}
if m.displacement_map.is_some() {
missing.push("displacementMap (geometry is traced as supplied)");
}
if missing.is_empty() {
return None;
}
Some(format!(
"MeshPhysicalMaterial: {} not modelled by the path tracer",
missing.join(", ")
))
}
fn skin_geometry(
geometry: &crate::core::BufferGeometry,
skeleton: &crate::core::Skeleton,
) -> Option<crate::core::BufferGeometry> {
let pos = geometry.get_attribute("position")?;
let joints = geometry.get_attribute("joint")?;
let weights = geometry.get_attribute("weight")?;
if joints.item_size < 4 || weights.item_size < 4 || pos.item_size < 3 {
return None;
}
let n = pos.count();
let normals = geometry
.get_attribute("normal")
.filter(|a| a.item_size >= 3);
let mut out_pos = vec![0.0f32; n * 3];
let mut out_nrm = normals.map(|_| vec![0.0f32; n * 3]);
for i in 0..n {
let p = Vector3::new(
pos.array[i * pos.item_size],
pos.array[i * pos.item_size + 1],
pos.array[i * pos.item_size + 2],
);
let nrm = normals.map(|a| {
Vector3::new(
a.array[i * a.item_size],
a.array[i * a.item_size + 1],
a.array[i * a.item_size + 2],
)
});
let mut skinned = Vector3::ZERO;
let mut skinned_n = Vector3::ZERO;
let mut total = 0.0f32;
for k in 0..4 {
let w = weights.array[i * weights.item_size + k];
if w == 0.0 {
continue;
}
let j = joints.array[i * joints.item_size + k] as usize;
let Some(m) = skeleton.bone_matrices.get(j) else {
continue;
};
skinned = skinned + p.apply_matrix4(m) * w;
if let Some(nrm) = nrm {
skinned_n = skinned_n + apply_matrix3(&Matrix3::normal_matrix(m), nrm) * w;
}
total += w;
}
let (p_out, n_out) = if total > 0.0 {
(skinned * (1.0 / total), skinned_n * (1.0 / total))
} else {
(p, nrm.unwrap_or(Vector3::UP))
};
out_pos[i * 3] = p_out.x;
out_pos[i * 3 + 1] = p_out.y;
out_pos[i * 3 + 2] = p_out.z;
if let Some(o) = &mut out_nrm {
let n_out = normalize_or(n_out, Vector3::UP);
o[i * 3] = n_out.x;
o[i * 3 + 1] = n_out.y;
o[i * 3 + 2] = n_out.z;
}
}
let mut g = crate::core::BufferGeometry::new();
g.set_attribute("position", crate::core::BufferAttribute::new(out_pos, 3));
if let Some(o) = out_nrm {
g.set_attribute("normal", crate::core::BufferAttribute::new(o, 3));
}
if let Some(uv) = geometry.get_attribute("uv") {
g.set_attribute("uv", uv.clone());
}
if let Some(idx) = &geometry.index {
g.set_index(idx.clone());
}
Some(g)
}
fn decode_cube(cube: &CubeTexture) -> Option<[CpuTexture; 6]> {
let bilinear = cube.mag_filter == crate::textures::TextureFilter::Linear;
let mut faces = Vec::with_capacity(6);
for i in 0..6 {
let decoded = match &cube.faces_f32 {
Some(hdr) => {
CpuTexture::from_linear_f32(cube.size, cube.size, hdr[i].as_ref().clone(), bilinear)
}
None => {
let mut tex = crate::textures::Texture::new(
cube.size,
cube.size,
cube.format,
cube.faces[i].as_ref().clone(),
);
tex.mag_filter = cube.mag_filter;
tex.min_filter = cube.min_filter;
tex.wrap_s = crate::textures::TextureWrap::ClampToEdge;
tex.wrap_t = crate::textures::TextureWrap::ClampToEdge;
tex.flip_y = false;
CpuTexture::from_texture(&tex)
}
};
faces.push(decoded?);
}
let mut it = faces.into_iter();
Some([
it.next()?,
it.next()?,
it.next()?,
it.next()?,
it.next()?,
it.next()?,
])
}
fn sample_cube(faces: &[CpuTexture; 6], dir: Vector3) -> Vector3 {
let (ax, ay, az) = (dir.x.abs(), dir.y.abs(), dir.z.abs());
let (face, sc, tc, ma) = if ax >= ay && ax >= az {
if dir.x > 0.0 {
(0usize, -dir.z, -dir.y, ax)
} else {
(1, dir.z, -dir.y, ax)
}
} else if ay >= az {
if dir.y > 0.0 {
(2, dir.x, dir.z, ay)
} else {
(3, dir.x, -dir.z, ay)
}
} else if dir.z > 0.0 {
(4, dir.x, -dir.y, az)
} else {
(5, -dir.x, -dir.y, az)
};
if ma <= 0.0 {
return Vector3::ZERO;
}
let uv = Vector2::new((sc / ma + 1.0) * 0.5, (tc / ma + 1.0) * 0.5);
if !uv.x.is_finite() || !uv.y.is_finite() {
return Vector3::ZERO;
}
faces[face].sample_rgb(uv)
}
fn v3(c: Color) -> Vector3 {
Vector3::new(c.r, c.g, c.b)
}
pub fn luminance(c: Vector3) -> f32 {
0.2126 * c.x + 0.7152 * c.y + 0.0722 * c.z
}
fn normalize_or(v: Vector3, fallback: Vector3) -> Vector3 {
if v.length_sq() > 1e-20 {
v.normalize()
} else {
fallback
}
}
fn transform_direction(m: &Matrix4, v: Vector3) -> Vector3 {
let e = &m.elements;
Vector3::new(
e[0] * v.x + e[4] * v.y + e[8] * v.z,
e[1] * v.x + e[5] * v.y + e[9] * v.z,
e[2] * v.x + e[6] * v.y + e[10] * v.z,
)
}
fn apply_matrix3(m: &Matrix3, v: Vector3) -> Vector3 {
let e = &m.elements;
Vector3::new(
e[0] * v.x + e[3] * v.y + e[6] * v.z,
e[1] * v.x + e[4] * v.y + e[7] * v.z,
e[2] * v.x + e[5] * v.y + e[8] * v.z,
)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::core::Object3D;
use crate::geometries::BoxGeometry;
use crate::lights::{AmbientLight, DirectionalLight, PointLight};
use crate::materials::StandardMaterial;
fn box_mesh(color: Color) -> crate::core::Mesh {
crate::core::Mesh::new(
BoxGeometry::new(1.0, 1.0, 1.0),
Material::Standard(StandardMaterial::new(color)),
)
}
#[test]
fn a_box_flattens_to_twelve_triangles() {
let mut scene = Scene::new();
scene.add(Object3D::mesh(box_mesh(Color::WHITE)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert_eq!(rt.tris.len(), 12);
assert_eq!(rt.shading.len(), 12);
assert_eq!(rt.materials.len(), 1);
assert_eq!(rt.report.meshes, 1);
}
#[test]
fn world_matrices_are_applied() {
let mut scene = Scene::new();
let mut obj = Object3D::mesh(box_mesh(Color::WHITE));
obj.position = Vector3::new(10.0, 0.0, 0.0);
scene.add(obj);
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
let (min, max) = rt.bounds();
assert!(min.x > 9.0, "min {min:?}");
assert!(max.x < 11.0, "max {max:?}");
}
#[test]
fn shared_materials_collapse_to_one_slot() {
let mut scene = Scene::new();
let geom = Arc::new(BoxGeometry::new(1.0, 1.0, 1.0));
let mat = Arc::new(Material::Standard(StandardMaterial::new(Color::RED)));
for i in 0..5 {
let mut obj = Object3D::mesh(crate::core::Mesh::from_arc(geom.clone(), mat.clone()));
obj.position = Vector3::new(i as f32 * 3.0, 0.0, 0.0);
scene.add(obj);
}
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert_eq!(rt.materials.len(), 1, "one Arc, one material slot");
assert_eq!(rt.tris.len(), 60);
}
#[test]
fn instanced_meshes_expand() {
let mut scene = Scene::new();
let mut im = crate::core::InstancedMesh::new(
BoxGeometry::new(1.0, 1.0, 1.0),
Material::Standard(StandardMaterial::new(Color::WHITE)),
4,
);
for i in 0..4 {
im.set_matrix_at(
i,
Matrix4::translation(Vector3::new(i as f32 * 2.0, 0.0, 0.0)),
);
}
scene.add(Object3D::instanced_mesh(im));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert_eq!(rt.tris.len(), 48);
let (min, max) = rt.bounds();
assert!(
max.x - min.x > 6.0,
"instances did not spread: {min:?}..{max:?}"
);
}
#[test]
fn lights_are_collected_with_three_js_conventions() {
let mut scene = Scene::new();
let mut dir = Object3D::light(DirectionalLight::new(Color::WHITE, 1.0));
dir.position = Vector3::new(0.0, 10.0, 0.0);
scene.add(dir);
let mut pt = Object3D::light(PointLight::new(Color::RED, 2.0));
pt.position = Vector3::new(3.0, 0.0, 0.0);
scene.add(pt);
scene.add_light(AmbientLight::new(Color::WHITE, 0.25));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert_eq!(rt.lights.len(), 2, "ambient is world lighting, not a light");
assert!((rt.world.ambient.x - 0.25).abs() < 1e-6);
match rt.lights[0] {
RtLight::Directional { direction, .. } => {
assert!((direction.y + 1.0).abs() < 1e-5, "got {direction:?}");
}
other => panic!("expected a directional light, got {other:?}"),
}
match rt.lights[1] {
RtLight::Point {
position,
intensity,
..
} => {
assert!((position.x - 3.0).abs() < 1e-5);
assert!((intensity.x - 2.0).abs() < 1e-5);
}
other => panic!("expected a point light, got {other:?}"),
}
}
#[test]
fn emissive_surfaces_enter_the_sampling_distribution() {
let mut scene = Scene::new();
let mut mat = StandardMaterial::new(Color::BLACK);
mat.emissive = Color::WHITE;
mat.emissive_intensity = 5.0;
scene.add(Object3D::mesh(crate::core::Mesh::new(
BoxGeometry::new(1.0, 1.0, 1.0),
Material::Standard(mat),
)));
scene.add(Object3D::mesh(box_mesh(Color::WHITE)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert_eq!(rt.emissive.len(), 12, "only the emitting box's faces");
assert!(rt.emissive.total_weight() > 0.0);
let mut prev = 0.0;
for e in &rt.emissive.tris {
assert!(e.cdf >= prev, "cdf not monotonic");
prev = e.cdf;
}
assert!((prev - 1.0).abs() < 1e-6);
for e in &rt.emissive.tris {
assert!(rt.emissive.probability_of(e.triangle) > 0.0);
}
}
#[test]
fn emissive_sampling_hits_every_slot() {
let mut scene = Scene::new();
let mut mat = StandardMaterial::new(Color::BLACK);
mat.emissive = Color::WHITE;
scene.add(Object3D::mesh(crate::core::Mesh::new(
BoxGeometry::new(1.0, 1.0, 1.0),
Material::Standard(mat),
)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
let mut seen = vec![false; rt.emissive.len()];
for i in 0..1000 {
let u = i as f32 / 1000.0;
let (e, p) = rt.emissive.sample(u).unwrap();
assert!(p > 0.0);
let slot = rt
.emissive
.tris
.iter()
.position(|t| t.triangle == e.triangle)
.unwrap();
seen[slot] = true;
}
assert!(seen.iter().all(|&s| s), "some emitter is unreachable");
}
#[test]
fn unsupported_physical_features_are_reported() {
let mut scene = Scene::new();
let mut m = crate::materials::PhysicalMaterial::new(Color::WHITE);
m.sheen = 0.8;
m.iridescence = 0.4;
scene.add(Object3D::mesh(crate::core::Mesh::new(
BoxGeometry::new(1.0, 1.0, 1.0),
Material::Physical(m),
)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
let notes = rt.report.approximated.join(" ");
assert!(notes.contains("sheen"), "sheen went unreported: {notes}");
assert!(
notes.contains("iridescence"),
"iridescence went unreported: {notes}"
);
let mut scene = Scene::new();
scene.add(Object3D::mesh(crate::core::Mesh::new(
BoxGeometry::new(1.0, 1.0, 1.0),
Material::Physical(crate::materials::PhysicalMaterial::new(Color::WHITE)),
)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert!(
rt.report.approximated.is_empty(),
"{:?}",
rt.report.approximated
);
}
#[test]
fn basic_material_becomes_an_emitter() {
let mut scene = Scene::new();
scene.add(Object3D::mesh(crate::core::Mesh::new(
BoxGeometry::new(1.0, 1.0, 1.0),
Material::Basic(crate::materials::BasicMaterial::new(Color::GREEN)),
)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert!(rt.materials[0].unlit);
assert!(rt.materials[0].emission.y > 0.9);
assert!(
!rt.report.approximated.is_empty(),
"the choice must be reported"
);
}
#[test]
fn empty_scene_is_valid_and_unlit() {
let mut scene = Scene::new();
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert_eq!(rt.tris.len(), 0);
assert!(!rt.has_light());
assert_eq!(rt.scale(), 1.0);
}
#[test]
fn degenerate_triangles_are_dropped() {
let mut g = crate::core::BufferGeometry::new();
g.set_attribute(
"position",
crate::core::BufferAttribute::new(
vec![
0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 2.0, 0.0, 0.0,
],
3,
),
);
let mut scene = Scene::new();
scene.add(Object3D::mesh(crate::core::Mesh::new(
g,
Material::Standard(StandardMaterial::new(Color::WHITE)),
)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert_eq!(rt.tris.len(), 1);
}
#[test]
fn geometry_without_normals_shades_flat() {
let mut g = crate::core::BufferGeometry::new();
g.set_attribute(
"position",
crate::core::BufferAttribute::new(vec![0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0], 3),
);
let mut scene = Scene::new();
scene.add(Object3D::mesh(crate::core::Mesh::new(
g,
Material::Standard(StandardMaterial::new(Color::WHITE)),
)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
let n = rt.shading[0].normals;
assert!((n[0] - n[1]).length() < 1e-6 && (n[1] - n[2]).length() < 1e-6);
assert!(
(n[0].z.abs() - 1.0).abs() < 1e-5,
"expected +/-Z, got {:?}",
n[0]
);
}
#[test]
fn ambient_only_world_still_counts_as_lit() {
let mut scene = Scene::new();
scene.add(Object3D::mesh(box_mesh(Color::WHITE)));
scene.add_light(AmbientLight::new(Color::WHITE, 0.5));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert!(rt.has_light());
let l = rt.world.lighting_radiance(Vector3::UP);
assert!((l.x - 0.5).abs() < 1e-6);
}
#[test]
fn background_mode_does_not_change_lighting() {
let mut scene = Scene::new();
scene.background = Color::from_hex(0xff0000);
scene.add_light(AmbientLight::new(Color::WHITE, 0.25));
let s = RaytraceSettings {
background: BackgroundMode::Transparent,
..Default::default()
};
let rt = RaytraceScene::build(&mut scene, &s);
let (bg, alpha) = rt.world.camera_radiance(Vector3::UP);
assert_eq!(alpha, 0.0);
assert_eq!(bg, Vector3::ZERO);
assert!((rt.world.lighting_radiance(Vector3::UP).x - 0.25).abs() < 1e-6);
}
#[test]
fn cube_sampling_recovers_the_face_a_direction_points_at() {
let size = 4u32;
let mut faces: [Vec<u8>; 6] = Default::default();
for (i, f) in faces.iter_mut().enumerate() {
let mut px = vec![0u8; (size * size * 4) as usize];
for p in px.chunks_exact_mut(4) {
p[0] = (i * 40) as u8;
p[1] = (i * 40) as u8;
p[2] = (i * 40) as u8;
p[3] = 255;
}
*f = px;
}
let cube = CubeTexture::new(size, crate::textures::TextureFormat::Rgba8Unorm, faces);
let decoded = decode_cube(&cube).unwrap();
let expect = [
(Vector3::new(1.0, 0.0, 0.0), 0),
(Vector3::new(-1.0, 0.0, 0.0), 1),
(Vector3::new(0.0, 1.0, 0.0), 2),
(Vector3::new(0.0, -1.0, 0.0), 3),
(Vector3::new(0.0, 0.0, 1.0), 4),
(Vector3::new(0.0, 0.0, -1.0), 5),
];
for (dir, face) in expect {
let got = sample_cube(&decoded, dir);
let want = (face * 40) as f32 / 255.0;
assert!(
(got.x - want).abs() < 1e-3,
"direction {dir:?} should read face {face} ({want}), got {got:?}"
);
}
}
#[test]
fn an_opaque_texture_keeps_the_fast_shadow_path() {
let opaque = Arc::new(crate::textures::Texture::new(
2,
2,
crate::textures::TextureFormat::Rgba8Unorm,
vec![255u8; 16],
));
let mut cutout_data = vec![255u8; 16];
cutout_data[3] = 0;
let cutout = Arc::new(crate::textures::Texture::new(
2,
2,
crate::textures::TextureFormat::Rgba8Unorm,
cutout_data,
));
for (map, expect_opaque) in [(opaque, true), (cutout, false)] {
let mut scene = Scene::new();
let mut m = StandardMaterial::new(Color::WHITE);
m.map = Some(map);
scene.add(Object3D::mesh(crate::core::Mesh::new(
BoxGeometry::new(1.0, 1.0, 1.0),
Material::Standard(m),
)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert_eq!(
rt.shadows_all_opaque, expect_opaque,
"textured material classified wrongly"
);
}
}
#[test]
fn an_emissive_map_without_an_emissive_colour_is_not_a_light() {
let map = Arc::new(crate::textures::Texture::new(
2,
2,
crate::textures::TextureFormat::Rgba8Unorm,
vec![255u8; 16],
));
let mut scene = Scene::new();
let mut m = StandardMaterial::new(Color::WHITE);
m.emissive_map = Some(map.clone());
scene.add(Object3D::mesh(crate::core::Mesh::new(
BoxGeometry::new(1.0, 1.0, 1.0),
Material::Standard(m),
)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert!(rt.emissive.is_empty(), "black emissive should emit nothing");
let mut scene = Scene::new();
let mut m = StandardMaterial::new(Color::WHITE);
m.emissive_map = Some(map);
m.emissive = Color::WHITE;
scene.add(Object3D::mesh(crate::core::Mesh::new(
BoxGeometry::new(1.0, 1.0, 1.0),
Material::Standard(m),
)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert_eq!(rt.emissive.len(), 12);
}
#[test]
fn an_hdr_environment_round_trips_through_the_cube() {
let (w, h) = (256u32, 128u32);
let mut src = vec![0.0f32; (w * h * 4) as usize];
for y in 0..h {
for x in 0..w {
let i = ((y * w + x) * 4) as usize;
src[i] = (x as f32 + 0.5) / w as f32; src[i + 1] = (y as f32 + 0.5) / h as f32; src[i + 3] = 1.0;
}
}
let cube = crate::extras::PmremGenerator::from_equirect_f32(&src, w, h, 64);
let mut scene = Scene::new();
scene.environment = Some(Arc::new(cube));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
for d in [
Vector3::new(1.0, 0.2, -0.3).normalize(),
Vector3::new(-1.0, -0.25, 0.4).normalize(),
Vector3::new(0.15, 0.2, 1.0).normalize(),
Vector3::new(0.3, -0.2, -1.0).normalize(),
Vector3::new(0.89, 0.38, 0.25).normalize(),
Vector3::new(-0.40, 0.80, 0.45).normalize(),
Vector3::new(0.3, -0.9, -0.31).normalize(),
] {
let lon = d.z.atan2(d.x);
let lat = d.y.clamp(-1.0, 1.0).asin();
let want_u = (lon / (2.0 * std::f32::consts::PI) + 0.5).rem_euclid(1.0);
let want_v = (0.5 - lat / std::f32::consts::PI).clamp(0.0, 1.0);
let got = rt.world.lighting_radiance(d);
assert!(
(got.x - want_u).abs() < 0.02,
"direction {d:?}: longitude {want_u} read back as {}",
got.x
);
assert!(
(got.y - want_v).abs() < 0.02,
"direction {d:?}: latitude {want_v} read back as {}",
got.y
);
}
}
#[test]
fn an_hdr_environment_keeps_values_above_one() {
let size = 8u32;
let bright = 500.0f32;
let faces: [Vec<f32>; 6] = std::array::from_fn(|_| {
let mut f = vec![0.0f32; (size * size * 4) as usize];
for p in f.chunks_exact_mut(4) {
p[0] = bright;
p[1] = bright;
p[2] = bright;
p[3] = 1.0;
}
f
});
let mut scene = Scene::new();
scene.environment = Some(Arc::new(crate::textures::CubeTexture::new_f32(size, faces)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
let l = rt.world.lighting_radiance(Vector3::new(0.0, 1.0, 0.0));
assert!(
(l.x - bright).abs() < 0.01 * bright,
"expected {bright}, read {} — the 8-bit fallback was used",
l.x
);
}
#[test]
fn shadow_opacity_is_detected() {
let mut scene = Scene::new();
scene.add(Object3D::mesh(box_mesh(Color::WHITE)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert!(rt.shadows_all_opaque);
let mut scene = Scene::new();
let mut m = StandardMaterial::new(Color::WHITE);
m.opacity = 0.4;
scene.add(Object3D::mesh(crate::core::Mesh::new(
BoxGeometry::new(1.0, 1.0, 1.0),
Material::Standard(m),
)));
let rt = RaytraceScene::build(&mut scene, &RaytraceSettings::default());
assert!(!rt.shadows_all_opaque);
}
}