@pacem/pacem-3d 2.0.0-goldbach → 2.0.0-hadamard

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -37,14 +37,31 @@ declare class AdapterUtils {
37
37
  clipPixel(evt: PointerEventLike, viewport: Rect): Point;
38
38
  }
39
39
 
40
+ /**
41
+ * How the alpha of a physically-based material (color alpha × {@link Material.opacity} × base color map alpha ×
42
+ * opacity map luminance) is interpreted, after the glTF `alphaMode`:
43
+ * - `'opaque'`: alpha is ignored, the surface is fully opaque;
44
+ * - `'blend'`: the surface is translucent, alpha blends it over what lies behind;
45
+ * - `'mask'`: cutout, the surface is fully opaque where alpha reaches the alpha cutoff and invisible elsewhere.
46
+ */
47
+ declare type AlphaMode = 'opaque' | 'blend' | 'mask';
48
+
40
49
  /** A {@link Material} using the unlit ("basic") shading model: rendered at flat {@link Material.color}, unaffected by scene lighting. */
41
50
  declare interface BasicMaterial extends Material {
42
51
  readonly shader: KnownShader.Basic;
43
52
  }
44
53
 
45
- /** `<pacem-3d-material-basic>`: produces a {@link BasicMaterial} (unlit shading model): rendered at flat color, unaffected by scene lighting. */
54
+ /**
55
+ * `<pacem-3d-material-basic>`: produces a {@link BasicMaterial}: its color (and texture), display-referred, shaded by
56
+ * the scene lights with a simple half-Lambert diffuse (WebGPU adapter), or unshaded when there are none.
57
+ */
46
58
  declare class BasicMaterialElement extends MaterialElement {
47
59
  constructor();
60
+ /** Builds the {@link BasicMaterial}, adding {@link flatShading} to the base {@link Material}. */
61
+ protected createMaterial(): Promise<Material>;
62
+ propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
63
+ /** Gets or sets whether each face is lit as flat (faceted), whatever the mesh normals. */
64
+ flatShading: boolean;
48
65
  }
49
66
 
50
67
  /** Converts an attribute string to/from either a `boolean` (`"true"`/`"false"`) or a `number`. */
@@ -93,9 +110,11 @@ declare function computePlaneNormal(a: Vector3D, b: Vector3D, c: Vector3D): Vect
93
110
  */
94
111
  declare function computeSharpVertexNormals(geometry: MeshGeometry): void;
95
112
 
113
+ declare function convertToSmoothness(value: boolean | number): any;
114
+
96
115
  /** A {@link Material} whose shading model accounts for diffuse (matte) reflection of scene lighting. */
97
116
  declare interface DiffuseMaterial extends Material {
98
- /** Diffuse color, albedo. */
117
+ /** Emissive color: light the surface gives off by itself, regardless of the scene lighting (the albedo is {@link Material.color}). */
99
118
  emissiveColor?: string;
100
119
  /** Percentage of reflected light. */
101
120
  reflectivity?: number;
@@ -129,6 +148,8 @@ declare namespace Drawing3D {
129
148
  isMeshGeometry,
130
149
  isGroup,
131
150
  computeSharpVertexNormals,
151
+ subdivideTriangles,
152
+ smoothVertexNormals,
132
153
  computePlaneNormal,
133
154
  isInteraction,
134
155
  Vector3D,
@@ -145,6 +166,7 @@ declare namespace Drawing3D {
145
166
  PerspectiveCamera,
146
167
  Light,
147
168
  Mesh,
169
+ OutlineUnits,
148
170
  Group,
149
171
  DragEventArgs,
150
172
  UI3DEvent,
@@ -167,6 +189,7 @@ declare namespace Drawing3D {
167
189
  MeshGeometry,
168
190
  LineGeometry,
169
191
  NotifyChange,
192
+ convertToSmoothness,
170
193
  Point3DConverter,
171
194
  Point3DOrNumberConverter,
172
195
  QuaternionConverter,
@@ -177,6 +200,7 @@ declare namespace Drawing3D {
177
200
  isLambertMaterial,
178
201
  isPhongMaterial,
179
202
  isStandardMaterial,
203
+ isPhysicalMaterial,
180
204
  isShaderMaterial,
181
205
  KnownShader,
182
206
  Material,
@@ -186,9 +210,14 @@ declare namespace Drawing3D {
186
210
  LambertMaterial,
187
211
  SpecularMaterial,
188
212
  PhongMaterial,
213
+ AlphaMode,
214
+ StandardMaterialProperties,
189
215
  StandardMaterial,
216
+ PhysicalMaterial,
190
217
  ShaderMaterial,
191
- MaterialElement
218
+ MaterialElement,
219
+ HdrImage,
220
+ RadianceHdrParser
192
221
  }
193
222
  }
194
223
  export { Drawing3D }
@@ -207,6 +236,8 @@ declare namespace Drawing3D_2 {
207
236
  isMeshGeometry,
208
237
  isGroup,
209
238
  computeSharpVertexNormals,
239
+ subdivideTriangles,
240
+ smoothVertexNormals,
210
241
  computePlaneNormal,
211
242
  isInteraction,
212
243
  Vector3D,
@@ -223,6 +254,7 @@ declare namespace Drawing3D_2 {
223
254
  PerspectiveCamera,
224
255
  Light,
225
256
  Mesh,
257
+ OutlineUnits,
226
258
  Group,
227
259
  DragEventArgs,
228
260
  UI3DEvent,
@@ -248,6 +280,7 @@ declare namespace Drawing3D_2 {
248
280
  isLambertMaterial,
249
281
  isPhongMaterial,
250
282
  isStandardMaterial,
283
+ isPhysicalMaterial,
251
284
  isShaderMaterial,
252
285
  KnownShader,
253
286
  Material,
@@ -257,14 +290,19 @@ declare namespace Drawing3D_2 {
257
290
  LambertMaterial,
258
291
  SpecularMaterial,
259
292
  PhongMaterial,
293
+ AlphaMode,
294
+ StandardMaterialProperties,
260
295
  StandardMaterial,
296
+ PhysicalMaterial,
261
297
  ShaderMaterial,
262
298
  MaterialElement,
263
299
  BasicMaterialElement,
264
300
  LambertMaterialElement,
265
301
  LineMaterialElement,
266
302
  PhongMaterialElement,
303
+ StandardMaterialBaseElement,
267
304
  StandardMaterialElement,
305
+ PhysicalMaterialElement,
268
306
  Pacem3DPrimitiveElement,
269
307
  PacemBoxElement,
270
308
  PacemConeElement,
@@ -301,6 +339,16 @@ declare interface Group extends Ui3DObject {
301
339
  childRenderables: Renderable[];
302
340
  }
303
341
 
342
+ /** A decoded high dynamic range image: linear RGB radiance, top row first. */
343
+ declare interface HdrImage {
344
+ /** Width, in pixels. */
345
+ width: number;
346
+ /** Height, in pixels. */
347
+ height: number;
348
+ /** Linear RGB triplets (`3 × width × height` floats, unbounded), row by row from the top-left corner. */
349
+ data: Float32Array;
350
+ }
351
+
304
352
  /** Snapshot of the current pointer/viewport interaction state, as consumed by a WebGPU render pass for hit-testing/uniforms. */
305
353
  declare interface Interaction {
306
354
  /** Timestamp (as returned by `performance.now()`) of the current frame. */
@@ -351,6 +399,9 @@ declare function isPerspectiveCamera(object: any): object is PerspectiveCamera;
351
399
  /** Type guard checking whether `obj` implements the {@link PhongMaterial} contract. */
352
400
  declare function isPhongMaterial(obj: any): obj is PhongMaterial;
353
401
 
402
+ /** Type guard checking whether `obj` implements the {@link PhysicalMaterial} contract. */
403
+ declare function isPhysicalMaterial(obj: any): obj is PhysicalMaterial;
404
+
354
405
  /** Type guard checking whether `object` implements the {@link Renderable} contract (i.e. it is attached to a valid {@link Stage}). */
355
406
  declare function isRenderable(object: any): object is Renderable;
356
407
 
@@ -372,6 +423,7 @@ declare enum KnownShader {
372
423
  Lambert = "lambert",
373
424
  Phong = "phong",
374
425
  Standard = "standard",
426
+ Physical = "physical",
375
427
  Line = "line",
376
428
  Custom = "custom"
377
429
  }
@@ -395,16 +447,20 @@ declare class LambertMaterialElement extends MaterialElement {
395
447
  refractionRatio: number;
396
448
  }
397
449
 
398
- /** A {@link Renderable} light source (spot, directional, point/omni or ambient), as produced by {@link Pacem3DLightElement}. */
450
+ /** A {@link Renderable} light source (spot, directional, point/omni, ambient or environment), as produced by {@link Pacem3DLightElement}. */
399
451
  declare interface Light extends Renderable {
400
452
  /** Gets or sets the light intensity/brightness. */
401
453
  intensity: number;
402
454
  /** Gets or sets the point the light is aimed at (spotlight-specific). */
403
455
  target?: Vector3D;
404
- /** Gets or sets the light color. */
456
+ /** Gets or sets the light color (a tint, for an environment light). */
405
457
  color: string;
406
458
  /** Gets or sets the kind of light source. */
407
- type: 'spot' | 'direction' | 'omni' | 'ambient';
459
+ type: 'spot' | 'direction' | 'omni' | 'ambient' | 'environment';
460
+ /** URL of the equirectangular Radiance HDR (`.hdr`) image lighting the scene from every direction (environment-specific). */
461
+ map?: string;
462
+ /** Rotation of the environment around the vertical (`y`) axis, in degrees (environment-specific). */
463
+ rotation?: number;
408
464
  /** Distance at which the spotlight intensity starts to fall off (spotlight-specific). */
409
465
  attenuationStart?: number;
410
466
  /** Distance beyond which the spotlight has no effect (spotlight-specific). */
@@ -478,7 +534,7 @@ declare interface Material {
478
534
 
479
535
  /**
480
536
  * Abstract base of the declarative material custom elements — {@link BasicMaterialElement}, {@link LambertMaterialElement},
481
- * {@link LineMaterialElement}, {@link PhongMaterialElement} and {@link StandardMaterialElement} — that assemble a
537
+ * {@link LineMaterialElement}, {@link PhongMaterialElement}, {@link StandardMaterialElement} and {@link PhysicalMaterialElement} — that assemble a
482
538
  * {@link Material} (with its `shader`-specific extra properties) out of shared and shader-specific watched attributes,
483
539
  * ready to be assigned to a `Pacem3DMeshElement`'s `material`/`backMaterial` property.
484
540
  */
@@ -488,7 +544,16 @@ declare abstract class MaterialElement extends PacemEventTarget {
488
544
  constructor(shader: KnownShader);
489
545
  /** Gets the shading model this element produces materials for. */
490
546
  get shader(): KnownShader;
491
- private _loadMap;
547
+ /**
548
+ * Loads `url` into an {@link ImageBitmap}; resolves to `null` when `url` is empty or can't be loaded. An unchanged
549
+ * map (`url` equal to the `currentUrl` the `current` bitmap was loaded from) is reused rather than fetched and
550
+ * decoded again. Nothing gets closed here: the bitmaps a published material stops holding are closed by
551
+ * {@link updateMaterial}, once the new material is out.
552
+ * @param url The url of the map to load.
553
+ * @param currentUrl The url of the same map in the current {@link material}.
554
+ * @param current The bitmap of the same map in the current {@link material}.
555
+ */
556
+ protected loadBitmap(url: string, currentUrl: string, current: ImageBitmap): Promise<ImageBitmap>;
492
557
  /** Gets or sets the computed {@link Material}, recomputed by {@link updateMaterial} whenever a shading attribute changes. */
493
558
  material: Material;
494
559
  /** Gets or sets the opacity, from `0` (fully transparent) to `1` (fully opaque). */
@@ -503,7 +568,14 @@ declare abstract class MaterialElement extends PacemEventTarget {
503
568
  map?: string;
504
569
  propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
505
570
  viewActivatedCallback(): void;
506
- /** Recomputes {@link material} via {@link createMaterial}, flagging it as {@link StalePropertyFlag.Material}. */
571
+ /**
572
+ * Recomputes {@link material} via {@link createMaterial}, flagging it as {@link StalePropertyFlag.Material}.
573
+ *
574
+ * Debounced to one call per animation frame, so that several attributes changing together (e.g. a preset) make a
575
+ * single update. Since {@link createMaterial} is asynchronous (maps get fetched), updates may still complete out of
576
+ * order: a result superseded by a newer update is dropped, otherwise a slow, stale one (say, still holding a map
577
+ * that has been removed meanwhile) would overwrite the latest. Bitmaps nobody holds anymore get closed.
578
+ */
507
579
  protected updateMaterial(): void;
508
580
  /** Builds the base {@link Material} out of the shared watched attributes (`opacity`, `wireframe`, `color`, `hide`, `map`); overridden by subclasses to add their shader-specific properties. */
509
581
  protected createMaterial(): Promise<Material>;
@@ -524,6 +596,12 @@ declare interface Mesh extends Ui3DObject {
524
596
  castShadow?: boolean;
525
597
  /** Gets or sets whether the mesh gets darkened by the shadows of the other meshes (defaults to `true`). */
526
598
  receiveShadow?: boolean;
599
+ /** Gets or sets the color of the outline (inverted hull) drawn around the mesh (black by default). */
600
+ outlineColor?: string;
601
+ /** Gets or sets the outline thickness, in {@link outlineUnits}; `0` (default) draws no outline. */
602
+ outlineWidth?: number;
603
+ /** Gets or sets the unit of {@link outlineWidth} (`'world'` by default). */
604
+ outlineUnits?: OutlineUnits;
527
605
  }
528
606
 
529
607
  /** A {@link NodeGeometry} for triangulated surfaces: adds triangle vertex indices, per-vertex UV texture coordinates and normals. */
@@ -621,8 +699,13 @@ declare class OrbitCameraBehavior {
621
699
  get configuration(): OrbitCameraConfiguration;
622
700
  set configuration(v: OrbitCameraConfiguration);
623
701
  private _startHandler;
702
+ private _mouseDownHandler;
624
703
  private _avoidHandler;
704
+ /** Swallows the click that follows an orbit drag, so that it doesn't reach the hovered item. */
705
+ private _clickHandler;
706
+ private _releaseClick;
625
707
  private _endHandler;
708
+ private _trackDrag;
626
709
  private _zoomHandler;
627
710
  private _moveHandler;
628
711
  private _getSafeAzimuth;
@@ -665,6 +748,12 @@ declare interface OrthographicCamera extends Camera {
665
748
  right: number;
666
749
  }
667
750
 
751
+ /**
752
+ * Unit of a {@link Mesh.outlineWidth}: `'world'` pushes the outline hull out by that many world units (thicker
753
+ * lines on bigger objects, thinner with the distance), `'pixels'` keeps the line that many pixels wide on screen.
754
+ */
755
+ declare type OutlineUnits = 'world' | 'pixels';
756
+
668
757
  /**
669
758
  * Pluggable rendering-backend contract assignable to a {@link Pacem3DElement}'s `adapter` property. Concrete adapters
670
759
  * ({@link Pacem3DThreeAdapterElement} for Three.js/WebGL, {@link Pacem3DWebgpuAdapterElement} for WebGPU) are
@@ -829,16 +918,25 @@ declare class Pacem3DGroupElement extends Ui3DElement implements Group {
829
918
  propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
830
919
  }
831
920
 
832
- /** `<pacem-3d-light>`: a {@link RenderableElement} light source (point/omni, spot or directional) illuminating the scene. */
921
+ /**
922
+ * `<pacem-3d-light>`: a {@link RenderableElement} light source (point/omni, spot, directional, ambient or environment)
923
+ * illuminating the scene. An `environment` light (image-based lighting, WebGPU adapter) lights the scene out of the
924
+ * equirectangular HDR image at {@link map}: diffuse light from every direction plus reflections that blur with the
925
+ * surface roughness; one per scene.
926
+ */
833
927
  declare class Pacem3DLightElement extends RenderableElement implements Light {
834
928
  /** Gets or sets the light intensity/brightness. */
835
929
  intensity: number;
836
930
  /** Gets or sets the point the light is aimed at (spotlight-specific). */
837
931
  target: Vector3D;
838
- /** Gets or sets the light color. */
932
+ /** Gets or sets the light color (a tint, for an environment light). */
839
933
  color: string;
840
934
  /** Gets or sets the kind of light source. */
841
- type: 'spot' | 'direction' | 'omni';
935
+ type: 'spot' | 'direction' | 'omni' | 'ambient' | 'environment';
936
+ /** Gets or sets the URL of the equirectangular Radiance HDR (`.hdr`) image of an environment light. */
937
+ map: string;
938
+ /** Gets or sets the rotation of an environment light around the vertical (`y`) axis, in degrees (`0` by default). */
939
+ rotation: number;
842
940
  /** Gets or sets whether the light casts shadows (directional and omni lights, WebGPU adapter). */
843
941
  castShadow: boolean;
844
942
  /** Gets or sets the side, in texels, of the light's shadow map. */
@@ -860,6 +958,12 @@ declare class Pacem3DMeshElement extends Ui3DElement implements Mesh {
860
958
  castShadow: boolean;
861
959
  /** Gets or sets whether the mesh gets darkened by the shadows of the other meshes. */
862
960
  receiveShadow: boolean;
961
+ /** Gets or sets the color of the outline drawn around the mesh (black by default). */
962
+ outlineColor: string;
963
+ /** Gets or sets the outline thickness, in {@link outlineUnits}; `0` (default) draws no outline. */
964
+ outlineWidth: number;
965
+ /** Gets or sets the unit of {@link outlineWidth}: `'world'` (default) or `'pixels'`. */
966
+ outlineUnits: OutlineUnits;
863
967
  propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
864
968
  }
865
969
 
@@ -907,9 +1011,18 @@ declare class Pacem3DPerspectiveCameraElement extends Pacem3DCameraElement imple
907
1011
  * own shape parameters, ready to be assigned to a `Pacem3DMeshElement`'s `geometry` property.
908
1012
  */
909
1013
  declare abstract class Pacem3DPrimitiveElement extends PacemEventTarget {
1014
+ #private;
910
1015
  /** Gets or sets the computed vertex/index data describing the primitive's shape. */
911
1016
  geometry: NodeGeometry;
912
1017
  viewActivatedCallback(): void;
1018
+ /**
1019
+ * Schedules {@link geometry} to be rebuilt (see {@link buildGeometry}) in a microtask: shape parameters changed
1020
+ * together (e.g. every attribute of the markup at upgrade time) produce a single build and a single `geometry`
1021
+ * change, rather than one per parameter.
1022
+ */
1023
+ protected invalidateGeometry(): void;
1024
+ /** Computes the geometry of the current shape parameters (called by {@link invalidateGeometry}). */
1025
+ protected abstract buildGeometry(): NodeGeometry;
913
1026
  /** Computes the geometry to fall back to when {@link geometry} hasn't been explicitly set. */
914
1027
  protected abstract createDefaultGeometry(): NodeGeometry;
915
1028
  }
@@ -997,6 +1110,14 @@ declare class Pacem3DWebgpuAdapterElement extends Pacem3DAdapterElement implemen
997
1110
  * Reassigning it reinitializes the renderer(s).
998
1111
  */
999
1112
  reversedZ: boolean;
1113
+ /**
1114
+ * Gets or sets how the linear color of physically-based (standard) materials is compressed into the displayable
1115
+ * range: `'neutral'` (default, Khronos PBR Neutral), `'aces'` (filmic) or `'none'` (clamp). Basic and line
1116
+ * materials are unaffected. Reassigning it reinitializes the renderer(s).
1117
+ */
1118
+ toneMapping: ToneMappingMode;
1119
+ /** Gets or sets the exposure (linear multiplier, `1` by default) of physically-based (standard) materials, applied before tone mapping. Reassigning it reinitializes the renderer(s). */
1120
+ exposure: number;
1000
1121
  private _ensureRenderer;
1001
1122
  private _updatePipeline;
1002
1123
  /**
@@ -1050,6 +1171,8 @@ declare class PacemBoxElement extends Pacem3DPrimitiveElement {
1050
1171
  static createMeshGeometry(width?: number, height?: number, depth?: number, widthSegments?: number, heightSegments?: number, depthSegments?: number): MeshGeometry;
1051
1172
  /** Computes the box geometry from the default (unset) shape parameters. */
1052
1173
  protected createDefaultGeometry(): MeshGeometry;
1174
+ /** Computes the box geometry from the current shape parameters. */
1175
+ protected buildGeometry(): MeshGeometry;
1053
1176
  propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
1054
1177
  }
1055
1178
 
@@ -1065,10 +1188,18 @@ declare class PacemConeElement extends Pacem3DPrimitiveElement {
1065
1188
  heightSegments: number;
1066
1189
  /** Gets or sets the number of concentric ring subdivisions of the base cap. */
1067
1190
  capSegments: number;
1068
- /** Builds the {@link MeshGeometry} of a cone with the given base radius, height, side count, lateral-surface segments and base-cap segments. */
1069
- static createMeshGeometry(radius?: number, height?: number, sides?: number, heightSegments?: number, capSegments?: number): MeshGeometry;
1191
+ /** Gets or sets how round the lateral surface looks, from `0` (faceted) to `1` (smooth); `true`/`false` mean `1`/`0`. Unset (or the bare attribute) means `1`, smooth. The base stays flat. */
1192
+ smooth: number | boolean;
1193
+ /**
1194
+ * Builds the {@link MeshGeometry} of a cone with the given base radius, height, side count, lateral-surface segments
1195
+ * and base-cap segments, the normals of its lateral surface blended from the faces' towards the exact ones by
1196
+ * `smooth` (`0`, faceted, by default).
1197
+ */
1198
+ static createMeshGeometry(radius?: number, height?: number, sides?: number, heightSegments?: number, capSegments?: number, smooth?: number | boolean): MeshGeometry;
1070
1199
  /** Computes the cone geometry from the default (unset) shape parameters. */
1071
1200
  protected createDefaultGeometry(): MeshGeometry;
1201
+ /** Computes the cone geometry from the current shape parameters. */
1202
+ protected buildGeometry(): MeshGeometry;
1072
1203
  propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
1073
1204
  }
1074
1205
 
@@ -1084,10 +1215,18 @@ declare class PacemCylinderElement extends Pacem3DPrimitiveElement {
1084
1215
  heightSegments: number;
1085
1216
  /** Gets or sets the number of concentric ring subdivisions of each cap. */
1086
1217
  capSegments: number;
1087
- /** Builds the {@link MeshGeometry} of a cylinder with the given radius, height, side count, lateral-surface segments and cap segments. */
1088
- static createMeshGeometry(radius?: number, height?: number, sides?: number, heightSegments?: number, capSegments?: number): MeshGeometry;
1218
+ /** Gets or sets how round the lateral surface looks, from `0` (faceted) to `1` (smooth); `true`/`false` mean `1`/`0`. Unset (or the bare attribute) means `1`, smooth. The caps stay flat. */
1219
+ smooth: number | boolean;
1220
+ /**
1221
+ * Builds the {@link MeshGeometry} of a cylinder with the given radius, height, side count, lateral-surface segments
1222
+ * and cap segments, the normals of its lateral surface blended from the faces' towards the exact ones (horizontal,
1223
+ * radial) by `smooth` (`0`, faceted, by default).
1224
+ */
1225
+ static createMeshGeometry(radius?: number, height?: number, sides?: number, heightSegments?: number, capSegments?: number, smooth?: number | boolean): MeshGeometry;
1089
1226
  /** Computes the cylinder geometry from the default (unset) shape parameters. */
1090
1227
  protected createDefaultGeometry(): MeshGeometry;
1228
+ /** Computes the cylinder geometry from the current shape parameters. */
1229
+ protected buildGeometry(): MeshGeometry;
1091
1230
  propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
1092
1231
  }
1093
1232
 
@@ -1120,6 +1259,8 @@ declare class PacemLineElement extends Pacem3DPrimitiveElement {
1120
1259
  static createLineGeometry(positions?: Vector3D[]): LineGeometry;
1121
1260
  /** Computes the line geometry from the default (unset) vertex positions. */
1122
1261
  protected createDefaultGeometry(): LineGeometry;
1262
+ /** Computes the line geometry from the current vertex positions. */
1263
+ protected buildGeometry(): LineGeometry;
1123
1264
  propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
1124
1265
  }
1125
1266
 
@@ -1176,6 +1317,8 @@ declare class PacemPlaneElement extends Pacem3DPrimitiveElement {
1176
1317
  static createMeshGeometry(width?: number, length?: number, widthSegments?: number, lengthSegments?: number): MeshGeometry;
1177
1318
  /** Computes the plane geometry from the default (unset) shape parameters. */
1178
1319
  protected createDefaultGeometry(): MeshGeometry;
1320
+ /** Computes the plane geometry from the current shape parameters. */
1321
+ protected buildGeometry(): MeshGeometry;
1179
1322
  propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
1180
1323
  }
1181
1324
 
@@ -1185,10 +1328,17 @@ declare class PacemSphereElement extends Pacem3DPrimitiveElement {
1185
1328
  radius: number;
1186
1329
  /** Gets or sets the tessellation: the number of longitude divisions (and, derived from it, the latitude bands) around the sphere. */
1187
1330
  segments: number;
1188
- /** Builds the {@link MeshGeometry} of a sphere with the given radius (defaults to `1`) and tessellation (defaults to `8`). */
1189
- static createMeshGeometry(radius?: number, segs?: number): MeshGeometry;
1331
+ /** Gets or sets how round the surface looks, from `0` (faceted) to `1` (smooth); `true`/`false` mean `1`/`0`. Unset (or the bare attribute) means `1`, smooth. */
1332
+ smooth: number | boolean;
1333
+ /**
1334
+ * Builds the {@link MeshGeometry} of a sphere with the given radius (defaults to `1`) and tessellation (defaults to
1335
+ * `8`), its normals blended from the faces' towards the exact ones (radial) by `smooth` (`0`, faceted, by default).
1336
+ */
1337
+ static createMeshGeometry(radius?: number, segs?: number, smooth?: number | boolean): MeshGeometry;
1190
1338
  /** Computes the sphere geometry from the default (unset) shape parameters. */
1191
1339
  protected createDefaultGeometry(): MeshGeometry;
1340
+ /** Computes the sphere geometry from the current shape parameters. */
1341
+ protected buildGeometry(): MeshGeometry;
1192
1342
  propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
1193
1343
  }
1194
1344
 
@@ -1209,10 +1359,18 @@ declare class PacemTorusElement extends Pacem3DPrimitiveElement {
1209
1359
  segments: number;
1210
1360
  /** Gets or sets the number of segments around the tube's circular cross-section. */
1211
1361
  sides: number;
1212
- /** Builds the {@link MeshGeometry} of a torus with the given outer/inner radii and ring/tube segment counts. */
1213
- static createMeshGeometry(radius?: number, innerRadius?: number, segments?: number, sides?: number): MeshGeometry;
1362
+ /** Gets or sets how round the surface looks, from `0` (faceted) to `1` (smooth); `true`/`false` mean `1`/`0`. Unset (or the bare attribute) means `1`, smooth. */
1363
+ smooth: number | boolean;
1364
+ /**
1365
+ * Builds the {@link MeshGeometry} of a torus with the given outer/inner radii and ring/tube segment counts, its
1366
+ * normals blended from the faces' towards the exact ones (away from the tube's center circle) by `smooth` (`0`,
1367
+ * faceted, by default).
1368
+ */
1369
+ static createMeshGeometry(radius?: number, innerRadius?: number, segments?: number, sides?: number, smooth?: number | boolean): MeshGeometry;
1214
1370
  /** Computes the torus geometry from the default (unset) shape parameters. */
1215
1371
  protected createDefaultGeometry(): MeshGeometry;
1372
+ /** Computes the torus geometry from the current shape parameters. */
1373
+ protected buildGeometry(): MeshGeometry;
1216
1374
  propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
1217
1375
  }
1218
1376
 
@@ -1250,6 +1408,39 @@ declare class PhongMaterialElement extends MaterialElement {
1250
1408
  flatShading: boolean;
1251
1409
  }
1252
1410
 
1411
+ /** A {@link StandardMaterialProperties} material extended with the glTF `KHR_materials_ior`, `KHR_materials_transmission` and `KHR_materials_volume` properties (glass, water, gems...). */
1412
+ declare interface PhysicalMaterial extends StandardMaterialProperties {
1413
+ readonly shader: KnownShader.Physical;
1414
+ /** Index of refraction, deciding both the reflectance at normal incidence (`((ior - 1) / (ior + 1))²`) and how transmitted light bends; `1.5` by default. */
1415
+ ior?: number;
1416
+ /** Fraction of the light transmitted through the surface instead of being diffused, from `0` (opaque, default) to `1` (fully transmissive). */
1417
+ transmission?: number;
1418
+ /** Thickness of the volume beneath the surface, in local units, used to offset the refracted view and to attenuate the transmitted light; `0` (thin-walled) by default. */
1419
+ thickness?: number;
1420
+ /** Color that white light turns into after traveling {@link attenuationDistance} through the volume; white by default. */
1421
+ attenuationColor?: string;
1422
+ /** Distance the light travels through the volume before turning into {@link attenuationColor}; `Infinity` (no attenuation) by default. */
1423
+ attenuationDistance?: number;
1424
+ }
1425
+
1426
+ /** `<pacem-3d-material-physical>`: produces a {@link PhysicalMaterial}, a {@link StandardMaterialElement} extended with index of refraction, transmission and volume (glTF `KHR_materials_ior`, `KHR_materials_transmission`, `KHR_materials_volume`). */
1427
+ declare class PhysicalMaterialElement extends StandardMaterialBaseElement {
1428
+ constructor();
1429
+ /** Builds the {@link PhysicalMaterial}, adding the index of refraction, transmission and volume properties to the standard ones. */
1430
+ protected createMaterial(): Promise<PhysicalMaterial>;
1431
+ propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
1432
+ /** Gets or sets the index of refraction, deciding both the reflectance at normal incidence and how transmitted light bends (`1.5` by default). */
1433
+ ior: number;
1434
+ /** Gets or sets the fraction of the light transmitted through the surface, from `0` (opaque, default) to `1` (fully transmissive). */
1435
+ transmission: number;
1436
+ /** Gets or sets the thickness of the volume beneath the surface, in local units (`0`, thin-walled, by default). */
1437
+ thickness: number;
1438
+ /** Gets or sets the color white light turns into after traveling {@link attenuationDistance} through the volume (white by default). */
1439
+ attenuationColor: string;
1440
+ /** Gets or sets the distance the light travels through the volume before turning into {@link attenuationColor} (`Infinity`, no attenuation, by default). */
1441
+ attenuationDistance: number;
1442
+ }
1443
+
1253
1444
  /** Converts a `"x y z"` attribute string to/from a {@link Vector3D}. */
1254
1445
  declare const Point3DConverter: PropertyConverter;
1255
1446
 
@@ -1267,10 +1458,18 @@ declare type PointerEventLike = MouseEvent | PointerEvent | TouchEvent;
1267
1458
  declare abstract class PolyhedronElement extends Pacem3DPrimitiveElement {
1268
1459
  /** Gets or sets the radius of the sphere the polyhedron's vertices lie on. */
1269
1460
  radius: number;
1461
+ /**
1462
+ * Gets or sets in how many segments each edge is divided (`1`, the plain solid, by default): every triangle becomes
1463
+ * `segments²` smaller ones, the faces staying flat. Gives displacement maps vertices to move.
1464
+ */
1465
+ segments: number;
1270
1466
  propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
1271
- private _assignMeshGeometry;
1467
+ /** Computes the polyhedron geometry from the current {@link radius} (`1` when not positive) and {@link segments}. */
1468
+ protected buildGeometry(): MeshGeometry;
1272
1469
  /** Computes the polyhedron geometry using a radius of `1` when {@link radius} hasn't been explicitly set. */
1273
1470
  protected createDefaultGeometry(): MeshGeometry;
1471
+ /** `geometry` with its edges divided into {@link segments} parts (see {@link subdivideTriangles}), or itself when not subdivided. */
1472
+ private _segmented;
1274
1473
  /** Computes the {@link MeshGeometry} of the polyhedron with the given radius. */
1275
1474
  protected abstract createMeshGeometry(radius: number): MeshGeometry;
1276
1475
  }
@@ -1281,6 +1480,39 @@ declare type Quaternion = Geometry.LinearAlgebra.Quaternion;
1281
1480
  /** Converts a `"x y z w"` attribute string to/from a {@link Quaternion}. Used e.g. for `rotate`. */
1282
1481
  declare const QuaternionConverter: PropertyConverter;
1283
1482
 
1483
+ /**
1484
+ * Decoder of Radiance HDR (`.hdr`, a.k.a. RGBE) images, the common format of the equirectangular environment maps
1485
+ * used for image-based lighting: every pixel stores three 8-bit mantissas sharing one exponent byte.
1486
+ *
1487
+ * Supports the `32-bit_rle_rgbe` format with "new" run-length encoded scanlines and flat (uncompressed) ones, in the
1488
+ * standard `-Y height +X width` orientation (and its `+Y` bottom-up variant, flipped to top row first). The `EXPOSURE`
1489
+ * header is ignored: values are returned as stored.
1490
+ */
1491
+ declare class RadianceHdrParser {
1492
+ /**
1493
+ * Fetches and decodes the `.hdr` image at `url`.
1494
+ * @returns A promise resolving with the decoded {@link HdrImage}, or `null` if the fetch response was not OK.
1495
+ */
1496
+ static load(url: string): Promise<HdrImage>;
1497
+ /**
1498
+ * Decodes the content of an `.hdr` file.
1499
+ * @throws {Error} If the content isn't a supported Radiance HDR image.
1500
+ */
1501
+ static parse(buffer: ArrayBuffer): HdrImage;
1502
+ /** Checks the signature and reads the header lines up to the blank one ending them, rejecting non-RGBE formats. */
1503
+ private static _readHeader;
1504
+ /** Reads the resolution line (`-Y height +X width`, or `+Y` for bottom-up images). */
1505
+ private static _readResolution;
1506
+ /** Reads one scanline of `width` RGBE pixels into `scanline`, run-length encoded or flat. */
1507
+ private static _readScanline;
1508
+ /** Reads the run-length encoded bytes of one `channel` of a scanline, interleaving them into `scanline`. */
1509
+ private static _readEncodedChannel;
1510
+ /** Reads one uncompressed scanline (`width` consecutive RGBE quadruplets). */
1511
+ private static _readFlatScanline;
1512
+ /** Converts a scanline of RGBE pixels into linear RGB floats, written into `data` from `offset`. */
1513
+ private static _decodeScanline;
1514
+ }
1515
+
1284
1516
  /** Result of a {@link Pacem3DAdapterElement.raycast} hit-test: the hit {@link Renderable} object and the world-space point of intersection. */
1285
1517
  declare type RaycastResult = {
1286
1518
  object: Renderable;
@@ -1350,6 +1582,17 @@ declare interface ShaderMaterial extends Material {
1350
1582
  fragmentShader?: string;
1351
1583
  }
1352
1584
 
1585
+ /**
1586
+ * Blends the per-corner normals of `geometry`, the face normals set by {@link computeSharpVertexNormals}, towards the
1587
+ * exact normals of the surface the mesh approximates: `normalize(mix(face, surface, smooth))`. `0` keeps the facets,
1588
+ * `1` renders a round surface, values in between soften the facets' edges. The surface normal is flipped, if needed,
1589
+ * to the side of the face normal, so that the faces' winding keeps deciding what's outside.
1590
+ * @param geometry A mesh geometry whose normals are the face normals (one per triangle corner, in index order).
1591
+ * @param surfaceNormal Gets the unit normal of the surface at a vertex `position`, given the normal of the face the corner belongs to; `null` keeps the face normal (e.g. the flat caps of a cylinder).
1592
+ * @param smooth Blend factor, from `0` (faceted) to `1` (round).
1593
+ */
1594
+ declare function smoothVertexNormals(geometry: MeshGeometry, surfaceNormal: (position: Vector3D, faceNormal: Vector3D) => Vector3D, smooth: number): void;
1595
+
1353
1596
  /** A {@link DiffuseMaterial} that additionally models specular (glossy) highlights. */
1354
1597
  declare interface SpecularMaterial extends DiffuseMaterial {
1355
1598
  /** Specular color, defines the color of reflections. */
@@ -1399,38 +1642,153 @@ declare enum StalePropertyFlag {
1399
1642
  /** The object's {@link Renderable.hide} visibility changed. */
1400
1643
  Visibility = "visibility",
1401
1644
  /** The mesh's {@link Mesh.castShadow}/{@link Mesh.receiveShadow} changed. */
1402
- Shadow = "shadow"
1645
+ Shadow = "shadow",
1646
+ /** The mesh's {@link Mesh.outlineColor}/{@link Mesh.outlineWidth}/{@link Mesh.outlineUnits} changed. */
1647
+ Outline = "outline"
1403
1648
  }
1404
1649
 
1405
- /** A {@link DiffuseMaterial} using a physically-based (metalness/roughness) shading model. */
1406
- declare interface StandardMaterial extends DiffuseMaterial {
1407
- readonly shader: KnownShader.Phong;
1408
- /** Surface roughness, from `0` (mirror-smooth) to `1` (fully matte), controlling how spread-out specular highlights are. */
1409
- roughness?: number;
1410
- /** How metallic the surface is, from `0` (dielectric) to `1` (fully metallic), controlling how much of {@link DiffuseMaterial.emissiveColor} tints reflections. */
1411
- metalness?: number;
1412
- /** Percentage of reflected light at grazing angles. */
1413
- fresnel?: number;
1650
+ /** A {@link StandardMaterialProperties} material, the glTF 2.0 core one: dielectrics reflect 4% of the light at normal incidence. */
1651
+ declare interface StandardMaterial extends StandardMaterialProperties {
1652
+ readonly shader: KnownShader.Standard;
1414
1653
  }
1415
1654
 
1416
- /** `<pacem-3d-material-standard>`: produces a {@link StandardMaterial} using a physically-based (metalness/roughness) shading model. */
1417
- declare class StandardMaterialElement extends MaterialElement {
1418
- constructor();
1419
- /** Builds the {@link StandardMaterial}, adding `emissiveColor`, `refractionRatio`, `metalness`, `roughness` and `flatShading` to the base {@link Material}. */
1420
- protected createMaterial(): Promise<PhongMaterial>;
1655
+ declare class StandardMaterialBaseElement extends MaterialElement {
1656
+ /** @param shader The {@link KnownShader} produced: {@link KnownShader.Standard} by default, {@link KnownShader.Physical} for the {@link PhysicalMaterialElement} subclass. */
1657
+ constructor(shader?: KnownShader.Standard | KnownShader.Physical);
1658
+ /** Builds the {@link StandardMaterial}, adding the emissive, metalness/roughness and map properties to the base {@link Material}. */
1659
+ protected createMaterial(): Promise<StandardMaterialProperties>;
1421
1660
  propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
1422
- /** Gets or sets the diffuse color (albedo). */
1661
+ /** Gets or sets the emissive color: light the surface gives off by itself (the albedo is {@link color}). */
1423
1662
  emissiveColor: string;
1663
+ /** Gets or sets the multiplier of {@link emissiveColor} (`1` by default). */
1664
+ emissiveIntensity: number;
1424
1665
  /** Gets or sets the index of refraction. */
1425
1666
  refractionRatio: number;
1426
- /** Gets or sets the surface roughness, from `0` (mirror-smooth) to `1` (fully matte). */
1667
+ /** Gets or sets the surface roughness, from `0` (mirror-smooth) to `1` (fully matte, default). */
1427
1668
  roughness: number;
1428
- /** Gets or sets how metallic the surface is, from `0` (dielectric) to `1` (fully metallic). */
1669
+ /** Gets or sets how metallic the surface is, from `0` (dielectric, default) to `1` (fully metallic). */
1429
1670
  metalness: number;
1671
+ /** Gets or sets the strength of the {@link normalMap} perturbation (`1` by default). */
1672
+ normalScale: number;
1673
+ /** Gets or sets the strength of the {@link occlusionMap}, from `0` (ignored) to `1` (fully applied, default). */
1674
+ occlusionStrength: number;
1430
1675
  /** Gets or sets whether each face is rendered as flat (faceted) rather than smoothly interpolated. */
1431
1676
  flatShading: boolean;
1677
+ /** Gets or sets the URL of the tangent-space normal map. */
1678
+ normalMap: string;
1679
+ /** Gets or sets the URL of the bump (height) map: black low, white high; it adds to the {@link normalMap}, if any. */
1680
+ bumpMap: string;
1681
+ /** Gets or sets the strength of the {@link bumpMap}: multiplies its slope, in height per texel (`1` by default). */
1682
+ bumpScale: number;
1683
+ /** Gets or sets the URL of the metalness/roughness map (glTF packing: roughness in green, metalness in blue). */
1684
+ metalnessRoughnessMap: string;
1685
+ /** Gets or sets the URL of the ambient occlusion map (red channel). */
1686
+ occlusionMap: string;
1687
+ /** Gets or sets the URL of the emissive map. */
1688
+ emissiveMap: string;
1689
+ /** Gets or sets the URL of the opacity map: its luminance multiplies the alpha (black = transparent, white = opaque). */
1690
+ opacityMap: string;
1691
+ /** Gets or sets the URL of the displacement (height) map: black low, white high; it moves the vertices along the normals. */
1692
+ displacementMap: string;
1693
+ /** Gets or sets how far white moves the surface, in local units (`1` by default). */
1694
+ displacementScale: number;
1695
+ /** Gets or sets the offset added to every displacement, in local units (`0` by default). */
1696
+ displacementBias: number;
1697
+ /** Gets or sets how the alpha is interpreted: `'opaque'`, `'blend'` or `'mask'` (see {@link AlphaMode}); when unset, translucent if the color alpha times opacity is below `1` or an {@link opacityMap} is set. */
1698
+ alphaMode: AlphaMode;
1699
+ /** Gets or sets the alpha threshold of the `'mask'` {@link alphaMode} (`0.5` by default). */
1700
+ alphaCutoff: number;
1701
+ /** Gets or sets whether the surface reflects the other objects of the scene too, not just the environment (6 extra renders per mesh whenever the scene changes; `false` by default). */
1702
+ reflectScene: boolean;
1703
+ }
1704
+
1705
+ /** `<pacem-3d-material-standard>`: produces a {@link StandardMaterial} using a physically-based (metalness/roughness) shading model, aligned with the glTF 2.0 core material. */
1706
+ declare class StandardMaterialElement extends StandardMaterialBaseElement {
1707
+ }
1708
+
1709
+ /** Properties of the physically-based (metalness/roughness) shading model, aligned with the glTF 2.0 core material; shared by {@link StandardMaterial} and {@link PhysicalMaterial}. */
1710
+ declare interface StandardMaterialProperties extends DiffuseMaterial {
1711
+ /** Surface roughness, from `0` (mirror-smooth) to `1` (fully matte), controlling how spread-out specular highlights are. */
1712
+ roughness?: number;
1713
+ /** How metallic the surface is, from `0` (dielectric) to `1` (fully metallic), controlling how much of {@link Material.color} tints reflections. */
1714
+ metalness?: number;
1715
+ /** Multiplier of {@link DiffuseMaterial.emissiveColor}. */
1716
+ emissiveIntensity?: number;
1717
+ /** Strength of the {@link normalMap} perturbation (`1` = as authored). */
1718
+ normalScale?: number;
1719
+ /** Strength of the {@link occlusionMap}, from `0` (ignored) to `1` (fully applied). */
1720
+ occlusionStrength?: number;
1721
+ /** Tangent-space normal map. */
1722
+ normalMap?: string;
1723
+ /** The decoded bitmap of {@link normalMap}, loaded asynchronously. */
1724
+ normalTexture?: ImageBitmap;
1725
+ /** Bump (height) map: its luminance is the height (black low, white high); converted into a normal map, it adds to the {@link normalMap}, if any. */
1726
+ bumpMap?: string;
1727
+ /** The decoded bitmap of {@link bumpMap}, loaded asynchronously. */
1728
+ bumpTexture?: ImageBitmap;
1729
+ /** Strength of the {@link bumpMap}: multiplies its slope, in height per texel (`1` by default: white stands one texel above black). */
1730
+ bumpScale?: number;
1731
+ /** Metalness/roughness map, glTF packing: roughness in the green channel, metalness in the blue one (both multiplied by {@link roughness}/{@link metalness}). */
1732
+ metalnessRoughnessMap?: string;
1733
+ /** The decoded bitmap of {@link metalnessRoughnessMap}, loaded asynchronously. */
1734
+ metalnessRoughnessTexture?: ImageBitmap;
1735
+ /** Ambient occlusion map, read from the red channel. */
1736
+ occlusionMap?: string;
1737
+ /** The decoded bitmap of {@link occlusionMap}, loaded asynchronously. */
1738
+ occlusionTexture?: ImageBitmap;
1739
+ /** Emissive map, multiplied by {@link DiffuseMaterial.emissiveColor}. */
1740
+ emissiveMap?: string;
1741
+ /** The decoded bitmap of {@link emissiveMap}, loaded asynchronously. */
1742
+ emissiveTexture?: ImageBitmap;
1743
+ /** Opacity map, as in 3ds Max: its luminance multiplies the alpha (black = transparent, white = opaque). */
1744
+ opacityMap?: string;
1745
+ /** The decoded bitmap of {@link opacityMap}, loaded asynchronously. */
1746
+ opacityTexture?: ImageBitmap;
1747
+ /**
1748
+ * Displacement (height) map: its luminance (black low, white high) moves the vertices along the normals by
1749
+ * `height × displacementScale + displacementBias`, in local units. Needs enough vertices (e.g. the polyhedra's
1750
+ * `segments`); the shading follows from the normal map, or else the bump map, or else this map itself.
1751
+ */
1752
+ displacementMap?: string;
1753
+ /** The decoded bitmap of {@link displacementMap}, loaded asynchronously. */
1754
+ displacementTexture?: ImageBitmap;
1755
+ /** How far white moves the surface, in local units (`1` by default). */
1756
+ displacementScale?: number;
1757
+ /** Offset added to every displacement, in local units (`0` by default): e.g. `-scale / 2` centers it on the surface. */
1758
+ displacementBias?: number;
1759
+ /**
1760
+ * How the alpha is interpreted (see {@link AlphaMode}). When omitted, the surface is translucent if its color alpha
1761
+ * times opacity is below `1` or it has an {@link opacityMap}, opaque otherwise.
1762
+ */
1763
+ alphaMode?: AlphaMode;
1764
+ /** Alpha threshold of the `'mask'` {@link alphaMode}: the surface shows where its alpha is at least this (`0.5` by default). */
1765
+ alphaCutoff?: number;
1766
+ /**
1767
+ * Whether the surface reflects the other objects of the scene, not just the environment: each mesh using the
1768
+ * material captures its surroundings (a reflection probe, from its own position) whenever the scene changes. How much
1769
+ * and how sharply it reflects stays up to {@link metalness}, {@link roughness} and Fresnel. `false` by default.
1770
+ */
1771
+ reflectScene?: boolean;
1432
1772
  }
1433
1773
 
1774
+ /**
1775
+ * Subdivides every triangle of `geometry` into `segments²` smaller ones, each edge split into `segments` equal parts
1776
+ * (a barycentric grid): positions and the per-corner texture coordinates are interpolated, so the faces stay flat and
1777
+ * the texture mapping unchanged, and the winding is preserved. Gives displacement maps vertices to move. The normals
1778
+ * are recomputed as face normals ({@link computeSharpVertexNormals}).
1779
+ * @param geometry A triangle mesh with per-corner texture coordinates (in index order).
1780
+ * @param segments Parts each edge is divided into; `1` (or less) returns `geometry` itself.
1781
+ * @returns A new geometry (positions shared within each original face only).
1782
+ */
1783
+ declare function subdivideTriangles(geometry: MeshGeometry, segments: number): MeshGeometry;
1784
+
1785
+ /**
1786
+ * How the linear (high dynamic range) color of physically-based materials is compressed into the displayable range:
1787
+ * `'none'` just clamps, `'neutral'` (Khronos PBR Neutral, default) keeps base colors recognisable while rolling off
1788
+ * the highlights, `'aces'` (Stephen Hill's fit of the ACES filmic curve) gives a more contrasted, cinematic look.
1789
+ */
1790
+ declare type ToneMappingMode = 'none' | 'neutral' | 'aces';
1791
+
1434
1792
  /**
1435
1793
  * How translucent meshes get rendered: `'a-buffer'` (default) collects their fragments in per-pixel lists, sorted and
1436
1794
  * composited after the opaque pass (order-independent transparency); `'blend'` just alpha-blends them in draw order.