@idetik/core 0.46.2 → 0.48.0

package/dist/index.d.ts

@@ -1437,7 +1437,7 @@ type LayerProps = {
  *   }
  *
  *   public update(): boolean {
- *     return true;
+ *     return false; // static content, no changes to redraw
  *   }
  * }
  *
@@ -1584,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_;
@@ -1593,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;
@@ -1622,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
  */
@@ -1634,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
@@ -1652,6 +1696,13 @@ 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;
 }
 
 /**
@@ -1743,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_;
@@ -2664,6 +2715,7 @@ declare class ImageLayer extends Layer implements ChannelsEnabled {
     private readonly onPickValue_?;
     private readonly visibleChunks_;
     private orderedChunks_;
+    private lastSliceCoord_?;
     private readonly pool_;
     private readonly initialChannelProps_?;
     private readonly channelChangeCallbacks_;
@@ -2838,6 +2890,7 @@ declare class VolumeLayer extends Layer implements ChannelsEnabled {
     private readonly source_;
     private readonly sliceCoords_;
     private readonly currentVolumes_;
+    private renderedChunks_;
     private readonly volumeToPoolKey_;
     private readonly pool_;
     private readonly initialChannelProps_?;
@@ -2845,9 +2898,8 @@ declare class VolumeLayer extends Layer implements ChannelsEnabled {
     private policy_;
     private chunkStoreView_?;
     private channelProps_?;
-    private lastLoadedTime_;
-    private lastNumRenderedChannelChunks_;
     private interactiveStepSizeScale_;
+    private previousAppearanceState_;
     private debugShowWireframes_;
     /** Whether chunk bounding wireframes are drawn for debugging. */
     get debugShowWireframes(): boolean;
@@ -2904,6 +2956,7 @@ declare class VolumeLayer extends Layer implements ChannelsEnabled {
      * @param viewport - The viewport being rendered.
      */
     update(viewport?: Viewport): boolean;
+    private updateAppearanceState;
     private rebuildObjects;
     /** @hidden */
     get chunkStoreView(): ChunkStoreView | undefined;
@@ -3075,6 +3128,8 @@ declare class LabelLayer extends Layer {
     private readonly onPickValue_?;
     private readonly outlineSelected_;
     private readonly visibleChunks_;
+    private orderedChunks_;
+    private lastSliceCoord_?;
     private readonly pool_;
     private colorMap_;
     private selectedValue_;
@@ -3626,4 +3681,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 };