@equinor/videx-3d 1.1.0 → 2.0.0

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,19 @@ 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;
     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,12 @@
+import { WebGLRenderer, WebGLRenderTarget } from 'three';
+import { Pass } from '../Pass';
+export declare class FxaaPass extends Pass {
+    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/passes/OITRenderPass.d.ts

@@ -0,0 +1,282 @@
+import { Camera, Scene, WebGLRenderer, WebGLRenderTarget } from 'three';
+import { Pass } from '../Pass';
+/** Per-frame object counts for each classification, exposed for debugging. */
+export type OITRenderPassStats = {
+    /** Plain opaque renderables (not OIT-capable, not overlay). */
+    opaque: number;
+    /** OIT-capable renderables currently transparent (routed through OIT). */
+    oit: number;
+    /**
+     * OIT-capable renderables that are currently fully opaque and therefore drawn in
+     * the opaque pass as real occluders (depth-writing), bypassing the OIT passes.
+     */
+    oitOpaque: number;
+    /** Additive/glow renderables (tagged `LAYERS.EMISSIVE`), drawn before the transparent layers. */
+    emissive: number;
+    /** Always-on-top renderables (tagged `LAYERS.OVERLAY`), drawn after the transparent layers. */
+    overlay: number;
+    /** Subset of `oit` whose whole material is OIT-capable (hidden in opaque pass). */
+    oitHidden: number;
+    /** Subset of `oit` that are mixed multi-material meshes (some opaque groups). */
+    oitMixed: number;
+};
+/**
+ * Resource/accumulation counters for leak monitoring. Unlike {@link OITRenderPassStats}
+ * (per-frame object classification, which naturally varies with the camera), these
+ * track internal structures and global GPU resources that should stay *bounded* over
+ * time. Watch them while toggling the pipeline on/off (which recreates the passes): a
+ * steady climb indicates passes or GPU resources are not being disposed.
+ */
+export type OITRenderPassResources = {
+    /**
+     * Active OIT pipeline registrations on this canvas (the ref-counted
+     * {@link RenderingState} `_oitCount`). Should read 1 while a single OIT pipeline is
+     * mounted; a value that climbs each time the pipeline is recreated means a pass was
+     * acquired but never released in {@link OITRenderPass.dispose} (a real leak).
+     */
+    oitPipelines: number;
+    /**
+     * Total classification entries created since this pass instance was constructed
+     * (monotonic). Resets only when the pass itself is recreated, so it grows quickly
+     * during warm-up and should then plateau.
+     */
+    entriesTotal: number;
+    /**
+     * Classification entries created this frame (cache misses). ~0 in steady state; a
+     * persistently non-zero value means object material identities churn every frame,
+     * which also churns the cached per-pass OIT variants.
+     */
+    entriesThisFrame: number;
+    /** GPU textures currently tracked by the renderer (global; watch for unbounded growth). */
+    textures: number;
+    /** GPU geometries currently tracked by the renderer (global). */
+    geometries: number;
+    /** Compiled shader programs currently held by the renderer (global). `-1` if unavailable. */
+    programs: number;
+};
+/**
+ * Per-segment GPU timings in milliseconds, populated when {@link OITRenderPass.profile}
+ * is enabled and the platform supports timer queries. `-1` means "no result yet"
+ * (or unsupported). `tail` is the single weighted-blended OIT pass cost.
+ */
+export type OITRenderPassTimings = {
+    /** Opaque pass (step 1), including any forced-opaque OIT occluders. */
+    opaque: number;
+    /** Additive/glow emissive pass (step 1b). */
+    emissive: number;
+    /** Min-depth pre-pass (step 2). */
+    minDepth: number;
+    /** Weighted-blended OIT tail pass (step 3). */
+    tail: number;
+    /** Fullscreen tail composite (step 4). */
+    composite: number;
+    /** Exact front-layer pass (step 5). */
+    front: number;
+    /** Optional occlusion depth-stamp pass (step 5b). */
+    occlusion: number;
+    /** Optional emitter depth-stamp pass (step 1c). */
+    emitterStamp: number;
+    /** Always-on-top overlay pass (step 6). */
+    overlay: number;
+    /** Sum of the measured OIT segments above. */
+    total: number;
+};
+/**
+ * Hybrid order-independent-transparency (OIT) render pass for use with the
+ * {@link RenderingPipeline} (or any custom composer). Renders the nearest transparent
+ * layer exactly (depth-peeled, alpha-over) and the remaining layers using
+ * weighted-blended OIT (WBOIT), partitioned per-pixel in view-space linear depth.
+ *
+ * Transparency is opt-in: this pass only affects materials that are OIT-capable
+ * (library materials, or stock/user materials patched with `makeOitCompatible`).
+ * Two per-object escape-hatch layers override the default routing: `LAYERS.FORCE_OPAQUE`
+ * draws the object as a depth-writing opaque occluder (its material is temporarily
+ * forced to `depthWrite=true, transparent=false`); `LAYERS.OIT_EXCLUDED` also draws it
+ * in the opaque pass but leaves the material's own properties untouched.
+ * Additive/glow objects tagged with the `LAYERS.EMISSIVE` layer are drawn between the
+ * opaque and transparent layers (so transparent surfaces in front attenuate them);
+ * always-on-top objects tagged with the `LAYERS.OVERLAY` layer are drawn last, on top
+ * of the resolved transparency. While this pass is active it sets the per-canvas
+ * rendering state to `'oit'` so components can disable conflicting self-transparency
+ * workarounds.
+ *
+ * @example
+ * ```tsx
+ * const passes = useMemo(
+ *   () => [new OITRenderPass(scene, camera), new OutputPass()],
+ *   [scene, camera],
+ * );
+ * return <RenderingPipeline passes={passes} />;
+ * ```
+ *
+ * @group Rendering
+ * @see {@link RenderingPipeline}
+ * @see {@link makeOitCompatible}
+ */
+export declare class OITRenderPass extends Pass {
+    private scene;
+    private camera;
+    /**
+     * Debug: when true, the exact depth-peeled front layer is disabled and every
+     * transparent fragment is resolved through the weighted-blended (WBOIT) tail.
+     * Useful for isolating tail behaviour and comparing against the hybrid result.
+     */
+    skipFront: boolean;
+    /**
+     * Optional feature (default off): after the transparent OIT passes, stamp depth
+     * for transparent surfaces wherever their own alpha is at least
+     * {@link occlusionDepthThreshold}. Transparent surfaces normally write no depth, so
+     * annotation labels behind a high-but-not-full opacity surface are never occluded;
+     * enabling this makes a surface occlude labels once its alpha clears the threshold.
+     *
+     * The test is per-fragment and per-surface (each surface judged on its own alpha,
+     * not accumulated coverage), and the stamped depth uses the same encoding the
+     * {@link AnnotationsPass} already samples. Costs one extra transparent-geometry
+     * pass per frame when enabled; nothing (not even a shader compile) when off.
+     */
+    occlusionDepthStamp: boolean;
+    /** Alpha threshold (0..1) for {@link occlusionDepthStamp}. Default 0.5. */
+    occlusionDepthThreshold: number;
+    /**
+     * Optional feature (default off): stamp depth for emissive/glow emitters (objects
+     * on `LAYERS.EMISSIVE`) wherever their fragment strength is at least
+     * {@link emitterDepthThreshold}, drawn before the transparent OIT passes. This lets
+     * the dense core of an additive emitter (e.g. perforation jets) occlude transparent
+     * surfaces behind it, preventing the wash-out where a far transparent surface would
+     * otherwise dim the emitter. Surfaces in front still attenuate it.
+     *
+     * An emitter opts in by exposing a depth-only stamp material on its material's
+     * `userData.occlusionDepthMaterial` (with a `uOcclusionThreshold` uniform the pass
+     * drives). Emitters without one are simply skipped. Costs one extra emissive pass
+     * per frame when enabled; nothing when off.
+     */
+    emitterDepthStamp: boolean;
+    /** Strength threshold (0..1) for {@link emitterDepthStamp}. Default 0.5. */
+    emitterDepthThreshold: number;
+    /**
+     * When true, draws small thumbnails of the internal render targets (min-depth,
+     * accumulation) into the bottom-left of the output, for debugging.
+     * GPU-only; no pixel readback.
+     */
+    debugTargets: boolean;
+    /**
+     * When true, measures per-segment GPU time (opaque/emissive/min-depth/tail/
+     * composite/front/overlay) via timer queries and exposes it on {@link timings}. Adds a
+     * little CPU/driver overhead and lags a few frames, so it is off by default. No-op
+     * on platforms without `EXT_disjoint_timer_query_webgl2`.
+     *
+     * The most relevant figure for the transparent-geometry cost is
+     * {@link OITRenderPassTimings.tail}.
+     */
+    profile: boolean;
+    /**
+     * Per-segment GPU timings (ms) from the last completed measurement. Only updated
+     * while {@link profile} is enabled. `-1` means "no result yet" or unsupported.
+     */
+    readonly timings: OITRenderPassTimings;
+    /**
+     * Per-frame object counts for each pass, updated every {@link render}. Useful for
+     * verifying which objects are routed through OIT vs. drawn opaque/overlay.
+     */
+    readonly stats: OITRenderPassStats;
+    /**
+     * Resource/accumulation counters for leak monitoring, updated every {@link render}.
+     * See {@link OITRenderPassResources}.
+     */
+    readonly resources: OITRenderPassResources;
+    private fullscreenRenderer;
+    private minDepthTarget;
+    private accumTarget;
+    private compositeMaterial;
+    /** Lazily-created material for the debug-target thumbnails. */
+    private debugMaterial;
+    /** Lazily-created GPU timer, only when {@link profile} is first enabled. */
+    private gpuTimer;
+    /**
+     * OIT pipeline registration release handle. Acquired lazily on the first
+     * {@link render} rather than in the constructor: the host (e.g. a `useMemo`) may
+     * construct passes that React then discards without ever committing/rendering them,
+     * and a constructor-time acquire on such an orphan would never be released. Only
+     * committed passes are rendered, so acquiring here keeps the registration count
+     * symmetric with {@link dispose}.
+     */
+    private releaseOit?;
+    private entryCache;
+    /** Monotonic count of classification entries created (cache misses). */
+    private entriesCreated;
+    /** Saved material state for OIT objects temporarily forced opaque this frame. */
+    private forcedOpaque;
+    private width;
+    private height;
+    private depthFar;
+    constructor(scene: Scene, camera: Camera);
+    setSize(width: number, height: number): void;
+    dispose(): void;
+    private getEntry;
+    /**
+     * Traverse the scene once, classifying renderables into transparent-OIT,
+     * plain-opaque, emissive (additive/glow) and always-on-top overlay sets.
+     * OIT-capable objects that are currently fully opaque, or explicitly tagged with
+     * the `LAYERS.FORCE_OPAQUE` layer, are added to both `opaqueList` (for the
+     * visibility lifecycle) and `oitOpaqueList` (so their materials can be forced
+     * depth-writing), making them real occluders. Objects tagged `LAYERS.OIT_EXCLUDED`
+     * are added to `opaqueList` only, so they render with their material untouched.
+     * Emissive objects are detected by the EMISSIVE layer, overlay objects by the
+     * OVERLAY layer.
+     */
+    private collect;
+    /**
+     * Prepare the OIT renderables for the opaque pass. Objects whose whole material
+     * is OIT-capable are simply hidden (and collected into `hidden` for restore), so
+     * their geometry isn't rasterised at all. Mixed multi-material meshes are swapped
+     * to their opaque variant (opaque groups kept, OIT groups drawn as no-op).
+     */
+    private applyOpaqueSwap;
+    private applyPassSwap;
+    private restoreMaterials;
+    private setOitUniforms;
+    private setVisible;
+    /**
+     * Resolve the opt-in depth-stamp material for an emissive emitter, if any. The
+     * emitter exposes it on `material.userData.occlusionDepthMaterial`; this also drives
+     * its `uOcclusionThreshold` uniform from {@link emitterDepthThreshold}. Returns null
+     * when the emitter provides no stamp material (it is then skipped).
+     */
+    private getEmitterStamp;
+    /**
+     * Current effective opacity of a material. `ShaderMaterial`s drive opacity through
+     * a `uniforms.opacity` value (the material's own `opacity` field is often left at
+     * 1), so prefer that; otherwise use `Material.opacity`.
+     */
+    private static effectiveOpacity;
+    /** Whether a material currently renders as fully opaque. */
+    private static isMaterialOpaque;
+    /**
+     * Whether an OIT entry is currently fully opaque (every OIT-capable material is
+     * opaque). Such objects are drawn in the opaque pass as real occluders instead of
+     * being routed through the (more expensive, depth-non-writing) OIT passes.
+     */
+    private isEntryOpaque;
+    /**
+     * Temporarily force the OIT-capable materials of the given entries to write depth
+     * and render opaque, so they act as genuine occluders during the opaque pass. The
+     * previous state is saved and restored by {@link restoreForcedOpaque}. These
+     * objects are hidden during the OIT sub-passes, so the forced state only takes
+     * effect where intended.
+     */
+    private applyForcedOpaque;
+    private restoreForcedOpaque;
+    /**
+     * Copy the latest smoothed GPU timings out of the timer into {@link timings} and
+     * recompute the `total`. Segments without a result yet (or skipped this frame)
+     * report `-1` and are excluded from the total.
+     */
+    private updateTimings;
+    render(renderer: WebGLRenderer, buffer: WebGLRenderTarget): void;
+    /**
+     * Draw small thumbnails of the auxiliary render targets along the bottom-left of
+     * the output buffer (min-depth, accumulation). Uses the buffer's viewport
+     * to scope each draw; GPU-only.
+     */
+    private renderDebugTargets;
+}

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

@@ -0,0 +1,10 @@
+import { MeshBasicMaterial, WebGLRenderer, WebGLRenderTarget } from 'three';
+import { FullscreenRenderer } from '../fullscreen-renderer';
+import { Pass } from '../Pass';
+export declare class OutputPass extends Pass {
+    fullscreenRenderer: FullscreenRenderer;
+    material: MeshBasicMaterial;
+    constructor();
+    render(renderer: WebGLRenderer, buffer: WebGLRenderTarget): void;
+    dispose(): void;
+}

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

@@ -0,0 +1,8 @@
+import { Camera, Scene, WebGLRenderer, WebGLRenderTarget } from 'three';
+import { Pass } from '../Pass';
+export declare class RenderPass extends Pass {
+    private scene;
+    private camera;
+    constructor(scene: Scene, camera: Camera);
+    render(renderer: WebGLRenderer, buffer: WebGLRenderTarget): void;
+}

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

@@ -0,0 +1,40 @@
+import { Vector2, WebGLRenderer, WebGLRenderTarget } from 'three';
+import { Pass } from '../Pass';
+/**
+ * Subpixel Morphological Anti-Aliasing (SMAA) post-process pass for use with the
+ * {@link RenderingPipeline}. A drop-in alternative to {@link FxaaPass}: it detects
+ * edges by colour discontinuity and reconstructs anti-aliased silhouettes using
+ * precomputed area/search lookup tables, giving noticeably cleaner long edges on
+ * opaque geometry than FXAA, with less detail blurring.
+ *
+ * SMAA operates in linear space and must run before the {@link OutputPass} (i.e.
+ * before tone-mapping / output-encoding), exactly like {@link FxaaPass}.
+ *
+ * Like all morphological techniques it cannot recover sub-pixel features (e.g.
+ * 1px WebGL lines that fall between samples) — use {@link TAAPass} for those.
+ *
+ * This wraps the well-tested SMAA shaders and lookup textures from `three-stdlib`
+ * and drives the three sub-passes (edge detection, blend-weight calculation,
+ * neighbourhood blending) through the pipeline's {@link FullscreenRenderer},
+ * compositing the result back into the shared buffer in place.
+ *
+ * @group Rendering
+ * @see {@link RenderingPipeline}
+ * @see {@link FxaaPass}
+ * @see {@link TAAPass}
+ */
+export declare class SMAAPass extends Pass {
+    private inner;
+    private scratch;
+    private blitMaterial;
+    private fullscreenRenderer;
+    private materialEdges;
+    private materialWeights;
+    private materialBlend;
+    constructor();
+    setSize(width: number, height: number): void;
+    dispose(): void;
+    render(renderer: WebGLRenderer, buffer: WebGLRenderTarget): void;
+    /** Resolution uniform helper kept for parity with other passes. */
+    get resolution(): Vector2;
+}

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

@@ -0,0 +1,94 @@
+import { Camera, WebGLRenderer, WebGLRenderTarget } from 'three';
+import { Pass } from '../Pass';
+/**
+ * Temporal Anti-Aliasing pass (jittered accumulation) for use with the
+ * {@link RenderingPipeline}.
+ *
+ * Each frame the camera's projection is offset by a sub-pixel jitter from a
+ * Halton(2,3) sequence and the freshly rendered buffer is accumulated into a
+ * history target as a running average. Because the 1px-line problem with
+ * supersampling is that the line stays one device-pixel wide as the buffer
+ * grows, jittered accumulation is the technique that *does* anti-alias thin
+ * features: the same 1px line lands on slightly different sub-pixel positions
+ * each frame, so the average is coverage-weighted without thinning.
+ *
+ * The accumulation resets whenever the (un-jittered) camera view changes, so an
+ * orbit-and-inspect workflow converges to near-supersampled quality within a
+ * handful of static frames. Once the full jitter sequence has accumulated the
+ * pass freezes (no further jitter or blending) and presents the converged image
+ * until the next camera move, so a still camera settles to a stable result.
+ * Place it where you would place {@link FxaaPass} — before the {@link OutputPass}.
+ *
+ * Limitations (no history reprojection / neighbourhood clamping): animated
+ * content that moves while the camera is static (e.g. additive jet streams) does
+ * not update once the image has converged and frozen, and ghosts before then.
+ * Camera motion itself never ghosts because it triggers a reset.
+ *
+ * @todo Improve TAA. Current trade-offs to address: (1) AA is only present once
+ * the camera settles — during motion the image is un-anti-aliased and it takes
+ * roughly a second of stillness to converge; (2) because the pass freezes on
+ * convergence, content that changes while the camera is static (a highlight
+ * toggled on, async geometry finishing loading) does not appear until the next
+ * camera move. A proper fix needs motion vectors + history reprojection +
+ * neighbourhood colour clamping so the history can be reused under motion and
+ * invalidated per-pixel on content change, rather than the all-or-nothing
+ * reset-on-camera-move + freeze-on-convergence heuristic used here. Likely
+ * revisited as part of the WebGPU/TSL renderer migration.
+ *
+ * @group Rendering
+ * @see {@link RenderingPipeline}
+ * @see {@link FxaaPass}
+ * @see {@link SMAAPass}
+ */
+export declare class TAAPass extends Pass {
+    private camera;
+    /**
+     * Number of unique jitter samples to cycle through before the average is
+     * considered fully converged. Higher = smoother but slower to settle.
+     */
+    sampleCount: number;
+    private historyRead;
+    private historyWrite;
+    private resolveMaterial;
+    private blitMaterial;
+    private fullscreenRenderer;
+    private width;
+    private height;
+    /** Index into the jitter sequence for the current frame. */
+    private sampleIndex;
+    /** How many frames have been accumulated since the last reset. */
+    private accumulated;
+    /** Jitter (in clip-space units) currently baked into the camera projection. */
+    private appliedJitterX;
+    private appliedJitterY;
+    /** Snapshot of the previous frame's camera state used to detect motion. The
+     * view matrix and the projection are stored separately so the two projection
+     * elements we jitter can be excluded from the comparison (see `detectMotion`). */
+    private prevView;
+    private prevProjection;
+    private hasPrev;
+    constructor(camera: Camera, sampleCount?: number);
+    setSize(width: number, height: number): void;
+    dispose(): void;
+    /** Force the accumulation to restart on the next frame. */
+    reset(): void;
+    /** Indices into the projection matrix offset elements for the active camera. */
+    private jitterElements;
+    private clearJitter;
+    private applyJitter;
+    /**
+     * Compare the current camera against the previous frame and reset the
+     * accumulation on any real view change (orbit, pan, zoom, fov).
+     *
+     * Motion is measured from the camera's view matrix (`matrixWorldInverse`,
+     * which we never touch) and its projection matrix *excluding* the two elements
+     * we jitter (`ex`/`ey`). This is critical: deriving motion from a quantity that
+     * includes our own sub-pixel jitter — or trying to subtract the jitter back out
+     * of the projection — couples the test to the jitter and makes every frame look
+     * like motion (the jitter delta dwarfs the tolerance), so the accumulation
+     * resets forever and the image never settles. By ignoring the jittered slots
+     * outright, only genuine camera changes trigger a reset.
+     */
+    private detectMotion;
+    render(renderer: WebGLRenderer, buffer: WebGLRenderTarget): void;
+}

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

@@ -0,0 +1,6 @@
+export * from './FXAAPass';
+export * from './OITRenderPass';
+export * from './OutputPass';
+export * from './RenderPass';
+export * from './SMAAPass';
+export * from './TAAPass';

package/dist/types/rendering/rendering-state.d.ts

@@ -0,0 +1,59 @@
+import { Object3D } from 'three';
+import { StoreApi } from 'zustand/vanilla';
+/**
+ * Transparency rendering mode currently active for a given scene/canvas.
+ *
+ * - `'standard'`: default rendering, as if no custom rendering pipeline is used.
+ *   Components apply their default self-transparency workarounds.
+ * - `'oit'`: an order-independent-transparency pipeline (e.g. {@link OITRenderPass})
+ *   is active. Components should disable workarounds that conflict with OIT (such as
+ *   depth-only mask passes) and let the pipeline resolve transparency.
+ */
+export type TransparencyMode = 'standard' | 'oit';
+/**
+ * Per-canvas rendering pipeline state.
+ *
+ * Lets components react to which rendering pipeline (if any) is active without the
+ * user having to manually configure each component. The defaults match the behavior
+ * of default rendering with no custom pipeline.
+ *
+ * @group Rendering
+ */
+export type RenderingState = {
+    /** The active transparency mode. Defaults to `'standard'`. */
+    transparencyMode: TransparencyMode;
+    /** @internal reference count of active OIT pipelines. */
+    _oitCount: number;
+    /**
+     * Register an active OIT pipeline. Sets {@link RenderingState.transparencyMode}
+     * to `'oit'`. Returns a release function that must be called when the pipeline is
+     * disposed; the mode reverts to `'standard'` once all registrations are released.
+     * Reference counted so multiple/short-lived passes behave correctly.
+     */
+    acquireOit: () => () => void;
+};
+/**
+ * Get (or lazily create) the {@link RenderingState} store for a given scene.
+ *
+ * Both the rendering passes (which hold a reference to the scene) and the hooks used
+ * by components (which resolve the scene via R3F) call this with the same scene, so
+ * they share a single store instance per canvas. No provider is required — the store
+ * is created on first access, so components used without any pipeline still work and
+ * simply observe the `'standard'` default.
+ *
+ * @group Rendering
+ */
+export declare function getRenderingState(scene: Object3D): StoreApi<RenderingState>;
+/**
+ * Hook to read the per-canvas {@link RenderingState}. Resolves the store from the
+ * current R3F scene, so it must be used inside a `Canvas`.
+ *
+ * @example
+ * ```tsx
+ * const isOit = useRenderingState(state => state.transparencyMode === 'oit');
+ * ```
+ *
+ * @group Hooks
+ * @category Rendering
+ */
+export declare function useRenderingState<T>(selector: (state: RenderingState) => T): T;

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

@@ -11,7 +11,9 @@ export * from './geometries/curve/curve-3d';
 export * from './geometries/curve/tube-geometry';
 export * from './geometries/delatin';
 export * from './geometries/fence';
+export * from './geometries/geometry';
 export * from './geometries/packing';
+export * from './geometries/planar-geometry';
 export * from './geometries/triangulate-grid';
 export * from './geometries/triangulate-grid-delaunay';
 export * from './managers/CameraManager';

package/dist/types/sdk/utils/elevation-map.d.ts

@@ -13,3 +13,26 @@ export declare function createNormalTexture(buffer: Uint8Array, width: number, h
  * Create a data texture from RGBA encoded depth values
  */
 export declare function createElevationTexture(buffer: Float32Array, width: number, height: number): DataTexture;
+/**
+ * Compute geometric surface normals from an elevation grid, encoded as a compact
+ * RG8 buffer (2 bytes/texel) using a hemisphere encoding: only the grid-local
+ * `x` and `z` components are stored (mapped to [0, 1]); the consumer reconstructs
+ * `y = sqrt(1 - x^2 - z^2)`.
+ *
+ * This replicates the per-fragment normal that `SurfaceMaterial`'s shader derives
+ * from the elevation texture (same four diagonal neighbours, cross products and
+ * hole handling), but pays the cost once on the CPU instead of in every OIT pass.
+ * The result is laid out to match the elevation buffer (row-major, intended for a
+ * `flipY = true` texture), so it samples 1:1 with the same grid UVs.
+ *
+ * @param data elevation values (row-major, holes < 0)
+ * @param columns number of columns (nx)
+ * @param rows number of rows (ny)
+ * @param xScale column spacing (xinc)
+ * @param yScale row spacing (yinc)
+ */
+export declare function computeSurfaceNormalsRG(data: Float32Array, columns: number, rows: number, xScale: number, yScale: number): Uint8Array<ArrayBuffer>;
+/**
+ * Create an RG8 data texture from a buffer produced by {@link computeSurfaceNormalsRG}.
+ */
+export declare function createPackedNormalTexture(buffer: Uint8Array, width: number, height: number): DataTexture;

package/dist/types/sdk/utils/trigonometry.d.ts

@@ -8,5 +8,8 @@ export declare const PI8: number;
  * Given a 2D rectangle and an angle off the center, find the point
  * of the closest corner. Used for anchoring connector lines
  * to annotation labels.
+ *
+ * Pass an optional `target` array to write the result into, avoiding
+ * an allocation in hot paths.
  */
-export declare function edgeOfRectangle(rect: Vec2, theta: number): Vec2;
+export declare function edgeOfRectangle(rect: Vec2, theta: number, target?: Vec2): Vec2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/videx-3d",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "private": false,
   "type": "module",
   "license": "MIT",