@equinor/videx-3d 1.1.0 → 2.0.0

package/dist/shaderLib/oit.glsl

@@ -0,0 +1,106 @@
+// Order-independent transparency (OIT) shared shader chunk.
+//
+// Provides the uniforms and the per-pass output logic used by the OITRenderPass
+// hybrid pipeline (exact depth-peeled front layer + weighted-blended OIT tail).
+//
+// Usage (library ShaderMaterials, GLSL1 / gl_FragColor):
+//   #include <this file>           // brings uniforms + oitProcess()
+//   ...
+//   gl_FragColor = ...;            // compute final straight (non-premultiplied) color
+//   #ifdef USE_OIT
+//     gl_FragColor = oitProcess(gl_FragColor);
+//   #endif
+//
+// The fragment shader must have `vViewPosition` (view-space position) available.
+//
+// Pass selection is driven by defines set on the per-pass variant materials:
+//   USE_OIT            enables the whole block
+//   OIT_DEPTH_PASS     min-depth pre-pass (writes linear view-space depth)
+//   OIT_FRONT_PASS     exact front layer (alpha-over, discards tail fragments)
+//   (none of the above, USE_OIT only) => single-buffer weighted-blended OIT tail
+//
+// The WBOIT tail uses a single RGBA16F accumulation target with optical-depth
+// weighting: each fragment contributes weight b = -ln(1 - alpha), so
+//   accum.rgb = sum(rgb * b),  accum.a = sum(b).
+// The composite recovers the weighted-average colour as accum.rgb / accum.a and the
+// coverage as 1 - exp(-accum.a) = 1 - prod(1 - alpha) -- identical to a separate
+// (ZERO, ONE_MINUS_SRC_COLOR) reveal pass, but without the extra rasterisation.
+//
+// The `oitSkipFront` uniform (1) disables front peeling so the tail pass keeps the
+// front fragments too (debug: everything resolved through WBOIT).
+
+#ifdef USE_OIT
+
+uniform float oitDepthFar;          // normalisation factor for view-space depth
+uniform vec2 oitScreenSize;         // render target size in pixels
+uniform sampler2D oitMinDepthTexture; // per-pixel min linear depth (front layer)
+uniform int oitSkipFront;           // 1 = disable front peeling (debug: all WBOIT)
+uniform float oitOcclusionThreshold; // occlusion-stamp pass: min alpha to write depth
+
+// Process the straight (non-premultiplied) fragment color for the active pass.
+vec4 oitProcess(vec4 color) {
+  #ifdef OIT_OCCLUSION_PASS
+  // Occlusion depth stamp: write depth only where this surface is opaque enough
+  // (its own alpha clears the threshold). Colour writes are disabled on the
+  // variant, so the returned colour is ignored; discarding skips the depth write.
+  // Lets sufficiently-opaque transparent surfaces occlude annotation labels even
+  // though they don't write depth in the regular OIT passes.
+  if(color.a < oitOcclusionThreshold)
+    discard;
+  return color;
+  #endif
+
+  // View-space linear depth, normalised. Independent of the (logarithmic) depth
+  // buffer encoding, so the partition is correct at any camera scale.
+  float linZ = abs(vViewPosition.z) / oitDepthFar;
+
+  #ifdef OIT_DEPTH_PASS
+
+  // Written into an R32F target with MinEquation blending => per-pixel minimum.
+  return vec4(linZ, 0.0, 0.0, 1.0);
+
+  #else
+
+  // Gradient-relative tolerance: only the surface that produced the per-pixel
+  // minimum qualifies as "front". A fixed epsilon would form a depth slab and let
+  // distinct surfaces grazing within it bleed into each other.
+  vec2 uv = gl_FragCoord.xy / oitScreenSize;
+  float minZ = texture2D(oitMinDepthTexture, uv).r;
+  // Depth-relative tolerance. The min-depth pre-pass and this pass rasterise the
+  // SAME geometry with the SAME vertex transform, so the genuine front fragment's
+  // linZ matches the stored minZ to near bit-exactness; a tiny epsilon suffices.
+  // Avoid fwidth(linZ) here: at self-overlap silhouettes the 2x2 derivative quads
+  // straddle the depth discontinuity between layers, so fwidth spikes and inflates
+  // the tolerance, misclassifying back-layer fragments as front (visible edges).
+  float tol = minZ * 1e-3 + 1e-6;
+  bool isFront = (linZ - minZ) <= tol;
+
+  #ifdef OIT_FRONT_PASS
+
+  // Exact front layer: keep only the nearest fragment, blended alpha-over.
+  if(!isFront)
+    discard;
+  return color;
+
+  #else
+
+  // Tail pass: exclude the front fragment (handled exactly by the front pass),
+  // unless front peeling is disabled (debug: every fragment goes through WBOIT).
+  if(isFront && oitSkipFront == 0)
+    discard;
+
+  float alpha = color.a;
+
+  // Optical-depth weight b = -ln(1 - alpha). Additive (ONE, ONE) blending then gives
+  // accum.rgb = sum(rgb * b), accum.a = sum(b). The composite reconstructs both the
+  // weighted-average colour (accum.rgb / accum.a) and the coverage
+  // (1 - exp(-accum.a) = 1 - prod(1 - alpha)) from this single buffer, so no separate
+  // reveal pass is needed. alpha is clamped below 1 to keep b finite.
+  float b = -log(1.0 - clamp(alpha, 0.0, 0.9999));
+  return vec4(color.rgb * b, b);
+
+  #endif // OIT_FRONT_PASS
+  #endif // OIT_DEPTH_PASS
+}
+
+#endif // USE_OIT

package/dist/types/components/Annotations/AutoUpdate.d.ts

@@ -1,3 +1,3 @@
 export declare const AutoUpdate: ({ maxVisible }: {
     maxVisible: number;
-}) => null;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/types/components/Annotations/index.d.ts

@@ -1,8 +1,8 @@
 import { Vec3 } from '../../sdk';
 import { AnnotationProps } from './types';
+export * from '../../rendering/passes/AnnotationsPass';
 export * from './Annotations';
-export * from './annotations-renderer';
 export * from './annotations-state';
 export * from './AnnotationsLayer';
 export * from './types';
-export declare const getAnnotationPosition: (annotation: AnnotationProps) => Vec3;
+export declare const getAnnotationPosition: (annotation: AnnotationProps, target?: Vec3) => Vec3;

package/dist/types/components/Annotations/types.d.ts

@@ -55,7 +55,7 @@ export type AnnotationInstanceState = {
     kill?: boolean;
     cooldown?: number;
     opacity?: number;
-    labelWidht: number;
+    labelWidth: number;
     labelHeight: number;
     labelX?: number;
     labelY?: number;
@@ -68,6 +68,8 @@ export type AnnotationInstanceState = {
     _zIndex?: string;
     _transform?: string;
     _needsUpdate?: boolean;
+    _connPrevX?: number;
+    _connPrevY?: number;
 };
 export type AnnotationInstance = {
     id: string;

package/dist/types/components/Annotations/update-annotations.d.ts

@@ -1,6 +1,16 @@
 import { Clock, PerspectiveCamera } from 'three';
 import { Vec2 } from '../../sdk';
 import { AnnotationInstance } from './types';
+/**
+ * Activity flags updated by preprocessInstances each frame. Used by
+ * AnnotationsPass to skip the expensive post-process/overlay work when the
+ * scene is settled (camera static and no animations in progress).
+ */
+export declare const annotationsActivity: {
+    animating: boolean;
+    positionChanged: boolean;
+    deltaTime: number;
+};
 /**
  * PRE-PROCESS INSTANCES
  */

package/dist/types/components/EventEmitter/EventEmitterContext.d.ts

@@ -1,4 +1,4 @@
-import { Camera, Object3D } from 'three';
+import { Camera, Material, Object3D } from 'three';
 import { Vec2, Vec3 } from '../../sdk';
 export type KeysPressed = {
     altKey: boolean;
@@ -22,6 +22,7 @@ export type Listener = {
     ref?: any;
     threshold?: number;
     handlers: Record<string, EventEmitterCallback>;
+    customMaterial?: Material;
 };
 export type Emitter = {
     source: Object3D;

package/dist/types/components/EventEmitter/index.d.ts

@@ -1,3 +1,4 @@
 export * from './EventEmitter';
 export * from './EventEmitterContext';
 export * from './picking-helper';
+export * from './picking-material';

package/dist/types/components/EventEmitter/picking-helper.d.ts

@@ -19,7 +19,26 @@ export declare class PickingHelper {
     private _radius;
     private _pbo;
     private _buffer;
+    private _prevClearColor;
     private _material;
+    /**
+     * Dedicated camera used for the picking render so the shared scene camera is
+     * never mutated. `setViewOffset` rebuilds a camera's projection (it remaps the
+     * frustum to the tiny patch under the cursor), and that mutation would clobber
+     * any external modification of the real camera's projection — e.g. the
+     * sub-pixel jitter a TAA pass bakes in. Each pick this camera is `copy()`d from
+     * the real camera (which faithfully mirrors `matrixWorld`,
+     * `matrixWorldInverse`, the projection and all intrinsics) and the view offset
+     * is applied here instead. `matrixWorldAutoUpdate` is disabled so the renderer
+     * uses the copied world matrix verbatim rather than recomputing it.
+     */
+    private _camera;
+    private _listeners;
+    private _emitters;
+    private _mapStarts;
+    private _mapObjectIds;
+    private _objectMapLength;
+    private _objectMapCount;
     constructor(options?: {});
     private traverseObject;
     updateListeners: () => void;
@@ -27,6 +46,12 @@ export declare class PickingHelper {
     getListener: (id: number) => Listener | undefined;
     removeListener: (id: number) => void;
     render(pointer: Vector2, renderer: WebGLRenderer, scene: Scene, camera: PerspectiveCamera): Promise<PickResult>;
+    /**
+     * Locate the emitter owning a flat id via binary search. Emitter ranges are
+     * contiguous and sorted by start, so the owner is the rightmost entry whose
+     * start is `<= flatId`.
+     */
+    private findEmitterIndex;
     private pick;
     dispose(): void;
 }

package/dist/types/components/EventEmitter/picking-material.d.ts

@@ -1,11 +1,14 @@
-import { Camera, Object3D, Scene, ShaderMaterial, WebGLRenderer } from 'three';
+import { Camera, Object3D, Scene, ShaderMaterial, Uniform, WebGLRenderer } from 'three';
 import { BufferGeometry } from 'three/webgpu';
-import { Emitter, Listener } from './EventEmitterContext';
+export declare const pickingMaterialUniforms: {
+    emitterId: Uniform<number>;
+    side: Uniform<number>;
+};
 export declare class PickingMaterial extends ShaderMaterial {
-    listeners: Map<number, Listener>;
-    emitters: Map<number, Emitter>;
-    currentObjectMap: Array<number> | null;
     constructor();
     dispose(): void;
     onBeforeRender(_renderer: WebGLRenderer, _scene: Scene, _camera: Camera, _geometry: BufferGeometry, object: Object3D): void;
 }
+export declare class CustomPickingMaterial extends PickingMaterial {
+    constructor(vertexShader?: string, uniforms?: Record<string, Uniform>);
+}

package/dist/types/components/Surfaces/Surface.d.ts

@@ -28,6 +28,13 @@ export type SurfaceProps = CommonComponentProps & PointerEvents & {
     wireframe?: boolean;
     normalMap?: Texture;
     normalScale?: Vec2;
+    /**
+     * Precompute the surface normals into a compact texture instead of deriving
+     * them per-fragment from the elevation map. This skips the normal recompute
+     * the shader otherwise repeats across the order-independent transparency
+     * passes, at the cost of a little extra texture memory. Defaults to `false`.
+     */
+    precomputeNormals?: boolean;
     debug?: boolean;
 };
 /**
@@ -43,4 +50,4 @@ export type SurfaceProps = CommonComponentProps & PointerEvents & {
  *
  * @group Components
  */
-export declare const Surface: ({ meta, color, colorRamp, rampMin, rampMax, reverseRamp, useColorRamp, showContours, contoursInterval, contoursColorMode, contoursColorModeFactor, contoursThickness, contoursColor, opacity, priority, maxError, doubleSide, wireframe, normalMap, normalScale, name, userData, receiveShadow, castShadow, layers, position, renderOrder, visible, debug, onPointerClick, onPointerEnter, onPointerLeave, onPointerMove, }: SurfaceProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const Surface: ({ meta, color, colorRamp, rampMin, rampMax, reverseRamp, useColorRamp, showContours, contoursInterval, contoursColorMode, contoursColorModeFactor, contoursThickness, contoursColor, opacity, priority, maxError, doubleSide, wireframe, normalMap, normalScale, precomputeNormals, name, userData, receiveShadow, castShadow, layers, position, renderOrder, visible, debug, onPointerClick, onPointerEnter, onPointerLeave, onPointerMove, }: SurfaceProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/components/Surfaces/SurfaceMaterial.d.ts

@@ -20,6 +20,7 @@ export type SurfaceMaterialParameters = ShaderMaterialParameters & MeshLambertMa
     contoursColor?: string | number | Color;
     elevationTexture?: Texture;
     normalTexture?: Texture;
+    usePrecomputedNormals?: boolean;
     debug?: boolean;
 };
 /**
@@ -48,6 +49,8 @@ export declare class SurfaceMaterial extends ShaderMaterial {
     set showContours(value: any);
     get debug(): any;
     set debug(value: any);
+    get usePrecomputedNormals(): any;
+    set usePrecomputedNormals(value: any);
     dispose(): void;
     onBeforeCompile(): void;
 }

package/dist/types/components/Surfaces/surface-defs.d.ts

@@ -4,4 +4,5 @@ export declare const surfaceTextures = "surfaceTextures";
 export type SurfaceGeometryResponse = PackedBufferGeometry;
 export type SurfaceTexturesResponse = {
     elevationImageBuffer: Float32Array;
+    normalImageBuffer?: Uint8Array;
 };

package/dist/types/components/Wellbores/Casings/CasingEmitterMaterial.d.ts

@@ -0,0 +1,16 @@
+import { CustomPickingMaterial } from '../../EventEmitter/picking-material';
+export declare class CasingEmitterMaterial extends CustomPickingMaterial {
+    constructor();
+    get sizeMultiplier(): number;
+    set sizeMultiplier(v: number);
+    get radius(): number;
+    set radius(v: number);
+    get innerRadius(): number;
+    set innerRadius(v: number);
+    get sliceOffset(): number;
+    set sliceOffset(v: number);
+    get sliceAngle(): number;
+    set sliceAngle(v: number);
+    get autoSlicePosition(): boolean;
+    set autoSlicePosition(v: boolean);
+}

package/dist/types/components/Wellbores/Casings/CasingSection.d.ts

@@ -1,3 +1,4 @@
+import { PointerEvents } from '../../../main';
 import { CasingSectionMaterialOptions } from './Casings';
 import { CasingSectionType } from './casings-defs';
 type CasingSectionProps = {
@@ -10,6 +11,6 @@ type CasingSectionProps = {
     autoSlicePosition?: boolean;
     opacity?: number;
     renderOrder?: number;
-};
-export declare const CasingSection: ({ section, materialOptions, radialSegments, sizeMultiplier, sliceAngle, sliceOffset, autoSlicePosition, opacity, renderOrder, }: CasingSectionProps) => import("react/jsx-runtime").JSX.Element;
+} & PointerEvents;
+export declare const CasingSection: ({ section, materialOptions, radialSegments, sizeMultiplier, sliceAngle, sliceOffset, autoSlicePosition, opacity, renderOrder, onPointerClick, onPointerEnter, onPointerLeave, onPointerMove, }: CasingSectionProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/components/Wellbores/Casings/Casings.d.ts

@@ -1,6 +1,7 @@
 import { ReactElement } from 'react';
 import { Group, MeshStandardMaterialParameters, Object3D } from 'three';
 import { CommonComponentProps } from '../../../common/types';
+import { PointerEvents } from '../../../main';
 import { CasingSectionType } from './casings-defs';
 /**
  * CasingSectionMaterialOptions
@@ -20,7 +21,7 @@ export type MaterialOptions = (section: CasingSectionType) => CasingSectionMater
  * Casing props
  * @expand
  */
-export type CasingProps = CommonComponentProps & {
+export type CasingProps = PointerEvents & CommonComponentProps & {
     fallback?: () => ReactElement<Object3D>;
     radialSegments?: number;
     sliceAngle?: number;
@@ -55,7 +56,7 @@ export type CasingProps = CommonComponentProps & {
  *
  * @group Components
  */
-export declare const Casings: import('react').ForwardRefExoticComponent<CommonComponentProps & {
+export declare const Casings: import('react').ForwardRefExoticComponent<PointerEvents & CommonComponentProps & {
     fallback?: () => ReactElement<Object3D>;
     radialSegments?: number;
     sliceAngle?: number;

package/dist/types/generators/surface-generator.d.ts

@@ -1,4 +1,4 @@
 import { SurfaceTexturesResponse } from '../main';
 import { PackedBufferGeometry, ReadonlyStore } from '../sdk';
-export declare function generateSurfaceTexturesData(this: ReadonlyStore, id: string): Promise<SurfaceTexturesResponse | null>;
+export declare function generateSurfaceTexturesData(this: ReadonlyStore, id: string, computeNormals?: boolean): Promise<SurfaceTexturesResponse | null>;
 export declare function generateSurfaceGeometry(this: ReadonlyStore, id: string, maxError?: number): Promise<PackedBufferGeometry | null>;

package/dist/types/layers/layers.d.ts

@@ -1,5 +1,9 @@
 import { Layers } from 'three';
 export declare const LAYERS: {
+    OIT_EXCLUDED: number;
+    FORCE_OPAQUE: number;
+    OVERLAY: number;
+    EMISSIVE: number;
     NOT_EMITTER: number;
     EMITTER: number;
 };

package/dist/types/rendering/OitMaterial.d.ts

@@ -0,0 +1,59 @@
+import { Side } from 'three';
+/**
+ * Props for {@link OitMaterial}.
+ * @expand
+ */
+export type OitMaterialProps = {
+    /**
+     * Force a specific `side` on the OIT variants (e.g. `DoubleSide`). Defaults to
+     * the material's own side.
+     */
+    side?: Side;
+    /**
+     * Names of custom uniform-container properties on the material to share by
+     * reference with the per-pass variants. Only needed for non-`ShaderMaterial`
+     * materials that read a custom uniforms object in `onBeforeCompile`.
+     */
+    shareUniforms?: string[];
+    /**
+     * Names of value properties (e.g. `color`, `metalness`) to keep live on the
+     * per-pass variants of a cloned built-in material. See
+     * {@link OitMaterialOptions.syncProperties}. Ignored for `ShaderMaterial`s
+     * (already live via shared uniforms).
+     */
+    syncProperties?: string[];
+    /**
+     * - `inject` (default): patch the material's shaders at compile time (stock or
+     *   inline materials whose shader does not already include `oit.glsl`).
+     * - `attach`: the material's shader already `#include`s `oit.glsl` and calls
+     *   `oitProcess` (library materials); only wire up the variant machinery.
+     */
+    mode?: 'inject' | 'attach';
+};
+/**
+ * A declarative helper that makes the material of its parent `mesh` participate in
+ * the {@link OITRenderPass} pipeline, so transparent inline materials are resolved
+ * order-independently instead of being treated as opaque occluders.
+ *
+ * Drop it in as a sibling of the material, inside the `mesh`:
+ *
+ * ```tsx
+ * <mesh geometry={geometry}>
+ *   <shaderMaterial
+ *     uniforms={uniforms}
+ *     vertexShader={vertexShader}
+ *     fragmentShader={fragmentShader}
+ *     transparent
+ *   />
+ *   <OitMaterial side={DoubleSide} />
+ * </mesh>
+ * ```
+ *
+ * It renders an invisible, empty `object3D` purely to locate the parent mesh; the
+ * wiring is idempotent and a no-op outside the OIT pipeline.
+ *
+ * @group Rendering
+ * @see {@link makeOitCompatible}
+ * @see {@link attachOitVariants}
+ */
+export declare function OitMaterial({ side, shareUniforms, syncProperties, mode, }: OitMaterialProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/rendering/Pass.d.ts

@@ -0,0 +1,7 @@
+import { WebGLRenderer, WebGLRenderTarget } from 'three';
+export declare abstract class Pass {
+    writeToScreen: boolean;
+    setSize?(width: number, height: number, pixelRatio: number): void;
+    dispose?(): void;
+    abstract render(renderer: WebGLRenderer, buffer: WebGLRenderTarget): void;
+}

package/dist/types/rendering/RenderingPipeline.d.ts

@@ -0,0 +1,37 @@
+import { Pass } from './Pass';
+/**
+ * Props for the {@link RenderingPipeline} component.
+ * @expand
+ */
+export type RenderingPipelineProps = {
+    /** Ordered list of passes to execute every frame. */
+    passes: Pass[];
+    /** Multisample count for the main render target. Defaults to 0. */
+    samples?: number;
+    /** Render target supersampling factor. Defaults to 1. */
+    supersample?: number;
+    /** Frame priority (passed to `useFrame`). Defaults to 1. */
+    priority?: number;
+};
+/**
+ * Generic render pipeline component that runs an ordered list of {@link Pass} objects
+ * against a shared `WebGLRenderTarget` (color + depth texture). Use it to compose
+ * custom rendering pipelines — e.g. a {@link OITRenderPass} based pipeline for
+ * order-independent transparency.
+ *
+ * @example
+ * ```tsx
+ * const passes = useMemo(
+ *   () => [new OITRenderPass(scene, camera), new OutputPass()],
+ *   [scene, camera],
+ * );
+ * return <RenderingPipeline passes={passes} />;
+ * ```
+ *
+ * @group Components
+ * @category Rendering
+ * @see {@link Pass}
+ * @see {@link OITRenderPass}
+ * @see {@link OutputPass}
+ */
+export declare const RenderingPipeline: ({ passes, samples, supersample, priority, }: RenderingPipelineProps) => null;

package/dist/types/rendering/fullscreen-renderer.d.ts

@@ -4,6 +4,7 @@ export declare class FullscreenRenderer {
     mesh: Mesh;
     copyMaterial: RawShaderMaterial;
     constructor();
+    dispose(): void;
     renderMaterial(renderer: WebGLRenderer, buffer: WebGLRenderTarget | null, material: Material): void;
     renderTexture(renderer: WebGLRenderer, buffer: WebGLRenderTarget | null, texture: Texture, opacity?: number): void;
 }

package/dist/types/rendering/gpu-timer.d.ts

@@ -0,0 +1,46 @@
+import { WebGLRenderer } from 'three';
+/**
+ * Tiny GPU timer for WebGL2 built on `EXT_disjoint_timer_query_webgl2`.
+ *
+ * DEBUG-ONLY instrumentation: it brackets named, non-overlapping segments with
+ * `TIME_ELAPSED` queries and reads the results back asynchronously (a few frames
+ * later), reporting a smoothed millisecond figure per segment. Because the GPU runs
+ * behind the CPU, results are never available the same frame they are issued, so a
+ * small ring of queries per segment is kept in flight.
+ *
+ * Only one timer query can be active at a time per spec, so {@link begin}/{@link end}
+ * calls must be strictly sequential (never nested). All methods are no-ops when the
+ * extension is unavailable (older browsers, or the WebGPU renderer), so call sites
+ * can leave instrumentation in place unconditionally.
+ *
+ * This is measurement only — it issues no draws and mutates no render state — so it
+ * does not affect the rendered result and is safe to leave compiled in behind a flag.
+ *
+ * @group Rendering
+ */
+export declare class GpuTimer {
+    private gl;
+    private ext;
+    private segments;
+    private pool;
+    private active;
+    private activeSeg;
+    /** Whether GPU timing is available in this context. */
+    get supported(): boolean;
+    constructor(renderer: WebGLRenderer);
+    /** Begin timing a segment. No-op if unsupported or another segment is active. */
+    begin(label: string): void;
+    /** End timing the current segment. */
+    end(): void;
+    /**
+     * Harvest finished queries and update the smoothed timings. Call once per frame
+     * (e.g. at the top of the host pass's render). Disjoint frames (GPU context
+     * disruption) are discarded.
+     */
+    poll(): void;
+    /** Smoothed elapsed milliseconds for a segment, or -1 if no result yet. */
+    get(label: string): number;
+    /** Snapshot of every segment's smoothed timing in milliseconds. */
+    snapshot(): Record<string, number>;
+    dispose(): void;
+}

package/dist/types/rendering/index.d.ts

@@ -1,2 +1,8 @@
 export * from './fullscreen-renderer';
-export * from './render-passes';
+export * from './gpu-timer';
+export * from './oit-material';
+export * from './OitMaterial';
+export * from './Pass';
+export * from './passes';
+export * from './rendering-state';
+export * from './RenderingPipeline';

package/dist/types/rendering/oit-material.d.ts

@@ -0,0 +1,122 @@
+import { IUniform, Material, ShaderMaterial, Side, Texture, Vector2 } from 'three';
+/**
+ * The OIT render passes a material provides a variant for.
+ * - `depthMin`: min view-space linear depth pre-pass (front-layer detection)
+ * - `accum`: single-buffer weighted-blended OIT tail (b-weighted, carries coverage)
+ * - `front`: exact depth-peeled front layer (alpha-over)
+ * - `occlusion`: optional depth-only stamp that writes depth where the surface's own
+ *   alpha clears `oitOcclusionThreshold` (used to occlude annotation labels). Off by
+ *   default; its program is only compiled by Three when the pass actually renders it.
+ */
+export type OitPass = 'depthMin' | 'accum' | 'front' | 'occlusion';
+/** The set of per-pass variant materials used by the OITRenderPass. */
+export type OitVariants = Record<OitPass, Material>;
+/** The OIT uniforms shared across a material's variants and set by the pass. */
+export type OitUniforms = {
+    oitDepthFar: IUniform<number>;
+    oitScreenSize: IUniform<Vector2>;
+    oitMinDepthTexture: IUniform<Texture | null>;
+    oitSkipFront: IUniform<number>;
+    oitOcclusionThreshold: IUniform<number>;
+};
+/**
+ * A material that can participate in the {@link OITRenderPass} hybrid pipeline.
+ * Implemented by library materials (via {@link attachOitVariants}) and by patched
+ * stock / user materials (via {@link makeOitCompatible}).
+ */
+export interface OitCapableMaterial {
+    /** Returns the lazily-built per-pass variant materials (shared uniforms). */
+    getOitVariants(): OitVariants;
+    /** Returns the OIT uniforms object the pass updates each frame. */
+    getOitUniforms(): OitUniforms;
+}
+/** Options for making a material OIT-compatible. */
+export type OitMaterialOptions = {
+    /**
+     * Force a specific `side` on all variants (e.g. `DoubleSide` for surfaces so back
+     * faces contribute to the tail). Defaults to the base material's side.
+     */
+    side?: Side;
+    /**
+     * Names of properties on the material that hold uniform containers (objects of
+     * `IUniform`) which should be shared *by reference* with each per-pass variant.
+     * `ShaderMaterial` variants already share `uniforms`, but non-`ShaderMaterial`
+     * materials are cloned, so any custom uniform object they read in
+     * `onBeforeCompile` (e.g. a `uniforms` field used for slicing) must be listed
+     * here for live per-frame updates to reach the variants.
+     */
+    shareUniforms?: string[];
+    /**
+     * Names of **value** properties to keep in sync from the base material onto the
+     * per-pass variants every frame. Only relevant for stock/built-in materials, whose
+     * variants are *cloned* and would otherwise snapshot their appearance at build time
+     * (`ShaderMaterial` variants share `uniforms` and are always live, so this is
+     * ignored for them).
+     *
+     * Restricted to value properties that do **not** affect the compiled program:
+     * - primitives (e.g. `metalness`, `roughness`, `emissiveIntensity`), and
+     * - copyable value objects with a `.copy()` method (e.g. `color`, `emissive` —
+     *   `Color`; or `Vector2/3/4`), which are copied in place (no allocation, no
+     *   recompile).
+     *
+     * Do **not** list program-affecting properties here (textures such as `map`,
+     * `vertexColors`, anything that toggles a shader `#define`) — changing those needs
+     * a recompile and is intentionally unsupported through this fast path. `opacity` is
+     * always kept live and need not be listed. Use {@link COMMON_OIT_SYNC_PROPS} for a
+     * sensible default set.
+     *
+     * @example
+     * ```ts
+     * makeOitCompatible(material, { syncProperties: ['color', 'metalness'] });
+     * // or spread the common set:
+     * makeOitCompatible(material, { syncProperties: [...COMMON_OIT_SYNC_PROPS] });
+     * ```
+     */
+    syncProperties?: string[];
+};
+/**
+ * A convenient default set of common appearance properties to pass as
+ * {@link OitMaterialOptions.syncProperties} so runtime changes (e.g. recoloring) are
+ * reflected through the OIT passes for cloned built-in materials. Properties not
+ * present on a given material are ignored.
+ *
+ * @group Rendering
+ */
+export declare const COMMON_OIT_SYNC_PROPS: readonly ["color", "emissive", "emissiveIntensity", "metalness", "roughness"];
+/** Type guard for {@link OitCapableMaterial}. */
+export declare function isOitCapable(material: Material | null | undefined): material is Material & OitCapableMaterial;
+/**
+ * Make a library `ShaderMaterial` OIT-capable. The material's fragment shader is
+ * expected to already `#include` `oit.glsl` and call `oitProcess(gl_FragColor)`
+ * guarded by `#ifdef USE_OIT` (a no-op in the default pipeline). This adds the OIT
+ * uniforms to the material and attaches the per-pass variant machinery.
+ *
+ * @param material - the library ShaderMaterial to extend
+ * @param options - optional overrides (e.g. `side`)
+ * @returns the same material, typed as {@link OitCapableMaterial}
+ *
+ * @group Rendering
+ * @see {@link makeOitCompatible}
+ */
+export declare function attachOitVariants<T extends ShaderMaterial>(material: T, options?: OitMaterialOptions): T & OitCapableMaterial;
+/**
+ * Make any stock Three.js material or user-authored material OIT-compatible by
+ * patching its shaders at compile time (via `onBeforeCompile`) to include the OIT
+ * logic, and attaching the per-pass variant machinery.
+ *
+ * Works with lit built-in materials (which provide `vViewPosition`) and with
+ * materials lacking it (e.g. `LineBasicMaterial`), in which case `vViewPosition` is
+ * injected automatically. All injected code is guarded by `#ifdef USE_OIT`, so the
+ * base program is unchanged outside the OIT pipeline.
+ *
+ * Note: targets materials compiled by Three.js (built-ins, `ShaderMaterial`). Raw
+ * `RawShaderMaterial` (no Three.js shader prelude) is not auto-patched.
+ *
+ * @param material - the material to patch
+ * @param options - optional overrides (e.g. `side`)
+ * @returns the same material, typed as {@link OitCapableMaterial}
+ *
+ * @group Rendering
+ * @see {@link attachOitVariants}
+ */
+export declare function makeOitCompatible<T extends Material>(material: T, options?: OitMaterialOptions): T & OitCapableMaterial;