@idetik/core 0.45.5 → 0.46.0

package/README.md

@@ -35,6 +35,7 @@ This example displays a single slice from [Zebrahub](https://zebrahub.sf.czbiohu
 import {
   Idetik,
   ImageLayer,
+  Viewport,
   OmeZarrImageSource,
   OrthographicCamera,
   PanZoomControls,
@@ -56,13 +57,15 @@ const camera = new OrthographicCamera({
   top: 0, bottom: y.lods[0].size * y.lods[0].scale
 });
 
+const canvas = document.querySelector<HTMLCanvasElement>('canvas')!;
 const idetik = new Idetik({
-  canvas: document.querySelector('canvas')!,
-  viewports: [{
+  canvas,
+  viewports: [new Viewport({
+    domElement: canvas,
     camera,
     layers: [layer],
     cameraControls: new PanZoomControls(camera)
-  }],
+  })],
 });
 
 idetik.start();

package/dist/index.d.ts

@@ -1065,13 +1065,15 @@ type OrthographicCameraProps = {
  *  bottom: 1024
  * });
  *
+ * const canvas = document.querySelector<HTMLCanvasElement>('canvas')!;
  * const idetik = new Idetik({
- *   canvas: document.querySelector('canvas')!,
- *   viewports: [{
+ *   canvas,
+ *   viewports: [new Viewport({
+ *     domElement: canvas,
  *     camera,
  *     layers: [imageLayer],
  *     cameraControls: new PanZoomControls(camera),
- *   }],
+ *   })],
  * });
  * ```
  * @group Cameras
@@ -1219,11 +1221,12 @@ type PanZoomControlsProps = {
  *
  * const idetik = new Idetik({
  *   canvas,
- *   viewports: [{
+ *   viewports: [new Viewport({
+ *     domElement: canvas,
  *     camera,
  *     layers: [imageLayer],
  *     cameraControls: new PanZoomControls(camera),
- *   }],
+ *   })],
  * });
  * ```
  *
@@ -1268,8 +1271,8 @@ declare class PanZoomControls implements CameraControls {
 type ViewportProps = {
     /** Unique id. Defaults to the element id or a generated id. */
     id?: string;
-    /** Host element. Defaults to the Idetik canvas. */
-    element?: HTMLElement;
+    /** Host element. */
+    domElement: HTMLElement;
     /** The camera the viewport renders with. */
     camera: Camera;
     /** Layers to render in order. */
@@ -1277,17 +1280,11 @@ type ViewportProps = {
     /** Input controls driving the camera. */
     cameraControls?: CameraControls;
 };
-interface ResolvedViewportProps extends ViewportProps {
-    id: string;
-    element: HTMLElement;
-    context: IdetikContext;
-}
 /**
  * A region of the canvas that renders a stack of layers through a camera.
  *
  * Every viewport draws into the shared canvas through the area of its host
- * element. The element defaults to the canvas itself and must be unique
- * across viewports.
+ * element. The element must be unique across viewports.
  *
  * Viewports also route input. Pointer and wheel events on the host element
  * are enriched with clip and world coordinates and a picking ray, sent to
@@ -1295,12 +1292,13 @@ interface ResolvedViewportProps extends ViewportProps {
  * propagation.
  *
  * ```ts
- * const idetik = new Idetik({
- *   canvas,
- *   viewports: [{ id: 'main', camera, layers: [imageLayer] }],
+ * const viewport = new Viewport({
+ *   domElement: canvas,
+ *   camera,
+ *   layers: [imageLayer],
  * });
+ * const idetik = new Idetik({ canvas, viewports: [viewport] });
  *
- * const viewport = idetik.getViewport('main')!;
  * viewport.addLayer(labelLayer);
  * ```
  *
@@ -1310,24 +1308,23 @@ declare class Viewport {
     /** The viewport's unique identifier. */
     readonly id: string;
     /** The host element defining the viewport's area. */
-    readonly element: HTMLElement;
+    readonly domElement: HTMLElement;
     /** The camera the viewport renders with. */
     readonly camera: Camera;
     /** The pointer and wheel event dispatcher for the host element. */
     readonly events: EventDispatcher;
     /** Input controls driving the camera. */
     cameraControls?: CameraControls;
-    private readonly context_;
     private layers_;
-    /** @hidden */
-    constructor(props: ResolvedViewportProps);
+    constructor(props: ViewportProps);
     /**
      * The layers rendered by this viewport in order. Layers with `occludes`
      * set draw before non-occluding layers regardless of stack order.
      */
     get layers(): readonly Layer[];
     /**
-     * Adds a layer to the top of the stack.
+     * Adds a layer to the top of the stack. Throws if the viewport already
+     * contains the layer.
      *
      * @param layer - The layer to add.
      */
@@ -1346,14 +1343,17 @@ declare class Viewport {
      */
     updateSize(): void;
     /**
-     * Computes the viewport's box relative to the given canvas in device pixels.
+     * Computes the viewport's box relative to the given element in device
+     * pixels, with `y` flipped to match WebGL's bottom-left origin.
      *
-     * @param canvas - The canvas to compute the box against.
-     * @returns The viewport's box in the canvas's coordinate space.
+     * @param element - The element to compute the box against, typically the
+     *   canvas.
+     * @returns The viewport's box in the element's coordinate space.
      */
-    getBoxRelativeTo(canvas: HTMLCanvasElement): Box2;
+    getBoxRelativeTo(element: HTMLElement): Box2;
     /**
-     * The viewport's rectangle in the drawing buffer in device pixels.
+     * The viewport's size in device pixels. Measured relative to its own host
+     * element, so `x` and `y` are always `0`.
      */
     getBufferRect(): {
         x: number;
@@ -1494,6 +1494,8 @@ declare abstract class Layer {
      * @param _event - The event with clip and world coordinates attached.
      */
     onEvent(_event: EventContext): void;
+    /** Whether the layer is attached to a viewport. */
+    get attached(): boolean;
     /**
      * Lifecycle hook that is called automatically when a layer is
      * is attached to a viewport. A layer can only be attached to one viewport
@@ -1652,8 +1654,8 @@ type Overlay = {
 type IdetikProps = {
     /** The canvas element to render into. */
     canvas: HTMLCanvasElement;
-    /** Viewport definitions to create at startup. */
-    viewports?: ViewportProps[];
+    /** Viewports to render at startup. */
+    viewports?: Viewport[];
     /** Overlays to run each frame. */
     overlays?: Overlay[];
     /** Shows an FPS meter. Defaults to `false`. */
@@ -1692,13 +1694,15 @@ type IdetikContext = {
  *   bottom: 1024,
  * });
  *
+ * const canvas = document.querySelector<HTMLCanvasElement>('canvas')!;
  * const idetik = new Idetik({
- *   canvas: document.querySelector('canvas')!,
- *   viewports: [{
+ *   canvas,
+ *   viewports: [new Viewport({
+ *     domElement: canvas,
  *     camera,
  *     layers: [layer],
  *     cameraControls: new PanZoomControls(camera),
- *   }],
+ *   })],
  * });
  *
  * idetik.start();
@@ -1719,6 +1723,7 @@ declare class Idetik {
     private readonly context_;
     private readonly renderer_;
     private readonly viewports_;
+    private readonly attachments_;
     private readonly stats_?;
     private readonly sizeObserver_;
     private lastAnimationId_?;
@@ -1747,11 +1752,10 @@ declare class Idetik {
     /**
      * Adds a viewport at runtime.
      *
-     * @param props - The viewport definition. The `element` defaults to the
-     *   canvas and must be unique across viewports.
-     * @returns The created viewport.
+     * @param viewport - The viewport to add.
+     * @returns The added viewport.
      */
-    addViewport(props: ViewportProps): Viewport;
+    addViewport(viewport: Viewport): Viewport;
     /**
      * Removes a previously added viewport.
      *
@@ -1784,6 +1788,8 @@ declare class Idetik {
      * @returns The instance, for chaining.
      */
     start(): this;
+    private detachRemovedLayers;
+    private renderViewport;
     private animate;
     /**
      * Stops the render loop and disconnects input handlers.
@@ -3435,9 +3441,15 @@ type PerspectiveCameraProps = {
  *   target: [0, 0, 0],
  * });
  *
+ * const canvas = document.querySelector<HTMLCanvasElement>('canvas')!;
  * const idetik = new Idetik({
- *   canvas: document.querySelector('canvas')!,
- *   viewports: [{ camera, layers: [volumeLayer], cameraControls: controls }],
+ *   canvas,
+ *   viewports: [new Viewport({
+ *     domElement: canvas,
+ *     camera,
+ *     layers: [volumeLayer],
+ *     cameraControls: controls
+ *   })],
  * });
  * ```
  *
@@ -3511,14 +3523,15 @@ type OrbitControlsProps = {
  *
  * const idetik = new Idetik({
  *   canvas,
- *   viewports: [{
+ *   viewports: [new Viewport({
+ *     domElement: canvas,
  *     camera,
  *     layers: [volumeLayer],
  *     cameraControls: new OrbitControls(camera, {
  *       radius: 100,
  *       target: [40, 40, 10],
  *     }),
- *   }],
+ *   })],
  * });
  * ```
  *