@equinor/videx-3d 1.1.1 → 3.0.0

package/dist/types/rendering/fxaa-resolver.d.ts

@@ -0,0 +1,25 @@
+import { WebGLRenderer, WebGLRenderTarget } from 'three';
+/**
+ * Fast Approximate Anti-Aliasing (FXAA) resolver. A single-pass, purely spatial
+ * morphological technique: it estimates edge direction from local luma and blends
+ * along it. Very cheap, but softer than SMAA and — like all spatial techniques —
+ * unable to recover sub-pixel features (thin lines/tubes that fall between
+ * samples); those need supersampling or the temporal mode.
+ *
+ * It operates entirely in the pipeline's linear FP16 space: the shader detects
+ * edges with a cheap perceptual luma but blends the linear texels, so brightness
+ * is untouched, flat regions are an exact passthrough, and HDR values above 1 are
+ * preserved (no LDR clamp). Because the neighbourhood taps cannot read the same
+ * target being written, it resolves into a scratch target and blits the result
+ * back into the buffer in place.
+ */
+export declare class FxaaResolver {
+    private scratch;
+    private fxaaMaterial;
+    private blitMaterial;
+    private fullscreenRenderer;
+    constructor();
+    setSize(width: number, height: number): void;
+    dispose(): void;
+    render(renderer: WebGLRenderer, buffer: WebGLRenderTarget): 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,9 @@
 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';
+export type { SMAAQuality } from './smaa-resolver';

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;

package/dist/types/{components/Annotations/annotations-renderer.d.ts → rendering/passes/AnnotationsPass.d.ts}

@@ -1,7 +1,8 @@
 import { Camera, CanvasTexture, Clock, PerspectiveCamera, ShaderMaterial, Vector2, WebGLRenderer, WebGLRenderTarget } from 'three';
-import { FullscreenRenderer } from '../../rendering/fullscreen-renderer';
-import { AnnotationInstance } from './types';
-export declare class AnnotationsRenderer {
+import { AnnotationInstance } from '../../components/Annotations/types';
+import { FullscreenRenderer } from '../fullscreen-renderer';
+import { Pass } from '../Pass';
+export declare class AnnotationsPass extends Pass {
     maxVisible: number;
     camera: PerspectiveCamera;
     clock: Clock;
@@ -12,11 +13,20 @@ export declare class AnnotationsRenderer {
     annotationsRenderTarget: WebGLRenderTarget;
     annotationsBuffer: Uint8Array;
     annotationsMaterial: ShaderMaterial;
-    fullscreenRenderer: FullscreenRenderer;
     annotationsData: AnnotationInstance[];
     isBusy: boolean;
     dataTextureNeedsUpdate: boolean;
+    fullscreenRenderer: FullscreenRenderer;
     unsubscribeListeners: () => void;
+    private prevCameraMatrix;
+    private prevPointerX;
+    private prevPointerY;
+    private prevSizeX;
+    private prevSizeY;
+    private occlusionChanged;
+    connectorTargetFrameTime: number;
+    connectorStretchSlack: number;
+    connectorRestStretch: number;
     constructor(camera: Camera, clock: Clock, pointer: Vector2, maxVisible?: number);
     updateAnnotationsData(buffer: Uint8Array): void;
     updateOverlayTexture(inViewSpace: AnnotationInstance[]): void;

package/dist/types/rendering/passes/FXAAPass.d.ts

@@ -0,0 +1,17 @@
+import { WebGLRenderer, WebGLRenderTarget } from 'three';
+import { Pass } from '../Pass';
+/**
+ * Standalone FXAA post pass. Wraps a {@link FxaaResolver} and composites it in
+ * place into the shared pipeline buffer, so it works after any base pass
+ * ({@link RenderPass} or {@link OITRenderPass}) — unlike the OIT-internal SMAA /
+ * temporal modes it does not require order-independent transparency.
+ *
+ * Insert it between the base pass and the {@link OutputPass}:
+ * `[base, new FXAAPass(), new OutputPass()]`.
+ */
+export declare class FXAAPass extends Pass {
+    private resolver;
+    setSize(width: number, height: number): void;
+    dispose(): void;
+    render(renderer: WebGLRenderer, buffer: WebGLRenderTarget): void;
+}