@idetik/core 0.45.4 → 0.45.5

package/dist/index.d.ts

@@ -1011,181 +1011,6 @@ declare class EventDispatcher {
     private readonly handleEvent;
 }
 
-/**
- * The loading lifecycle state of a layer.
- */
-type LayerState = "initialized" | "loading" | "ready";
-/**
- * How a layer's output blends with previously drawn content.
- */
-type BlendMode = "none" | "normal" | "additive" | "subtractive" | "multiply" | "premultipliedOver";
-/**
- * A callback invoked after a layer's state changes.
- */
-type StateChangeCallback = (newState: LayerState, prevState?: LayerState) => void;
-/**
- * Initialization properties for constructing a layer.
- */
-type LayerProps = {
-    /** Layer opacity in `[0, 1]`. Defaults to `1`. */
-    opacity?: number;
-    /** How the layer blends. Defaults to `"none"`. */
-    blendMode?: BlendMode;
-    /** Hides content behind. Inferred from `blendMode`. */
-    occludes?: boolean;
-};
-/**
- * Abstract base class for any layer that can be added to a viewport.
- *
- * A layer owns a set of renderable objects and contributes them to the
- * scene each frame. Subclasses such as {@link ImageLayer},
- * {@link VolumeLayer}, and {@link LabelLayer} implement {@link update} to
- * build or refresh those objects for the current view. Custom layers
- * register objects with {@link addObject} and report readiness through
- * {@link setState}.
- *
- * Layers carry shared presentation state in {@link opacity},
- * {@link blendMode}, and {@link occludes}, and expose a lifecycle
- * {@link LayerState} that observers can subscribe to. A layer instance may
- * be attached to only one viewport at a time.
- *
- * ```ts
- * class Particles extends Layer {
- *   public readonly type = "Particles";
- *
- *   constructor(points: PointProps[]) {
- *     super();
- *     this.addObject(new PointsRenderable(points));
- *     this.setState("ready");
- *   }
- *
- *   public update() {}
- * }
- *
- * viewport.addLayer(new Particles(points));
- * ```
- *
- * @group Layers
- */
-declare abstract class Layer {
-    /** A string identifying the concrete layer type. */
-    abstract readonly type: string;
-    /**
-     * How the layer's output blends with previously drawn content. Also
-     * applies to blending between objects within the layer.
-     */
-    blendMode: BlendMode;
-    /**
-     * Whether the layer writes depth and hides content drawn behind it.
-     *
-     * Occluding layers render a depth pass and always draw before
-     * non-occluding layers regardless of their order in the viewport. When
-     * not set explicitly this value is inferred from `blendMode` at
-     * construction only. Reassigning {@link blendMode} later does not update
-     * it.
-     */
-    occludes: boolean;
-    /** Set to `true` by subclasses whose shaders read scene depth. */
-    protected requiresSceneDepth_: boolean;
-    private readonly coverageGroups_;
-    private state_;
-    private attached_;
-    private readonly callbacks_;
-    private opacity_;
-    /**
-     * Creates a layer with the given presentation state.
-     *
-     * @param props - Initialization properties.
-     */
-    constructor({ opacity, blendMode, occludes, }?: LayerProps);
-    /**
-     * Whether the layer's shaders read scene depth. When `true` the renderer
-     * draws occluding layers to a depth texture the layer's shaders can
-     * sample. A layer cannot both occlude and read scene depth.
-     */
-    get requiresSceneDepth(): boolean;
-    /** The layer's opacity in `[0, 1]`. Values outside are clamped. */
-    get opacity(): number;
-    /** @param value - The new opacity in `[0, 1]`. */
-    set opacity(value: number);
-    /**
-     * Builds or refreshes the layer's renderable objects for the current
-     * view. Called automatically once per frame for every layer in a
-     * viewport.
-     *
-     * @param viewport - The viewport being rendered.
-     */
-    abstract update(viewport?: Viewport): void;
-    /**
-     * Handles a pointer or wheel event from the owning viewport. Called
-     * automatically for each event before the camera controls. The default
-     * implementation does nothing.
-     *
-     * @param _event - The event with clip and world coordinates attached.
-     */
-    onEvent(_event: EventContext): void;
-    /**
-     * Lifecycle hook that is called automatically when a layer is
-     * is attached to a viewport. A layer can only be attached to one viewport
-     * at a time.
-     *
-     * @param context - The shared runtime context.
-     */
-    onAttached(context: IdetikContext): void;
-    /**
-     * Lifecycle hook that is called automatically when a layer is detached
-     * from a viewport.
-     *
-     * @param context - The shared runtime context.
-     */
-    onDetached(context: IdetikContext): void;
-    /** @hidden */
-    protected attach(_context: IdetikContext): void;
-    /** @hidden */
-    protected detach(_context: IdetikContext): void;
-    /**
-     * The layer's renderable objects grouped by coverage group. Objects in
-     * a group draw each pixel at most once, letting chunks at multiple
-     * levels of detail overlap correctly.
-     */
-    get coverageGroups(): ReadonlyMap<number | null, readonly RenderableObject[]>;
-    /** The layer's current lifecycle state. */
-    get state(): LayerState;
-    /**
-     * Registers a callback invoked after every state change.
-     *
-     * @param callback - Receives the new and previous states.
-     */
-    addStateChangeCallback(callback: StateChangeCallback): void;
-    /**
-     * Removes a previously registered state change callback.
-     *
-     * @param callback - The callback to remove.
-     */
-    removeStateChangeCallback(callback: StateChangeCallback): void;
-    /**
-     * Sets the lifecycle state and notifies state change callbacks.
-     *
-     * @param newState - The state to enter.
-     */
-    protected setState(newState: LayerState): void;
-    /**
-     * Registers a renderable object for drawing. Objects in the same
-     * coverage group draw each pixel at most once.
-     *
-     * @param object - The object to add.
-     * @param coverageGroup - The group key.
-     */
-    protected addObject(object: RenderableObject, coverageGroup?: number | null): void;
-    /** Removes all registered renderable objects. */
-    protected clearObjects(): void;
-    /**
-     * Returns uniform name-value pairs applied to every object drawn by
-     * this layer. Override in subclasses that need custom shader uniforms.
-     */
-    getUniforms(): Record<string, unknown>;
-}
-
 /**
  * A world-space rectangle for the camera to frame.
  */
@@ -1556,6 +1381,251 @@ declare class Viewport {
     private updateAspectRatio;
 }
 
+/**
+ * The loading lifecycle state of a layer.
+ */
+type LayerState = "initialized" | "loading" | "ready";
+/**
+ * How a layer's output blends with previously drawn content.
+ */
+type BlendMode = "none" | "normal" | "additive" | "subtractive" | "multiply" | "premultipliedOver";
+/**
+ * A callback invoked after a layer's state changes.
+ */
+type StateChangeCallback = (newState: LayerState, prevState?: LayerState) => void;
+/**
+ * Initialization properties for constructing a layer.
+ */
+type LayerProps = {
+    /** Layer opacity in `[0, 1]`. Defaults to `1`. */
+    opacity?: number;
+    /** How the layer blends. Defaults to `"none"`. */
+    blendMode?: BlendMode;
+    /** Hides content behind. Inferred from `blendMode`. */
+    occludes?: boolean;
+};
+/**
+ * Abstract base class for any layer that can be added to a viewport.
+ *
+ * A layer owns a set of renderable objects and contributes them to the
+ * scene each frame. Subclasses such as {@link ImageLayer},
+ * {@link VolumeLayer}, and {@link LabelLayer} implement {@link update} to
+ * build or refresh those objects for the current view. Custom layers
+ * register objects with {@link addObject} and report readiness through
+ * {@link setState}.
+ *
+ * Layers carry shared presentation state in {@link opacity},
+ * {@link blendMode}, and {@link occludes}, and expose a lifecycle
+ * {@link LayerState} that observers can subscribe to. A layer instance may
+ * be attached to only one viewport at a time.
+ *
+ * ```ts
+ * class Particles extends Layer {
+ *   public readonly type = "Particles";
+ *
+ *   constructor(points: PointProps[]) {
+ *     super();
+ *     this.addObject(new PointsRenderable(points));
+ *     this.setState("ready");
+ *   }
+ *
+ *   public update() {}
+ * }
+ *
+ * viewport.addLayer(new Particles(points));
+ * ```
+ *
+ * @group Layers
+ */
+declare abstract class Layer {
+    /** A string identifying the concrete layer type. */
+    abstract readonly type: string;
+    /**
+     * How the layer's output blends with previously drawn content. Also
+     * applies to blending between objects within the layer.
+     */
+    blendMode: BlendMode;
+    /**
+     * Whether the layer writes depth and hides content drawn behind it.
+     *
+     * Occluding layers render a depth pass and always draw before
+     * non-occluding layers regardless of their order in the viewport. When
+     * not set explicitly this value is inferred from `blendMode` at
+     * construction only. Reassigning {@link blendMode} later does not update
+     * it.
+     */
+    occludes: boolean;
+    /** Set to `true` by subclasses whose shaders read scene depth. */
+    protected requiresSceneDepth_: boolean;
+    private readonly coverageGroups_;
+    private state_;
+    private attached_;
+    private readonly callbacks_;
+    private opacity_;
+    /**
+     * Creates a layer with the given presentation state.
+     *
+     * @param props - Initialization properties.
+     */
+    constructor({ opacity, blendMode, occludes, }?: LayerProps);
+    /**
+     * Whether the layer's shaders read scene depth. When `true` the renderer
+     * draws occluding layers to a depth texture the layer's shaders can
+     * sample. A layer cannot both occlude and read scene depth.
+     */
+    get requiresSceneDepth(): boolean;
+    /** The layer's opacity in `[0, 1]`. Values outside are clamped. */
+    get opacity(): number;
+    /** @param value - The new opacity in `[0, 1]`. */
+    set opacity(value: number);
+    /**
+     * Builds or refreshes the layer's renderable objects for the current
+     * view. Called automatically once per frame for every layer in a
+     * viewport.
+     *
+     * @param viewport - The viewport being rendered.
+     */
+    abstract update(viewport?: Viewport): void;
+    /**
+     * Handles a pointer or wheel event from the owning viewport. Called
+     * automatically for each event before the camera controls. The default
+     * implementation does nothing.
+     *
+     * @param _event - The event with clip and world coordinates attached.
+     */
+    onEvent(_event: EventContext): void;
+    /**
+     * Lifecycle hook that is called automatically when a layer is
+     * is attached to a viewport. A layer can only be attached to one viewport
+     * at a time.
+     *
+     * @param context - The shared runtime context.
+     */
+    onAttached(context: IdetikContext): void;
+    /**
+     * Lifecycle hook that is called automatically when a layer is detached
+     * from a viewport.
+     *
+     * @param context - The shared runtime context.
+     */
+    onDetached(context: IdetikContext): void;
+    /** @hidden */
+    protected attach(_context: IdetikContext): void;
+    /** @hidden */
+    protected detach(_context: IdetikContext): void;
+    /**
+     * The layer's renderable objects grouped by coverage group. Objects in
+     * a group draw each pixel at most once, letting chunks at multiple
+     * levels of detail overlap correctly.
+     */
+    get coverageGroups(): ReadonlyMap<number | null, readonly RenderableObject[]>;
+    /** The layer's current lifecycle state. */
+    get state(): LayerState;
+    /**
+     * Registers a callback invoked after every state change.
+     *
+     * @param callback - Receives the new and previous states.
+     */
+    addStateChangeCallback(callback: StateChangeCallback): void;
+    /**
+     * Removes a previously registered state change callback.
+     *
+     * @param callback - The callback to remove.
+     */
+    removeStateChangeCallback(callback: StateChangeCallback): void;
+    /**
+     * Sets the lifecycle state and notifies state change callbacks.
+     *
+     * @param newState - The state to enter.
+     */
+    protected setState(newState: LayerState): void;
+    /**
+     * Registers a renderable object for drawing. Objects in the same
+     * coverage group draw each pixel at most once.
+     *
+     * @param object - The object to add.
+     * @param coverageGroup - The group key.
+     */
+    protected addObject(object: RenderableObject, coverageGroup?: number | null): void;
+    /** Removes all registered renderable objects. */
+    protected clearObjects(): void;
+    /**
+     * Returns uniform name-value pairs applied to every object drawn by
+     * this layer. Override in subclasses that need custom shader uniforms.
+     */
+    getUniforms(): Record<string, unknown>;
+}
+
+declare abstract class Renderer {
+    private readonly canvas_;
+    private width_;
+    private height_;
+    protected renderedObjects_: number;
+    protected abstract resize(width: number, height: number): void;
+    protected abstract renderObject(layer: Layer, object: RenderableObject, camera: Camera): void;
+    protected abstract clear(): void;
+    constructor(canvas: HTMLCanvasElement);
+    beginFrame(): void;
+    abstract render(viewport: Viewport): void;
+    updateSize(): void;
+    private updateRendererSize;
+    protected get canvas(): HTMLCanvasElement;
+    get width(): number;
+    get height(): number;
+    get renderedObjects(): number;
+    abstract get gpuTextureBytes(): number;
+    abstract get gpuTextureCount(): number;
+    abstract uploadTexture(texture: Texture): void;
+    abstract disposeTexture(texture: Texture): void;
+}
+
+/** A snapshot of memory used by chunks, renderer textures, and the JS heap. */
+type MemoryStats = {
+    /** Bytes of chunk data in CPU memory, shared across all Idetik instances. */
+    cpuChunkBytes: number;
+    /** Number of chunks in CPU memory, shared across all Idetik instances. */
+    cpuChunkCount: number;
+    /** Bytes of texture data resident on this instance's GPU renderer. */
+    gpuTextureBytes: number;
+    /** Number of textures resident on this instance's GPU renderer. */
+    gpuTextureCount: number;
+    /** Used JS heap in bytes, when the browser exposes it. Not instance-specific. */
+    jsHeapUsedBytes?: number;
+    /** JS heap size limit in bytes, when the browser exposes it. */
+    jsHeapLimitBytes?: number;
+};
+/**
+ * Statistics available through `idetik.stats`.
+ *
+ * Getters read the current state. Only `chunks` walks chunk states. Reading
+ * memory usage, queue counts, or rendered objects does not scan chunks.
+ *
+ * @group Core
+ */
+declare class Stats {
+    private readonly renderer_;
+    private readonly chunkManager_;
+    private readonly viewports_;
+    /** @hidden */
+    constructor(renderer: Renderer, chunkManager: ChunkManager, viewports: readonly Viewport[]);
+    /**
+     * CPU chunk memory shared across instances, this renderer's GPU texture
+     * memory, and optional JS heap figures. Heap figures are not specific to
+     * this instance. Sizes are in bytes.
+     */
+    get memory(): MemoryStats;
+    /** Counts of queued and in-flight chunk requests for this instance. */
+    get queue(): QueueStats;
+    /**
+     * Chunk demand and GPU residency per source, by timepoint, and loading
+     * progress per viewport. Each read walks every view's chunk states, so poll
+     * it at the rate you need rather than every frame.
+     */
+    get chunks(): ChunkStats;
+    /** Objects reported by the renderer for the last viewport render. */
+    get renderedObjects(): number;
+}
+
 /**
  * An object updated once per frame after all viewports have rendered.
  *
@@ -1565,7 +1635,7 @@ declare class Viewport {
  * ```ts
  * const chunkReadout: Overlay = {
  *   update(idetik) {
- *     div.textContent = `${idetik.memoryStats.cpuChunkCount} chunks`;
+ *     div.textContent = `${idetik.stats.memory.cpuChunkCount} chunks`;
  *   },
  * };
  *
@@ -1598,23 +1668,6 @@ type IdetikProps = {
 type IdetikContext = {
     chunkManager: ChunkManager;
 };
-/**
- * A snapshot of the runtime's memory usage.
- */
-type MemoryStats = {
-    /** Bytes of chunk data held in CPU memory. */
-    cpuChunkBytes: number;
-    /** Number of chunks held in CPU memory. */
-    cpuChunkCount: number;
-    /** Bytes of texture data resident on the GPU. */
-    gpuTextureBytes: number;
-    /** Number of textures resident on the GPU. */
-    gpuTextureCount: number;
-    /** Used JS heap in bytes. */
-    jsHeapUsedBytes?: number;
-    /** JS heap size limit in bytes. */
-    jsHeapLimitBytes?: number;
-};
 /**
  * The entry point of an Idetik application.
  *
@@ -1660,6 +1713,8 @@ declare class Idetik {
     readonly canvas: HTMLCanvasElement;
     /** The registered overlays that update once per frame in order. */
     readonly overlays: Overlay[];
+    /** Memory, queue, chunk, and rendered-object statistics. */
+    readonly stats: Stats;
     private readonly chunkManager_;
     private readonly context_;
     private readonly renderer_;
@@ -1674,18 +1729,6 @@ declare class Idetik {
      * @param params - Initialization properties.
      */
     constructor(params: IdetikProps);
-    /** Counts of queued and in-flight chunk requests. */
-    get chunkQueueStats(): QueueStats;
-    /**
-     * Chunk demand and GPU residency per source, by timepoint, and loading
-     * progress per viewport. Each read walks every view's chunk states and returns a
-     * new snapshot, so poll it at the rate you need rather than every frame.
-     */
-    get chunkStats(): ChunkStats;
-    /** A snapshot of current CPU/GPU/JS heap memory usage. */
-    get memoryStats(): MemoryStats;
-    /** The number of objects drawn in the last rendered frame. */
-    get renderedObjects(): number;
     /** The width of the rendering surface in pixels. */
     get width(): number;
     /** The height of the rendering surface in pixels. */
@@ -3532,5 +3575,5 @@ declare class OrbitControls implements CameraControls {
     private cutoffLowVelocity;
 }
 
-export { AxesLayer, Box2, Box3, Camera, Color, Frustum, Idetik, ImageLayer, ImageRenderable, LabelImageRenderable, LabelLayer, Layer, OmeZarrImageSource, OrbitControls, OrthographicCamera, PanZoomControls, PerspectiveCamera, PointsRenderable, ProjectedLineRenderable, RenderableObject, TrsTransform, Viewport, VolumeLayer, VolumeRenderable, createExplorationPolicy, createImageSourcePolicy, createNoPrefetchPolicy, createPlaybackPolicy, loadOmeZarrPlate, loadOmeZarrWell, loadOmeroChannels, loadOmeroDefaults };
+export { AxesLayer, Box2, Box3, Camera, Color, Frustum, Idetik, ImageLayer, ImageRenderable, LabelImageRenderable, LabelLayer, Layer, OmeZarrImageSource, OrbitControls, OrthographicCamera, PanZoomControls, PerspectiveCamera, PointsRenderable, ProjectedLineRenderable, RenderableObject, Stats, TrsTransform, Viewport, VolumeLayer, VolumeRenderable, createExplorationPolicy, createImageSourcePolicy, createNoPrefetchPolicy, createPlaybackPolicy, loadOmeZarrPlate, loadOmeZarrWell, loadOmeroChannels, loadOmeroDefaults };
 export type { AxesLayerProps, BlendMode, CameraControls, CameraType, ChannelProps, ChunkStats, ColorLike, FileSystemOmeZarrImageSourceProps, HttpOmeZarrImageSourceProps, IdetikProps, ImageLayerProps, ImageRenderableProps, ImageSourcePolicy, ImageSourcePolicyProps, LabelColorMap, LabelColorMapProps, LabelImageRenderableProps, LabelLayerProps, LayerProps, LayerState, MemoryStats, OrbitControlsProps, OrthographicCameraFrame, OrthographicCameraProps, Overlay, PanZoomControlsProps, PerspectiveCameraProps, PointPickingResult, PointProps, PriorityCategory, ProjectedLineRenderableProps, QueueStats, SliceCoordinates, SliceOrientation, SourceChunkStats, SourceDimension, SourceDimensionLod, SourceDimensionMap, StateChangeCallback, ViewportChunkStats, ViewportProps, VolumeLayerProps, VolumeRenderableProps };