@idetik/core 0.46.1 → 0.47.0

package/dist/index.d.ts

@@ -1316,6 +1316,11 @@ declare class Viewport {
     /** Input controls driving the camera. */
     cameraControls?: CameraControls;
     private layers_;
+    private layersChanged_;
+    private lastRenderBox_?;
+    private lastVisibility_?;
+    private readonly lastCameraTransform_;
+    private readonly lastProjection_;
     constructor(props: ViewportProps);
     /**
      * The layers rendered by this viewport in order. Layers with `occludes`
@@ -1337,6 +1342,8 @@ declare class Viewport {
     removeLayer(layer: Layer): void;
     /** Removes all layers from the viewport. */
     removeAllLayers(): void;
+    /** @hidden */
+    renderStateChanged(canvas: HTMLCanvasElement): boolean;
     /**
      * Syncs the camera's aspect ratio to the host element's size. Called
      * automatically when the host element resizes.
@@ -1429,7 +1436,9 @@ type LayerProps = {
  *     this.setState("ready");
  *   }
  *
- *   public update() {}
+ *   public update(): boolean {
+ *     return true;
+ *   }
  * }
  *
  * viewport.addLayer(new Particles(points));
@@ -1440,28 +1449,16 @@ type LayerProps = {
 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 renderStateChanged_;
     private opacity_;
+    private blendMode_;
+    private occludes_;
     /**
      * Creates a layer with the given presentation state.
      *
@@ -1474,6 +1471,23 @@ declare abstract class Layer {
      * sample. A layer cannot both occlude and read scene depth.
      */
     get requiresSceneDepth(): boolean;
+    /**
+     * How the layer's output blends with previously drawn content.
+     */
+    get blendMode(): BlendMode;
+    /** @param value - The blending mode to use. */
+    set blendMode(value: 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.
+     */
+    get occludes(): boolean;
+    /** @param value - Whether the layer writes depth. */
+    set occludes(value: boolean);
     /** The layer's opacity in `[0, 1]`. Values outside are clamped. */
     get opacity(): number;
     /** @param value - The new opacity in `[0, 1]`. */
@@ -1483,9 +1497,21 @@ declare abstract class Layer {
      * view. Called automatically once per frame for every layer in a
      * viewport.
      *
+     * Return `true` if this update changed the rendered output, otherwise
+     * return `false`. Changes marked by {@link invalidate} are tracked
+     * separately, so returning `false` does not discard them.
+     *
      * @param viewport - The viewport being rendered.
      */
-    abstract update(viewport?: Viewport): void;
+    abstract update(viewport?: Viewport): boolean;
+    /**
+     * Marks the layer's rendered output as changed. Call from setters or
+     * asynchronous callbacks when a change happens outside {@link update}.
+     * The runtime checks this flag on its next update.
+     */
+    protected invalidate(): void;
+    /** @hidden */
+    renderStateChanged(): boolean;
     /**
      * Handles a pointer or wheel event from the owning viewport. Called
      * automatically for each event before the camera controls. The default
@@ -1558,6 +1584,12 @@ declare abstract class Layer {
     getUniforms(): Record<string, unknown>;
 }
 
+type GpuTiming = {
+    supported: boolean;
+    samples: number;
+    totalMs: number;
+    lastSampleAt?: number;
+};
 declare abstract class Renderer {
     private readonly canvas_;
     private width_;
@@ -1567,7 +1599,10 @@ declare abstract class Renderer {
     protected abstract renderObject(layer: Layer, object: RenderableObject, camera: Camera): void;
     protected abstract clear(): void;
     constructor(canvas: HTMLCanvasElement);
-    beginFrame(): void;
+    abstract beginFrame(): void;
+    abstract endFrame(): void;
+    abstract resetGpuTiming(): void;
+    abstract get gpuTiming(): GpuTiming;
     abstract render(viewport: Viewport): void;
     updateSize(): void;
     private updateRendererSize;
@@ -1596,11 +1631,35 @@ type MemoryStats = {
     /** JS heap size limit in bytes, when the browser exposes it. */
     jsHeapLimitBytes?: number;
 };
+/**
+ * A snapshot of drawing frequency and GPU draw cost.
+ *
+ * Values are averaged over sampling windows of at least one second. A frame
+ * is one canvas draw pass across all viewports including draws during resize.
+ * GPU timings are collected asynchronously and lag draw submission.
+ */
+type RuntimeStats = {
+    /** Whether GPU timer queries are supported by the current renderer context. */
+    gpuTimingSupported: boolean;
+    /**
+     * Canvas draw passes per second in the latest sampling window.
+     * This value diverges from frames per second when on-demand rendering
+     * is enabled.
+     */
+    renderedFramesPerSecond: number;
+    /**
+     * Mean elapsed GPU timeline time per sampled canvas render pass, in ms.
+     * The interval spans drawing across all viewports, excluding layer updates.
+     * Undefined when no recent valid sample exists.
+     */
+    gpuMsPerFrame?: 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.
+ * runtime rates, memory usage, queue counts, or rendered objects does not
+ * scan chunks.
  *
  * @group Core
  */
@@ -1608,8 +1667,19 @@ declare class Stats {
     private readonly renderer_;
     private readonly chunkManager_;
     private readonly viewports_;
+    private readonly runtime_;
+    private sampleStartedAt_;
+    private draws_;
+    private gpuSamples_;
+    private gpuMsAtWindowStart_;
     /** @hidden */
     constructor(renderer: Renderer, chunkManager: ChunkManager, viewports: readonly Viewport[]);
+    /**
+     * Drawing frequency and GPU cost, recalculated on read when at least one
+     * second has passed since the last calculation or reset. Values cover that
+     * entire interval, so less frequent reads produce longer-term averages.
+     */
+    get runtime(): RuntimeStats;
     /**
      * CPU chunk memory shared across instances, this renderer's GPU texture
      * memory, and optional JS heap figures. Heap figures are not specific to
@@ -1626,10 +1696,17 @@ declare class Stats {
     get chunks(): ChunkStats;
     /** Objects reported by the renderer for the last viewport render. */
     get renderedObjects(): number;
+    /** @hidden */
+    recordDraw(): void;
+    /** @hidden */
+    private sample;
+    /** @hidden */
+    resetRates(): void;
+    private resetSample;
 }
 
 /**
- * An object updated once per frame after all viewports have rendered.
+ * An object updated once per animation frame after any drawing.
  *
  * Overlays drive HUD elements that live outside the canvas such as scale
  * bars, time indicators, or memory readouts.
@@ -1645,7 +1722,7 @@ declare class Stats {
  * ```
  */
 type Overlay = {
-    /** Called once per rendered frame. */
+    /** Called every animation frame, including when drawing is skipped. */
     update: (idetik: Idetik) => void;
 };
 /**
@@ -1717,7 +1794,7 @@ 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. */
+    /** Runtime, memory, queue, chunk, and rendered-object statistics. */
     readonly stats: Stats;
     private readonly chunkManager_;
     private readonly context_;
@@ -1728,6 +1805,8 @@ declare class Idetik {
     private readonly sizeObserver_;
     private lastAnimationId_?;
     private lastTimestamp_;
+    private renderRequested_;
+    private renderInvalidated_;
     /**
      * Creates an Idetik runtime for the given canvas.
      *
@@ -1782,6 +1861,11 @@ declare class Idetik {
      * @param memoryLimitMB - The new budget in megabytes.
      */
     setMemoryLimitMB(memoryLimitMB: number): void;
+    /**
+     * Explicitly requests a draw on the next animation frame while running,
+     * even if no internal state has changed.
+     */
+    requestRender(): void;
     /**
      * Starts the render loop and connects input handlers.
      *
@@ -1789,8 +1873,10 @@ declare class Idetik {
      */
     start(): this;
     private detachRemovedLayers;
-    private renderViewport;
     private animate;
+    private invalidate;
+    private updateViewport;
+    private draw;
     /**
      * Stops the render loop and disconnects input handlers.
      */
@@ -2540,7 +2626,7 @@ declare class AxesLayer extends Layer {
      */
     constructor(props: AxesLayerProps);
     /** Performs no per-frame work. The axes are built at construction. */
-    update(): void;
+    update(): boolean;
 }
 
 /**
@@ -2657,7 +2743,7 @@ declare class ImageLayer extends Layer implements ChannelsEnabled {
      *
      * @param viewport - The viewport being rendered.
      */
-    update(viewport?: Viewport): void;
+    update(viewport?: Viewport): boolean;
     /** The slice plane the layer displays. */
     get orientation(): SliceOrientation;
     /**
@@ -2868,7 +2954,7 @@ declare class VolumeLayer extends Layer implements ChannelsEnabled {
      *
      * @param viewport - The viewport being rendered.
      */
-    update(viewport?: Viewport): void;
+    update(viewport?: Viewport): boolean;
     private rebuildObjects;
     /** @hidden */
     get chunkStoreView(): ChunkStoreView | undefined;
@@ -3066,7 +3152,7 @@ declare class LabelLayer extends Layer {
      *
      * @param viewport - The viewport being rendered.
      */
-    update(viewport?: Viewport): void;
+    update(viewport?: Viewport): boolean;
     /** The slice plane the layer displays. */
     get orientation(): SliceOrientation;
     /**
@@ -3251,7 +3337,9 @@ type PointProps = {
  *     this.setState("ready");
  *   }
  *
- *   public update() {}
+ *   public update(): boolean {
+ *     return true;
+ *   }
  * }
  * ```
  *
@@ -3589,4 +3677,4 @@ declare class OrbitControls implements CameraControls {
 }
 
 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 };
+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, RuntimeStats, SliceCoordinates, SliceOrientation, SourceChunkStats, SourceDimension, SourceDimensionLod, SourceDimensionMap, StateChangeCallback, ViewportChunkStats, ViewportProps, VolumeLayerProps, VolumeRenderableProps };