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
use crate::core::{Object3D, ObjectArena, ObjectId};
use crate::lights::Light;
use crate::math::{Color, Matrix4};
use crate::textures::CubeTexture;
use std::sync::Arc;
/// Fog parameters mirroring three.js [`Fog`](https://threejs.org/docs/#api/en/scene/Fog)
/// (linear) and `FogExp2`.
///
/// `mode`: `0` = disabled, `1` = linear, `2` = exponential squared.
#[derive(Debug, Clone, Copy)]
pub struct FogParams {
pub color: Color,
pub near: f32,
pub far: f32,
pub density: f32,
pub mode: u32,
}
impl Default for FogParams {
fn default() -> Self {
Self {
color: Color::WHITE,
near: 1.0,
far: 1000.0,
density: 0.0,
mode: 0,
}
}
}
/// Root scene container: object arena, background, environment, fog.
///
/// Mirrors three.js [`Scene`](https://threejs.org/docs/#api/en/scenes/Scene) —
/// the root is an `Object3D` group named `"Scene"`.
pub struct Scene {
pub arena: ObjectArena,
pub root: ObjectId,
pub background: Color,
/// Clear alpha for the background (0.0 = fully transparent framebuffer,
/// 1.0 = opaque). Lets offscreen renders produce transparent PNGs.
pub background_alpha: f32,
/// three.js `scene.environment`: the image-based light of every Standard
/// and Physical material without an `envMap` of its own. Sampled through
/// its PMREM atlas when it carries one, else through its mip chain.
pub environment: Option<Arc<CubeTexture>>,
/// three.js `scene.environmentIntensity` (default 1).
pub environment_intensity: f32,
/// three.js `scene.environmentRotation` (default zero).
pub environment_rotation: crate::math::Euler,
/// Alternate environment input: a CubeRenderTarget's cube view. When set,
/// the renderer samples from the live RT contents (typically produced by
/// a CubeCamera) instead of the CPU-backed `environment` cube texture.
pub environment_cube_rt: Option<u32>,
pub fog: FogParams,
}
impl Scene {
/// Every visible [`PositionalAudio`](crate::audio::PositionalAudio) as
/// `listener` hears it, for a playback backend to apply each frame. Uses
/// the world matrices of the last update.
#[cfg(feature = "audio")]
pub fn audio_mix(
&self,
listener: &crate::audio::AudioListener,
) -> Vec<(ObjectId, crate::audio::SpatialMix)> {
let mut mix = Vec::new();
self.arena.traverse_visible(self.root, &mut |id, obj| {
if let crate::core::ObjectKind::Audio(audio) = &obj.kind {
mix.push((id, audio.mix(&obj.matrix_world, listener)));
}
});
mix
}
/// Empty scene with dark gray background and no fog.
pub fn new() -> Self {
let mut arena = ObjectArena::new();
let mut root_obj = Object3D::group();
root_obj.name = "Scene".into();
let root = arena.insert(root_obj);
Self {
arena,
root,
background: Color::from_hex(0x111111),
background_alpha: 1.0,
environment: None,
environment_cube_rt: None,
environment_intensity: 1.0,
environment_rotation: crate::math::Euler::default(),
fog: FogParams::default(),
}
}
/// `scene.add(obj)` — insert and parent under the scene root.
pub fn add(&mut self, obj: Object3D) -> ObjectId {
let id = self.arena.insert(obj);
self.arena.add_child(self.root, id);
id
}
/// Convenience: build a light Object3D and add it to the scene.
/// Geometry plus material into the scene, in one call.
///
/// `scene.add(Object3D::mesh(Mesh::new(geometry, material)))` is three
/// constructors deep to say one thing, and it is the single most repeated
/// line in every example in this crate.
pub fn add_mesh(
&mut self,
geometry: crate::core::BufferGeometry,
material: crate::materials::Material,
) -> ObjectId {
self.add(Object3D::mesh(crate::core::Mesh::new(geometry, material)))
}
pub fn add_light(&mut self, light: impl Into<Light>) -> ObjectId {
self.add(Object3D::light(light))
}
/// Add under a specific parent (not the scene root).
pub fn add_to(&mut self, parent: ObjectId, obj: Object3D) -> ObjectId {
let id = self.arena.insert(obj);
self.arena.add_child(parent, id);
id
}
/// Give the scene root a fixed transform that every object inherits — the
/// single orienting/centring group a host app (e.g. a viewer that rotates
/// its whole scene) would otherwise keep on the CPU side. `update_world`
/// composes it into each child's world matrix, so cameras, picking and
/// rendering all see the objects in that frame. Takes the matrix as given
/// (auto-recompose from position/quaternion/scale is turned off on the root).
pub fn set_root_transform(&mut self, matrix: Matrix4) {
if let Some(root) = self.arena.get_mut(self.root) {
root.matrix = matrix;
root.matrix_auto_update = false;
root.matrix_world_auto_update = true;
}
}
pub fn get(&self, id: ObjectId) -> Option<&Object3D> {
self.arena.get(id)
}
pub fn get_mut(&mut self, id: ObjectId) -> Option<&mut Object3D> {
self.arena.get_mut(id)
}
/// Refresh all `matrix_world`s. The renderer calls this each frame.
/// Bring every world matrix up to date — what three.js's renderer does
/// with `scene.updateMatrixWorld()` before drawing, and skips when the
/// root's `matrix_world_auto_update` is off.
pub fn update_world(&mut self) {
if self
.arena
.get(self.root)
.is_some_and(|r| !r.matrix_world_auto_update)
{
return;
}
self.arena
.update_world_matrices(self.root, Matrix4::identity());
// three.js's renderer runs `skeleton.update()` for each skinned mesh
// it draws, from the bones' fresh world matrices.
crate::core::update_skeletons(&mut self.arena);
}
}
impl Default for Scene {
fn default() -> Self {
Self::new()
}
}