@equinor/videx-3d 1.1.1 → 3.0.0

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

@@ -0,0 +1,429 @@
+import { Camera, Scene, WebGLRenderer, WebGLRenderTarget } from 'three';
+import { Pass } from '../Pass';
+import { SMAAQuality } from '../smaa-resolver';
+import { TaaResolver } from '../taa-resolver';
+import { TemporalResolver } from '../temporal-resolver';
+/** 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;
+};
+/**
+ * Built-in anti-aliasing mode for {@link OITRenderPass.antialias}. See that field for
+ * the per-mode description. Exported as the single source of truth so consumers
+ * (and Storybook arg types) can reference it instead of re-declaring the union.
+ *
+ * @group Rendering
+ */
+export type OITAntialiasMode = 'none' | 'temporal' | 'smaa' | 'temporal-smaa' | 'taa' | 'fxaa';
+/**
+ * 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;
+    /**
+     * Number of MSAA samples (0 = off) for the hybrid multisample path. When > 0 the
+     * opaque geometry (including fully-opaque OIT occluders such as casings/completion
+     * tools), the emissive layer, the weighted-blended (WBOIT) tail composite, the exact
+     * front layer and the overlay are all rendered into ONE dedicated multisample target
+     * sharing the pipeline depth. The single-sample min-depth/accum aux targets read the
+     * opaque depth resolved on the first switch away from the multisample target; the
+     * final colour is resolved ONCE more and blitted into the single-sample pipeline
+     * buffer (~2 resolves total). This costs more than multisampling the opaque pass
+     * alone but far less than multisampling the whole half-float pipeline buffer
+     * (~4 resolves). Clamped to `renderer.capabilities.maxSamples`.
+     *
+     * **MSAA is not recommended with OIT.** The min-depth/accum aux buffers must be
+     * single-sample (WebGL2 cannot sample a multisample texture), so the transparent
+     * tail is composited single-sample over the multisample opaque edges. Opaque edges
+     * are matted against the cleared background before the transparent surfaces exist,
+     * and the single-sample composite cannot reconstruct per-sample coverage — so a
+     * background-coloured fringe survives along opaque and thin-line edges *over
+     * transparent surfaces*. This is structural and cannot be made clean here; only
+     * supersampling the whole composite (an {@link antialias} temporal mode, or the
+     * {@link RenderingPipeline} `supersample` prop) removes it.
+     *
+     * `opaqueSamples` is therefore intended only for the narrow **opaque-only** close-up
+     * (no transparent surfaces composited in front — e.g. a casing detail view), where
+     * the fringe cannot occur. For anything with transparent surfaces leave this at `0`
+     * and use {@link antialias} (temporal / SMAA / TAA / FXAA) or the
+     * {@link RenderingPipeline} `supersample` prop instead. (Pipeline-level `samples`
+     * does not anti-alias the OIT result either, and is only for a plain opaque
+     * `RenderPass` pipeline with no OIT.)
+     *
+     * Do not combine `opaqueSamples > 0` with an {@link antialias} temporal mode
+     * (`'temporal'`/`'temporal-smaa'`/`'taa'`): it is wasteful — the multisample colour
+     * is resolved first and the temporal resolver then runs on the already-resolved
+     * buffer, so you pay for MSAA rasterisation on top of temporal supersampling that
+     * already anti-aliases the same edges.
+     */
+    opaqueSamples: number;
+    /**
+     * Built-in anti-aliasing mode for the composited result.
+     *
+     * - `'none'`: no built-in AA. Pair with {@link opaqueSamples} (MSAA) for
+     *   opaque-edge AA in an opaque-only close-up; transparent/additive edges stay
+     *   un-anti-aliased, and MSAA leaves a background-coloured fringe over transparent
+     *   surfaces (see {@link opaqueSamples}).
+     * - `'temporal'`: temporal supersampling (see {@link TemporalResolver}). The camera
+     *   is sub-pixel jittered each frame and the composited frame is accumulated into a
+     *   running average **while the camera is still**, converging to a genuinely
+     *   supersampled image (thin trajectory lines, transparent-surface edges, contour
+     *   lines and the additive highlight all anti-alias). There is no reprojection, so
+     *   nothing ghosts; while the camera moves the current frame is shown un-jittered
+     *   (the moving frame is not anti-aliased unless combined with SMAA or MSAA).
+     * - `'smaa'`: subpixel morphological AA (see {@link smaaQuality}) applied as a
+     *   spatial post pass every frame. Anti-aliases moving frames too, but (like all
+     *   morphological techniques) cannot recover sub-pixel features such as 1px lines
+     *   that fall between samples.
+     * - `'temporal-smaa'`: both, mutually exclusive per frame — temporal accumulation
+     *   while the camera is still (crisp, recovers sub-pixel detail) and SMAA while it
+     *   moves. SMAA never softens the converged still image and only costs GPU time
+     *   during motion.
+     * - `'taa'` (default): reprojected temporal anti-aliasing (see {@link TaaResolver}).
+     *   Like `'temporal'` the camera is sub-pixel jittered, but the history is
+     *   reprojected every frame using the nearest visible surface's depth (opaque
+     *   hardware depth refined by the OIT front-layer depth), so anti-aliasing is
+     *   retained *during* camera motion. Ghosting from additive/animated/disoccluded
+     *   content is bounded by neighbourhood colour clamping. This is the recommended
+     *   default for the OIT pipeline — it anti-aliases both still and moving frames.
+     *   Use `'temporal'` instead if you need guaranteed ghost-free stills and don't
+     *   mind losing motion AA.
+     * - `'fxaa'`: fast approximate AA (see {@link FxaaResolver}) applied as a single
+     *   cheap spatial post pass every frame. Cheaper and softer than `'smaa'`, with no
+     *   OIT or temporal coupling. Like all spatial techniques it cannot recover
+     *   sub-pixel features. Also available as the standalone {@link FXAAPass} for
+     *   non-OIT (plain `RenderPass`) setups.
+     *
+     * The jitter is applied to the shared camera only between this pass's own scene
+     * render and resolve, so it never leaks to later passes (annotations, picking).
+     * This is the OIT pipeline's high-quality AA. Non-OIT setups (plain `RenderPass`)
+     * should use MSAA instead.
+     */
+    antialias: OITAntialiasMode;
+    /**
+     * SMAA quality preset used by the `'smaa'` and `'temporal-smaa'` {@link antialias}
+     * modes (default `'high'`). Ignored by the other modes.
+     */
+    smaaQuality: SMAAQuality;
+    /**
+     * The temporal-supersampling resolver, exposed for debug/tuning (e.g. its
+     * `clampStrength` anti-ghost knob). Non-null only while {@link antialias} is
+     * `'temporal'` / `'temporal-smaa'` and after at least one frame has rendered (it is
+     * created lazily and recreated on a mode switch, resetting to defaults).
+     */
+    get temporalResolver(): TemporalResolver | null;
+    /**
+     * The reprojected-TAA resolver, exposed for debug/tuning (e.g. its
+     * `restClampStrength` / `restBoxGamma` / `restNeighbourhoodRadius` anti-ghost knobs).
+     * Non-null only while {@link antialias} is `'taa'` and after at least one frame has
+     * rendered (it is created lazily and recreated on a mode switch, resetting to
+     * defaults).
+     */
+    get taaResolver(): TaaResolver | null;
+    /**
+     * 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;
+    /** Lazily-created temporal-supersampling resolver, used when {@link antialias} is `'temporal'`. */
+    private temporal;
+    /**
+     * Lazily-created reprojected-TAA resolver, used when {@link antialias} is `'taa'`.
+     */
+    private taa;
+    /**
+     * Lazily-created SMAA spatial resolver, used when {@link antialias} is `'smaa'` or
+     * `'temporal-smaa'`.
+     */
+    private smaa;
+    /** Lazily-created FXAA spatial resolver, used when {@link antialias} is `'fxaa'`. */
+    private fxaa;
+    private minDepthTarget;
+    private accumTarget;
+    private compositeMaterial;
+    /** Shared multisample target for the hybrid MSAA path (see {@link opaqueSamples}). */
+    private opaqueTarget;
+    /** Sample count the current opaqueTarget was built with (-1 = none yet). */
+    private opaqueTargetSamples;
+    /** Blit material: copy the resolved multisample colour into the buffer (no blending). */
+    private opaqueBlitMaterial;
+    /** 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);
+    /**
+     * Create or resize the shared multisample target, sharing the pipeline's depth
+     * texture so resolving writes the AA colour AND the resolved opaque depth the
+     * auxiliary OIT passes read. Recreated when sample count, size or shared depth
+     * texture changes.
+     */
+    private ensureOpaqueTarget;
+    private disposeOpaqueTarget;
+    setSize(width: number, height: number): void;
+    dispose(): void;
+    private getEntry;
+    /**
+     * Whether an OIT entry is currently fully invisible (every OIT-capable material
+     * has opacity ≤ 0). Such objects are hidden from all passes — they contribute
+     * nothing to any render target, so rasterising them (even through the cheap aux
+     * passes) is pure waste.
+     */
+    private isEntryInvisible;
+    /**
+     * 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 a material currently renders as fully invisible (opacity ≤ 0). */
+    private static isMaterialInvisible;
+    /**
+     * 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,19 @@
+import { MeshBasicMaterial, WebGLRenderer, WebGLRenderTarget } from 'three';
+import { FullscreenRenderer } from '../fullscreen-renderer';
+import { Pass } from '../Pass';
+/**
+ * Terminal pass: composites the pipeline's linear HDR buffer to the screen and
+ * applies tone mapping + sRGB output encoding once, for the whole buffer, via
+ * `renderer.toneMapping` / `toneMappingExposure` (`toneMapped: true` below).
+ *
+ * Because tone mapping is deferred to this single pass, scene materials must render
+ * linear (`toneMapped: false`) or they double-tone-map, and the per-material
+ * `toneMapped = false` opt-out is not honored. See documents/oit-guide.md §7.
+ */
+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,10 @@
+import { Camera, Scene, WebGLRenderer, WebGLRenderTarget } from 'three';
+import { Pass } from '../Pass';
+export declare class RenderPass extends Pass {
+    private scene;
+    private camera;
+    /** Reused scratch for saving the renderer clear colour (no per-frame alloc). */
+    private prevClearColor;
+    constructor(scene: Scene, camera: Camera);
+    render(renderer: WebGLRenderer, buffer: WebGLRenderTarget): void;
+}

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

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

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/rendering/smaa-resolver.d.ts

@@ -0,0 +1,58 @@
+import { WebGLRenderer, WebGLRenderTarget } from 'three';
+/**
+ * Quality preset for SMAA. Higher presets lower the edge-detection threshold (so
+ * fainter edges are anti-aliased) and increase the orthogonal search distance (so
+ * longer near-horizontal/vertical edges are reconstructed). The underlying
+ * three-stdlib SMAA shaders do not implement the reference SMAA's diagonal search
+ * and corner rounding, so those are unaffected by the preset.
+ *
+ * @group Rendering
+ */
+export type SMAAQuality = 'low' | 'medium' | 'high' | 'ultra';
+/**
+ * Subpixel Morphological Anti-Aliasing (SMAA) resolver, used internally by
+ * {@link OITRenderPass} when its `antialias` mode is `'smaa'` or `'temporal-smaa'`.
+ * It detects edges by colour discontinuity and reconstructs anti-aliased
+ * silhouettes using precomputed area/search lookup tables, giving clean long edges
+ * with little detail blurring.
+ *
+ * It operates in linear space (the OIT buffer is linear FP16) but detects edges on
+ * an sRGB-encoded copy so the perceptual thresholds behave as intended; the blend
+ * and output stay linear, so brightness is untouched.
+ *
+ * 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 a {@link FullscreenRenderer}, compositing the
+ * result back into the shared buffer in place.
+ *
+ * Like all morphological techniques it cannot recover sub-pixel features (e.g. 1px
+ * WebGL lines that fall between samples) — those are handled by the temporal
+ * supersampling mode while the camera is still.
+ */
+export declare class SmaaResolver {
+    private inner;
+    private scratch;
+    private encoded;
+    private encodeMaterial;
+    private blitMaterial;
+    private fullscreenRenderer;
+    private materialEdges;
+    private materialWeights;
+    private materialBlend;
+    private _quality;
+    /** Reused scratch for saving the renderer clear colour each frame (no per-frame alloc). */
+    private prevClearColor;
+    constructor(quality?: SMAAQuality);
+    /**
+     * Quality preset (default `'high'`). Assigning it rewrites the edge-detection
+     * threshold and orthogonal search-distance shader defines and recompiles the two
+     * affected sub-pass programs. The recompile only happens when the value actually
+     * changes, so reading/writing the same value every frame is free.
+     */
+    get quality(): SMAAQuality;
+    set quality(value: SMAAQuality);
+    private applyQuality;
+    setSize(width: number, height: number): void;
+    dispose(): void;
+    render(renderer: WebGLRenderer, buffer: WebGLRenderTarget): void;
+}