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
//! Port of `three.js/src/scenes/Scene.js` (rung 2 subset).
use crate::core::{Object3D, ObjectRef, SceneRenderHook};
use crate::materials::MeshBasicNodeMaterial;
use crate::math::{Color, Matrix4};
use crate::nodes::tsl::FogNode;
use crate::textures::CubeTexture;
/// `Scene.background`. three.js accepts a `Color`, a `Texture` or a
/// `CubeTexture`; `Background.update()` branches on which one it is — a colour
/// becomes the clear value, anything else becomes the skybox mesh.
#[derive(Clone, Debug)]
#[non_exhaustive]
pub enum Background {
/// A flat clear colour.
Color(Color),
/// A skybox drawn from a cube texture.
CubeTexture(CubeTexture),
/// `scene.backgroundNode = …` — `Background.update()`'s
/// `background.isNode` branch, which draws the skybox sphere with
/// `vec4( node ).mul( backgroundIntensity )` instead of clearing. Held in
/// the same slot because `nodes.getBackgroundNode( scene ) ||
/// scene.background` makes the node win over a plain background.
///
/// Any node, not just a `color()`: `webgpu_skinning` uses
/// `screenUV.y.mix( color( 0x66bbff ), color( 0x4466ff ) )`.
Node(crate::nodes::NodeRef),
/// `scene.background = <the texture of a generated PMREM>`.
///
/// Upstream this is the PMREM cube render target's texture, flagged
/// `isPMREMTexture`; `NodeManager.getBackgroundNode()` turns it into
/// `pmremTexture( background )` and `Background.update()` wraps that in
/// the node branch's context — `getUV` is `backgroundRotation.mul(
/// normalWorldGeometry )` and `getTextureLevel` is `backgroundBlurriness`.
/// The port carries the handle rather than the texture, because the
/// `maxLod` uniform the read needs travels with it; the renderer builds the
/// node, so an application writes the one line the page does.
Pmrem(crate::materials::environment::PmremHandle),
/// `scene.backgroundNode = <a graph of pmremTexture()s>` —
/// `webgpu_cubemap_mix`'s `mix( pmremTexture( cube2 ), pmremTexture(
/// cube1 ), … )`. `Background.update()` builds it under the same context
/// as [`Background::Pmrem`].
EnvironmentNode(crate::materials::environment::EnvironmentNode),
}
impl From<Color> for Background {
fn from(color: Color) -> Self {
Background::Color(color)
}
}
impl From<CubeTexture> for Background {
fn from(texture: CubeTexture) -> Self {
Background::CubeTexture(texture)
}
}
/// `Scene extends Object3D`.
///
/// The `Object3D` half is a real scene-graph [`ObjectRef`], so the tree under a scene
/// is the tree the renderer walks: `Group`s, lights and their children all
/// nest, and `Renderer::render` collects drawables with
/// `crate::renderer::project_object`. The fields below are what `Scene` adds
/// to `Object3D`; they are not a `Payload` variant because nothing in the
/// renderer's traversal branches on them.
pub struct Scene {
/// The scene root. `node.borrow().is_scene` is true.
pub node: ObjectRef,
/// `scene.background`.
pub background: Option<Background>,
/// `scene.backgroundBlurriness` — the roughness the background's PMREM is
/// read at, in `[ 0, 1 ]`. Three reads it through `backgroundBlurriness`,
/// the render-group uniform `BackgroundNode` puts on `getTextureLevel`, so
/// changing it is a uniform write and not a new program.
pub background_blurriness: f64,
/// `scene.backgroundIntensity` — the factor `BackgroundNode` multiplies
/// the background colour by. Like [`Scene::background_blurriness`] it is
/// a render-group uniform, so changing it is a uniform write.
pub background_intensity: f64,
/// `scene.environmentIntensity` — the factor `EnvironmentNode` scales the
/// radiance and irradiance of [`Scene::environment`] (or
/// [`Scene::environment_node`]) by, on every material that takes the
/// scene's environment instead of carrying its own. A material with its
/// own `pmrem_env` reads `envMapIntensity` instead, which the port keeps
/// at 1.
pub environment_intensity: f64,
/// `scene.environment` — the default environment map for every material in
/// the scene that does not carry one of its own.
///
/// Upstream this is a plain `Texture` and
/// `NodeManager.updateEnvironment( scene )` turns it into a
/// `scene.environmentNode`, which `NodeMaterial.setupEnvironment()` falls
/// back to when neither `builder.context.environment` nor the material's
/// own `envNode` is set. The port carries the generated PMREM's handle for
/// the reason [`Background::Pmrem`] does: the `maxLod` uniform the read needs
/// travels with the texture.
///
/// Assigning it after a material has drawn once needs
/// [`MeshBasicNodeMaterial::set_needs_update`] on that material, exactly as
/// three.js needs `material.needsUpdate = true`: it changes the program,
/// not a uniform.
///
/// [`MeshBasicNodeMaterial::set_needs_update`]: crate::materials::MeshBasicNodeMaterial::set_needs_update
pub environment: Option<crate::materials::environment::PmremHandle>,
/// `scene.environmentRotation` — the rotation `materialEnvRotation` applies
/// to [`Scene::environment`] (or [`Scene::environment_node`]) on every
/// material that has no `envMap` of its own. Three's uniform is
/// `makeRotationFromEuler( rotation ).transpose()`, an object-group `mat4`,
/// so changing it is a uniform write, not a new program.
pub environment_rotation: crate::math::Euler,
/// `scene.environmentNode` set by hand to a graph of `pmremTexture()`s.
/// `NodeManager.getEnvironmentNode()` returns it ahead of the node it would
/// make from [`Scene::environment`], so it wins when both are set. The same
/// rule about [`MeshBasicNodeMaterial::set_needs_update`] applies.
///
/// [`MeshBasicNodeMaterial::set_needs_update`]: crate::materials::MeshBasicNodeMaterial::set_needs_update
pub environment_node: Option<crate::materials::environment::EnvironmentNode>,
/// `scene.fog` — a classic [`Fog`](super::Fog) or
/// [`FogExp2`](super::FogExp2). The renderer turns it into a fog node
/// whose parameters are render-group uniforms (`NodeManager.updateFog()`),
/// so changing a value is a uniform write; changing the *kind* is a new
/// program. [`Scene::fog_node`] wins when both are set, as in three.js.
pub fog: Option<super::SceneFog>,
/// `scene.fogNode`. Read by `NodeMaterial`'s output flow on every material
/// in the scene (rung 5).
pub fog_node: Option<FogNode>,
/// `scene.overrideMaterial` — used to draw every object in the scene with
/// this material instead of its own.
pub override_material: Option<MeshBasicNodeMaterial>,
/// `scene.onBeforeRender( renderer, scene, camera, renderTarget )` —
/// called at the start of every render of this scene, after its matrices
/// and the camera's are updated and before the scene is projected. Not the
/// `on_before_render` of [`Scene::node`]'s `Object3D`: three calls an
/// object's hook per draw, and the scene root is not drawn, so the
/// renderer never calls that one. See [`SceneRenderHook`].
pub on_before_render: Option<SceneRenderHook>,
/// `scene.onAfterRender( renderer, scene, camera, renderTarget )` —
/// called at the end of every render of this scene, after its pass (and
/// its output pass, if any) has been recorded and every object's
/// `on_after_render` has run.
pub on_after_render: Option<SceneRenderHook>,
}
impl Default for Scene {
fn default() -> Self {
let object = Object3D {
object_type: "Scene",
is_scene: true,
..Default::default()
};
Self {
node: object.into_node(),
background: None,
background_blurriness: 0.0,
background_intensity: 1.0,
environment_intensity: 1.0,
environment: None,
environment_rotation: crate::math::Euler::default(),
environment_node: None,
fog: None,
fog_node: None,
override_material: None,
on_before_render: None,
on_after_render: None,
}
}
}
impl Scene {
/// `new Scene()`.
pub fn new() -> Self {
Self::default()
}
/// `Scene.matrixWorld`.
pub fn matrix_world(&self) -> Matrix4 {
self.node.borrow().matrix_world
}
/// `scene.onBeforeRender = function ( renderer, scene, camera,
/// renderTarget ) { ... }` — sets [`Scene::on_before_render`]. Assigning
/// the field works too; this spares spelling out the closure's argument
/// types.
pub fn set_on_before_render(
&mut self,
hook: impl Fn(
&crate::renderer::Renderer,
&Scene,
&dyn crate::cameras::RenderCamera,
Option<&crate::renderer::RenderTarget>,
) + 'static,
) {
self.on_before_render = Some(Box::new(hook));
}
/// `scene.onAfterRender = function ( ... ) { ... }` — sets
/// [`Scene::on_after_render`], as
/// [`set_on_before_render`](Self::set_on_before_render) does.
pub fn set_on_after_render(
&mut self,
hook: impl Fn(
&crate::renderer::Renderer,
&Scene,
&dyn crate::cameras::RenderCamera,
Option<&crate::renderer::RenderTarget>,
) + 'static,
) {
self.on_after_render = Some(Box::new(hook));
}
/// `scene.background = value`.
pub fn set_background(&mut self, background: impl Into<Background>) {
self.background = Some(background.into());
}
/// `scene.add( object )`.
pub fn add(&self, object: &ObjectRef) -> &Self {
self.node.add(object);
self
}
/// `scene.remove( object )`.
pub fn remove(&self, object: &ObjectRef) -> &Self {
self.node.remove(object);
self
}
/// `scene.children`, cloned — the direct children only. The renderer does
/// not use this; it walks the whole tree.
pub fn children(&self) -> Vec<ObjectRef> {
self.node.children()
}
/// `Object3D.updateMatrixWorld()` on the scene root, which is what
/// `Renderer.render()` calls before projecting the scene.
pub fn update_matrix_world(&self) {
self.node.update_matrix_world(false);
}
}