@idetik/core 0.46.2 → 0.47.0

package/dist/index.d.ts

@@ -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_;
@@ -3626,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 };