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
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
use super::StandardMaterial;
use crate::math::{Color, Vector2};
use crate::textures::Texture;
use std::sync::Arc;
/// Extended PBR with clearcoat, IOR, transmission, sheen, iridescence and
/// anisotropy layers. Matches three.js's `MeshPhysicalMaterial`.
///
/// All layers below are honored by the renderer. Two notes on fidelity:
///
/// - **Metals need an environment.** At `metalness = 1.0` the BRDF has no
/// diffuse term, so a metal with no `Scene::environment` renders near-black.
/// Set one (see [`crate::extras::PmremGenerator`]) before reaching for gold,
/// silver or foil looks.
/// - **Anisotropy needs UVs.** The tangent frame is derived from UV screen-space
/// derivatives so `anisotropy_rotation` is meaningful in texture space. On a
/// mesh with no UVs it falls back to a position-derived frame, where the
/// streak direction is view-dependent and the rotation is arbitrary.
#[derive(Debug, Clone)]
pub struct PhysicalMaterial {
pub color: Color,
pub emissive: Color,
pub emissive_intensity: f32,
pub roughness: f32,
pub metalness: f32,
pub ao_intensity: f32,
pub normal_scale: Vector2,
/// How far the displacement map pushes, in world units per unit of red.
pub displacement_scale: f32,
/// Constant offset added after scaling — use it to centre a height map
/// whose midpoint is sea level rather than zero.
pub displacement_bias: f32,
pub opacity: f32,
/// three.js `alphaTest`: fragments whose alpha (opacity × map alpha) is
/// below this are discarded. 0 (the default) keeps every fragment.
pub alpha_test: f32,
/// three.js `alphaMap`: its green channel multiplies the opacity, before
/// `alphaTest` (`alphamap_fragment`). Shows only with `transparent` or
/// `alpha_test`, as in three.js.
pub alpha_map: Option<Arc<Texture>>,
/// three.js `envMap`: this material's own image-based light, in place of
/// `scene.environment`.
pub env_map: Option<Arc<crate::textures::CubeTexture>>,
/// three.js `envMapIntensity` (default 1), with `env_map`.
pub env_map_intensity: f32,
/// three.js `envMapRotation` (default zero), with `env_map`.
pub env_map_rotation: crate::math::Euler,
/// three.js `lightMap`: baked irradiance added to the indirect light, times
/// [`light_map_intensity`](Self::light_map_intensity).
pub light_map: Option<Arc<Texture>>,
/// three.js `lightMapIntensity` (default 1).
pub light_map_intensity: f32,
/// three.js `bumpMap`: a height field (red channel) perturbing the normal
/// through its screen-space slope; ignored under a `normal_map`, as in
/// three.js.
pub bump_map: Option<Arc<Texture>>,
/// three.js `bumpScale` (default 1).
pub bump_scale: f32,
/// three.js `transparent`. `Some` is three.js's flag as given — `false`
/// draws opaquely whatever the opacity. `None` (the default) blends when
/// `opacity < 1`, the rule this crate used before it had the flag.
pub transparent: Option<bool>,
pub wireframe: bool,
pub clearcoat: f32,
pub clearcoat_roughness: f32,
pub ior: f32,
pub transmission: f32,
pub thickness: f32,
/// Chromatic dispersion (Abbe-like). 0 = none. Splits the refraction IOR per
/// RGB channel so the screen-space-glass path shows a rainbow edge fringe.
pub dispersion: f32,
/// Per-vertex emission: adds `vertexColor.rgb × vertexColor.a` as emitted
/// light, scaled by this factor (0 = off). A general mechanism for data-baked
/// or decal glow — the alpha channel gates *where* it emits and the rgb sets
/// the color, both authored into the mesh's vertex colors by the app.
pub vertex_emissive: f32,
pub sheen: f32,
pub sheen_color: Color,
pub sheen_roughness: f32,
pub iridescence: f32,
pub iridescence_ior: f32,
/// three.js `iridescenceThicknessRange`: the thin film's thickness in
/// **nanometres**, `[min, max]` (default `[100, 400]`). Without an
/// `iridescence_thickness_map` the film is `max` thick; with one, its
/// green channel runs from `min` to `max`. The thickness sets the hue of
/// the interference — ~100nm reads gold/magenta, ~400nm cyan/blue — and a
/// film of 0 is no film. Only used when `iridescence > 0`.
pub iridescence_thickness_range: [f32; 2],
/// three.js `specularIntensity` (default 1): scales the dielectric
/// specular reflectance and its grazing (F90) reflectance.
pub specular_intensity: f32,
/// three.js `specularColor` (default white): tints the dielectric specular
/// reflectance at normal incidence.
pub specular_color: Color,
/// Anisotropy strength (0 = isotropic). Stretches the specular highlight
/// along the surface tangent for a brushed/streaked look.
pub anisotropy: f32,
/// Anisotropy direction as a rotation (radians) of the tangent in the
/// surface plane.
pub anisotropy_rotation: f32,
/// Distance (world units) over which transmitted light is absorbed down to
/// `attenuation_color`. `INFINITY` (the default) disables volume absorption,
/// in which case transmission falls back to tinting by the base `color` —
/// the historical threers behaviour. Set this finite to opt into physical
/// Beer-Lambert absorption instead.
pub attenuation_distance: f32,
/// The color transmitted light trends toward at `attenuation_distance`.
/// Only used when `attenuation_distance` is finite and positive.
pub attenuation_color: Color,
pub map: Option<Arc<Texture>>,
pub normal_map: Option<Arc<Texture>>,
pub roughness_map: Option<Arc<Texture>>,
pub metalness_map: Option<Arc<Texture>>,
pub ao_map: Option<Arc<Texture>>,
pub emissive_map: Option<Arc<Texture>>,
/// A sphere that can eclipse the sun for this surface: world-space
/// `[x, y, z, radius]`, or `None`.
///
/// Both the sun and the occluder are circles on the sky from any shaded
/// point, so the light lost is the area their discs share — which gives a
/// penumbra for free, and an annular ring when the occluder is smaller than
/// the sun and centred on it. Shadow maps cannot do either at this scale:
/// a map fitted to a planet would not reach a moon sixty radii away.
pub eclipse_occluder: Option<[f32; 4]>,
/// Angular *radius* of the sun in radians, as seen from this body. 0.00465
/// is the Sun from Earth — half a degree across.
pub sun_angular_radius: f32,
/// Cloud map whose alpha casts a shadow onto this surface.
///
/// The shader intersects the sun ray from each shaded point with a shell
/// `cloud_height` above the body and samples the map where it crosses, so
/// the shadow lands offset from the cloud that casts it — further as the
/// sun gets lower, which is what makes a cloud deck read as floating above
/// the ground rather than painted onto it. Assumes the mesh is a sphere
/// centred on its own origin, equirectangularly mapped.
pub cloud_shadow_map: Option<Arc<Texture>>,
/// Height of the cloud shell, as a fraction of the body's radius.
pub cloud_height: f32,
/// How dark the cloud shadow gets, 0 (off) to 1.
pub cloud_shadow: f32,
/// Longitude offset of the cloud shell relative to this surface, in turns.
/// Clouds drift; without this the shadows would be pinned to the ground.
pub cloud_rotation: f32,
/// Forward scattering through a cloud deck. 0 disables it.
///
/// A cloud is not a surface. Sunlight enters the top, bounces between
/// droplets and leaves in a direction strongly biased *forward*, which is
/// why a deck with the sun behind it is far brighter than the same deck lit
/// from behind the camera, and why its edge lights up before its middle
/// does. A Lambert shell cannot do either: it is at its brightest facing
/// the sun and goes flat black past the terminator.
pub cloud_scatter: f32,
/// Henyey-Greenstein asymmetry for that scattering, -1 to 1.
///
/// Cloud droplets are large compared with visible wavelengths, so they
/// scatter hard forward: around 0.8 for water, which is the default.
pub cloud_anisotropy: f32,
/// Width of the twilight wrap, in cosine units. 0 disables it.
///
/// A planet with air is not lit by a hard Lambert terminator: light
/// scatters round the limb and reaches a little way onto the night side,
/// reddened by the length of the path it took.
///
/// Keep it small — around 0.1 for Earth. The wide orange band you see round
/// a night limb from space is the *atmosphere*, which
/// [`AtmosphereMaterial`](crate::AtmosphereMaterial) draws; light reaching
/// the *ground* is down to a four-hundredth of daylight six degrees past
/// the terminator, and gone by eighteen.
pub twilight: f32,
/// Colour of that scattered light — the long path through air reddens it.
pub twilight_color: Color,
/// Height map. Offsets each vertex along its normal by
/// `red * displacement_scale + displacement_bias`, so it moves real
/// geometry rather than faking relief in the shading — which means it needs
/// a mesh dense enough to have vertices where the detail is.
pub displacement_map: Option<Arc<Texture>>,
/// Per-texel thin-film thickness (three.js `iridescenceThicknessMap`).
/// The green channel runs between the two ends of
/// `iridescence_thickness_range`, so a noise or gradient map turns a single
/// hue into an oil-slick sweep.
pub iridescence_thickness_map: Option<Arc<Texture>>,
/// three.js `specularIntensityMap`: its alpha scales `specular_intensity`.
pub specular_intensity_map: Option<Arc<Texture>>,
/// three.js `specularColorMap`: its colour scales `specular_color`.
pub specular_color_map: Option<Arc<Texture>>,
/// three.js `clearcoatMap`: its red scales `clearcoat`.
pub clearcoat_map: Option<Arc<Texture>>,
/// three.js `clearcoatRoughnessMap`: its green scales `clearcoat_roughness`.
pub clearcoat_roughness_map: Option<Arc<Texture>>,
/// three.js `clearcoatNormalMap`: a tangent-space normal for the coat
/// alone, scaled by [`clearcoat_normal_scale`](Self::clearcoat_normal_scale).
pub clearcoat_normal_map: Option<Arc<Texture>>,
/// three.js `clearcoatNormalScale` (default (1, 1)).
pub clearcoat_normal_scale: Vector2,
/// three.js `iridescenceMap`: its red scales `iridescence`.
pub iridescence_map: Option<Arc<Texture>>,
/// three.js `sheenColorMap`: its colour scales `sheen_color`.
pub sheen_color_map: Option<Arc<Texture>>,
/// three.js `sheenRoughnessMap`: its alpha scales `sheen_roughness`.
pub sheen_roughness_map: Option<Arc<Texture>>,
/// three.js `transmissionMap`: its red scales `transmission`.
pub transmission_map: Option<Arc<Texture>>,
/// three.js `thicknessMap`: its green scales `thickness`.
pub thickness_map: Option<Arc<Texture>>,
/// three.js `anisotropyMap`: red and green turn the anisotropy direction
/// (encoded as `2·rg − 1`), blue scales its strength.
pub anisotropy_map: Option<Arc<Texture>>,
pub side: u32,
/// Transparency compositing technique (blend / single-layer glass / OIT).
pub transparency: super::TransparencyMode,
/// three.js `polygonOffset` / `polygonOffsetFactor` / `polygonOffsetUnits`:
/// `Some` enables the depth offset (see [`PolygonOffset`](super::PolygonOffset)).
pub polygon_offset: Option<super::PolygonOffset>,
/// three.js `toneMapped` (default `true`): whether the renderer's tone
/// mapping applies to this material's output.
pub tone_mapped: bool,
/// three.js `depthTest` / `depthWrite` / `depthFunc` / `colorWrite`.
/// Ignored by the glass, order-independent and refraction
/// [`transparency`](Self::transparency) modes, which own their depth state.
pub render_state: super::RenderState,
}
impl Default for PhysicalMaterial {
fn default() -> Self {
Self {
transparency: super::TransparencyMode::default(),
color: Color::WHITE,
emissive: Color::BLACK,
emissive_intensity: 1.0,
roughness: 1.0,
metalness: 0.0,
ao_intensity: 1.0,
normal_scale: Vector2::new(1.0, 1.0),
displacement_scale: 1.0,
displacement_bias: 0.0,
opacity: 1.0,
alpha_test: 0.0,
alpha_map: None,
env_map: None,
env_map_intensity: 1.0,
env_map_rotation: crate::math::Euler::default(),
light_map: None,
light_map_intensity: 1.0,
bump_map: None,
bump_scale: 1.0,
transparent: None,
wireframe: false,
clearcoat: 0.0,
clearcoat_roughness: 0.0,
ior: 1.5,
transmission: 0.0,
thickness: 0.01,
dispersion: 0.0,
vertex_emissive: 0.0,
sheen: 0.0,
sheen_color: Color::BLACK,
sheen_roughness: 1.0,
iridescence: 0.0,
iridescence_ior: 1.3,
iridescence_thickness_range: [100.0, 400.0],
specular_intensity_map: None,
specular_color_map: None,
clearcoat_map: None,
clearcoat_roughness_map: None,
clearcoat_normal_map: None,
iridescence_map: None,
sheen_color_map: None,
sheen_roughness_map: None,
transmission_map: None,
thickness_map: None,
anisotropy_map: None,
clearcoat_normal_scale: Vector2::new(1.0, 1.0),
specular_intensity: 1.0,
specular_color: Color::WHITE,
anisotropy: 0.0,
anisotropy_rotation: 0.0,
attenuation_distance: f32::INFINITY,
attenuation_color: Color::WHITE,
map: None,
normal_map: None,
roughness_map: None,
metalness_map: None,
ao_map: None,
emissive_map: None,
displacement_map: None,
eclipse_occluder: None,
sun_angular_radius: 0.00465,
cloud_shadow_map: None,
cloud_height: 0.012,
cloud_shadow: 0.0,
cloud_scatter: 0.0,
cloud_anisotropy: 0.8,
cloud_rotation: 0.0,
twilight: 0.0,
twilight_color: Color::new(1.0, 0.55, 0.32),
iridescence_thickness_map: None,
side: 0,
polygon_offset: None,
tone_mapped: true,
render_state: super::RenderState::default(),
}
}
}
impl PhysicalMaterial {
pub fn new(color: Color) -> Self {
Self {
color,
..Default::default()
}
}
pub fn with_roughness(mut self, r: f32) -> Self {
self.roughness = r;
self
}
pub fn with_metalness(mut self, m: f32) -> Self {
self.metalness = m;
self
}
pub fn with_emissive(mut self, c: Color, intensity: f32) -> Self {
self.emissive = c;
self.emissive_intensity = intensity;
self
}
/// Clear lacquer / cover-glass layer over the base: `strength` in `[0,1]`.
pub fn with_clearcoat(mut self, strength: f32, roughness: f32) -> Self {
self.clearcoat = strength;
self.clearcoat_roughness = roughness;
self
}
/// Brushed/streaked specular. `strength` in [-1,1] (sign flips the streak
/// axis), `rotation` in radians within the UV tangent plane.
pub fn with_anisotropy(mut self, strength: f32, rotation: f32) -> Self {
self.anisotropy = strength;
self.anisotropy_rotation = rotation;
self
}
/// Retroreflective fabric-style grazing lobe (Charlie distribution).
pub fn with_sheen(mut self, strength: f32, color: Color, roughness: f32) -> Self {
self.sheen = strength;
self.sheen_color = color;
self.sheen_roughness = roughness;
self
}
/// Thin-film interference, `thickness_nm` thick — the top of
/// [`iridescence_thickness_range`](Self::iridescence_thickness_range),
/// which is the film's thickness without a thickness map.
pub fn with_iridescence(mut self, strength: f32, ior: f32, thickness_nm: f32) -> Self {
self.iridescence = strength;
self.iridescence_ior = ior;
self.iridescence_thickness_range[1] = thickness_nm;
self
}
/// three.js `specularIntensity` and `specularColor`.
pub fn with_specular(mut self, intensity: f32, color: Color) -> Self {
self.specular_intensity = intensity;
self.specular_color = color;
self
}
/// See-through refraction. Pair with [`Self::with_attenuation`] for tinted
/// glass and `TransparencyMode::Refract` for the screen-space path.
pub fn with_transmission(mut self, transmission: f32, ior: f32, thickness: f32) -> Self {
self.transmission = transmission;
self.ior = ior;
self.thickness = thickness;
self
}
/// Beer-Lambert volume absorption: transmitted light trends toward `color`
/// over `distance` world units.
pub fn with_attenuation(mut self, color: Color, distance: f32) -> Self {
self.attenuation_color = color;
self.attenuation_distance = distance;
self
}
pub fn with_map(mut self, t: Arc<Texture>) -> Self {
self.map = Some(t);
self
}
pub fn with_normal_map(mut self, t: Arc<Texture>) -> Self {
self.normal_map = Some(t);
self
}
pub fn with_roughness_map(mut self, t: Arc<Texture>) -> Self {
self.roughness_map = Some(t);
self
}
pub fn with_metalness_map(mut self, t: Arc<Texture>) -> Self {
self.metalness_map = Some(t);
self
}
/// Attach a thin-film thickness map; see the field docs.
pub fn with_iridescence_thickness_map(mut self, t: Arc<Texture>) -> Self {
self.iridescence_thickness_map = Some(t);
self
}
pub fn with_transparency(mut self, mode: super::TransparencyMode) -> Self {
self.transparency = mode;
self
}
}
/// A standard material as a physical one with the same parameters, its
/// physical layers (clearcoat, transmission, sheen, …) off — three.js's
/// `MeshPhysicalMaterial` is a `MeshStandardMaterial` with more, so this is
/// that extension at rest: it shades as the standard material did. For a
/// standard surface drawn through a physical-only path (`TransparencyMode`'s
/// single-layer glass): `PhysicalMaterial::from(standard).with_transparency(…)`.
impl From<StandardMaterial> for PhysicalMaterial {
fn from(s: StandardMaterial) -> Self {
PhysicalMaterial {
color: s.color,
emissive: s.emissive,
emissive_intensity: s.emissive_intensity,
roughness: s.roughness,
metalness: s.metalness,
ao_intensity: s.ao_intensity,
normal_scale: s.normal_scale,
displacement_scale: s.displacement_scale,
displacement_bias: s.displacement_bias,
opacity: s.opacity,
alpha_test: s.alpha_test,
alpha_map: s.alpha_map,
env_map: s.env_map,
env_map_intensity: s.env_map_intensity,
env_map_rotation: s.env_map_rotation,
light_map: s.light_map,
light_map_intensity: s.light_map_intensity,
bump_map: s.bump_map,
bump_scale: s.bump_scale,
transparent: s.transparent,
wireframe: s.wireframe,
map: s.map,
normal_map: s.normal_map,
roughness_map: s.roughness_map,
metalness_map: s.metalness_map,
ao_map: s.ao_map,
emissive_map: s.emissive_map,
eclipse_occluder: s.eclipse_occluder,
sun_angular_radius: s.sun_angular_radius,
cloud_shadow_map: s.cloud_shadow_map,
cloud_height: s.cloud_height,
cloud_shadow: s.cloud_shadow,
cloud_rotation: s.cloud_rotation,
cloud_scatter: s.cloud_scatter,
cloud_anisotropy: s.cloud_anisotropy,
twilight: s.twilight,
twilight_color: s.twilight_color,
displacement_map: s.displacement_map,
side: s.side,
polygon_offset: s.polygon_offset,
tone_mapped: s.tone_mapped,
render_state: s.render_state,
..PhysicalMaterial::default()
}
}
}
/// A physical material's standard parameters (its physical layers dropped,
/// `emissive_night_side` at its default) — `From<StandardMaterial>` undone.
impl From<&PhysicalMaterial> for StandardMaterial {
fn from(p: &PhysicalMaterial) -> Self {
StandardMaterial {
color: p.color,
emissive: p.emissive,
emissive_intensity: p.emissive_intensity,
roughness: p.roughness,
metalness: p.metalness,
ao_intensity: p.ao_intensity,
normal_scale: p.normal_scale,
displacement_scale: p.displacement_scale,
displacement_bias: p.displacement_bias,
opacity: p.opacity,
alpha_test: p.alpha_test,
alpha_map: p.alpha_map.clone(),
env_map: p.env_map.clone(),
env_map_intensity: p.env_map_intensity,
env_map_rotation: p.env_map_rotation,
light_map: p.light_map.clone(),
light_map_intensity: p.light_map_intensity,
bump_map: p.bump_map.clone(),
bump_scale: p.bump_scale,
transparent: p.transparent,
wireframe: p.wireframe,
map: p.map.clone(),
normal_map: p.normal_map.clone(),
roughness_map: p.roughness_map.clone(),
metalness_map: p.metalness_map.clone(),
ao_map: p.ao_map.clone(),
emissive_map: p.emissive_map.clone(),
eclipse_occluder: p.eclipse_occluder,
sun_angular_radius: p.sun_angular_radius,
cloud_shadow_map: p.cloud_shadow_map.clone(),
cloud_height: p.cloud_height,
cloud_shadow: p.cloud_shadow,
cloud_rotation: p.cloud_rotation,
cloud_scatter: p.cloud_scatter,
cloud_anisotropy: p.cloud_anisotropy,
twilight: p.twilight,
twilight_color: p.twilight_color,
displacement_map: p.displacement_map.clone(),
side: p.side,
polygon_offset: p.polygon_offset,
tone_mapped: p.tone_mapped,
render_state: p.render_state,
..StandardMaterial::default()
}
}
}
#[cfg(test)]
mod conversion_tests {
use super::*;
#[test]
fn standard_round_trips_through_physical() {
let mut s = StandardMaterial::new(Color::new(0.2, 0.4, 0.6))
.with_roughness(0.3)
.with_metalness(0.7);
s.opacity = 0.35;
s.transparent = Some(true);
let p = PhysicalMaterial::from(s.clone());
assert_eq!(p.color, s.color);
assert_eq!(p.roughness, 0.3);
assert_eq!(p.opacity, 0.35);
assert_eq!(p.transparent, Some(true));
// its physical layers at rest
assert_eq!(p.clearcoat, PhysicalMaterial::default().clearcoat);
assert_eq!(p.transmission, PhysicalMaterial::default().transmission);
let back = StandardMaterial::from(&p);
assert_eq!(back.color, s.color);
assert_eq!(back.metalness, 0.7);
assert_eq!(back.opacity, 0.35);
assert_eq!(back.side, s.side);
}
}