@dreamcomposer/engine-types 2.1.1 → 3.0.0

package/Screenshot.d.ts

@@ -0,0 +1,44 @@
+import { CameraPosition } from "./Camera";
+
+/**
+ * Which camera a screenshot is taken through.
+ *
+ * - `"current"` shoots what the viewer shows, from the camera the user moved.
+ * - `"initial"` shoots the view the project opens with: the engine's default
+ *   viewing angle, the object's center as the target, and the distance that
+ *   fits the object into the image.
+ * - An explicit position shoots that pose. Anything left out of it is framed
+ *   the way `"initial"` would frame it, so an empty object is `"initial"`.
+ *
+ * Everything but `"current"` is rendered through a second camera, so the
+ * camera on screen keeps its position and the viewer shows the same frame
+ * before and after.
+ */
+export type ScreenshotCamera = "current" | "initial" | Partial<CameraPosition>;
+
+/**
+ * What every screenshot request shares, whatever is done with the image
+ * afterwards.
+ */
+export interface ScreenshotPayloadBase {
+  /**
+   * The width of the screenshot. Defaults to the width of the canvas.
+   */
+  width?: number;
+  /**
+   * The height of the screenshot. Defaults to the height of the canvas.
+   */
+  height?: number;
+  /**
+   * Which camera to shoot through. Defaults to `"current"`.
+   */
+  camera?: ScreenshotCamera;
+  /**
+   * A PNG image that is overlaid on top of the screenshot.
+   *
+   * It is drawn at the screenshot's own size, so it belongs to the framing the
+   * shot is taken in - pair it with the default camera rather than with a
+   * position the overlay was not captured for.
+   */
+  overlayPNG?: ImageBitmap;
+}

package/from-engine/EngineAliveMessage.d.ts

@@ -0,0 +1,11 @@
+import { FromEngineMessage } from "../post-messages";
+
+/**
+ * Sent as the very first thing when the engine page starts, before any of
+ * its scripts are loaded. It only tells the embedder that the engine is
+ * reachable; it is still not allowed to send commands until it receives the
+ * `engine-ready` message.
+ */
+export interface EngineAliveMessage extends FromEngineMessage<"engine-alive"> {
+  payload: true;
+}

package/from-engine/EngineErrorMessage.d.ts

@@ -0,0 +1,16 @@
+import { FromEngineMessage } from "../post-messages";
+
+/**
+ * Sent when the engine fails in a way it cannot recover from on its own.
+ *
+ * `startup` errors happen before `engine-ready` was sent, i.e. the engine will
+ * never become ready. `runtime` errors happen afterwards and leave the engine
+ * unusable, e.g. a lost WebGL context that is not restored.
+ */
+export interface EngineErrorMessage extends FromEngineMessage<"engine-error"> {
+  payload: {
+    phase: "startup" | "runtime";
+    /** A technical description for logs, not meant to be shown to users. */
+    message: string;
+  };
+}

package/from-engine/ScreenshotImageMessage.d.ts

@@ -0,0 +1,27 @@
+import { FromEngineMessage } from "../post-messages";
+
+/**
+ * The image of a `take-screenshot` message.
+ *
+ * It is sent before the ack of that message.
+ */
+export interface ScreenshotImageMessage extends FromEngineMessage<"screenshot-image"> {
+  payload: {
+    /**
+     * The `requestId` of the `take-screenshot` message this image belongs to.
+     */
+    requestId: string;
+    /**
+     * The height of the image.
+     */
+    height: number;
+    /**
+     * The width of the image.
+     */
+    width: number;
+    /**
+     * The base64 encoded image in the PNG format, as a data URL.
+     */
+    data: string;
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamcomposer/engine-types",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "description": "The type definitions for messages from and to the engine",
   "license": "UNLICENSED",
   "private": false,

package/post-messages.d.ts

@@ -1,5 +1,6 @@
 import { AckMessage } from "./from-engine/AckMessage";
-import { CanvasImageUrlMessage } from "./from-engine/CanvasImageUrlMessage";
+import { EngineAliveMessage } from "./from-engine/EngineAliveMessage";
+import { EngineErrorMessage } from "./from-engine/EngineErrorMessage";
 import { EngineReadyMessage } from "./from-engine/EngineReadyMessage";
 import { KeyDownMessage } from "./from-engine/KeyDownMessage";
 import { SetLoadingProgressMessage } from "./from-engine/SetLoadingProgressMessage";
@@ -56,6 +57,8 @@ import { SetAnnotationTagsMessage } from "./to-engine/SetAnnotationTagsMessage";
 import { SetCustomRequestHeaders } from "./to-engine/SetCustomRequestHeaders";
 import { SetObjectForScaleMessage } from "./to-engine/SetObjectForScaleMessage";
 import { ExportSceneMessage } from "./to-engine/ExportSceneMessage";
+import { ScreenshotImageMessage } from "./from-engine/ScreenshotImageMessage";
+import { TakeScreenshotMessage } from "./to-engine/TakeScreenshotMessage";
 
 /**
  * A message sent from the engine to the embedder.
@@ -80,8 +83,9 @@ export interface ToEngineMessage<Channel> {
 
 export type FromEnginePostMessage =
   | AckMessage
-  | CanvasImageUrlMessage
   | DisplayLoadingUiMessage
+  | EngineAliveMessage
+  | EngineErrorMessage
   | EngineReadyMessage
   | HideGuiMessage
   | HideLoadingUiMessage
@@ -93,10 +97,12 @@ export type FromEnginePostMessage =
   | CameraPositionChangeMessage
   | EnvironmentRotationChangedMessage
   | GeometryTransformChangeMessage
-  | AnnotationTagPositionChangedMessage;
+  | AnnotationTagPositionChangedMessage
+  | ScreenshotImageMessage;
 
 export type ToEnginePostMessage =
   | DownloadScreenshotMessage
+  | TakeScreenshotMessage
   | HighlightLayerMessage
   | MouseEventMessage
   | ResetCameraPositionMessage

package/to-engine/DownloadScreenshotMessage.d.ts

@@ -1,20 +1,18 @@
+import { ScreenshotPayloadBase } from "../Screenshot";
 import { ToEngineMessage } from "../post-messages";
 
-export interface ScreenshotPayload {
+export interface ScreenshotPayload extends ScreenshotPayloadBase {
+  /**
+   * The name of the file to download the screenshot as.
+   */
   fileName: string;
-  overlayPNG?: ImageBitmap;
-  width?: number;
-  height?: number;
 }
 
 /**
- * Downloads a high-resolution screenshot of the current scene.
+ * Downloads a screenshot of the scene.
  *
  * The download starts automatically once the screenshot has been rendered.
  */
 export interface DownloadScreenshotMessage extends ToEngineMessage<"download-screenshot"> {
-  /**
-   * An empty object.
-   */
   payload: ScreenshotPayload;
 }

package/to-engine/TakeScreenshotMessage.d.ts

@@ -0,0 +1,18 @@
+import { ScreenshotPayloadBase } from "../Screenshot";
+import { ToEngineMessage } from "../post-messages";
+
+export interface TakeScreenshotPayload extends ScreenshotPayloadBase {
+  /**
+   * An id that the engine echoes back in the `screenshot-image` message, so
+   * that an embedder with several screenshots in flight can tell them apart.
+   */
+  requestId: string;
+}
+
+/**
+ * Renders a screenshot of the scene and sends the image back
+ * in a `screenshot-image` message, which arrives before the ack of this one.
+ */
+export interface TakeScreenshotMessage extends ToEngineMessage<"take-screenshot"> {
+  payload: TakeScreenshotPayload;
+}

package/from-engine/CanvasImageUrlMessage.d.ts

@@ -1,26 +0,0 @@
-import { FromEngineMessage, ToEngineMessage } from "../post-messages";
-
-/**
- * A screenshot of the canvas that is sent to the embedder when the heatmap
- * collection is stopped.
- *
- * The screenshot is used by the embedder to draw the heatmap over it.
- */
-// TODO: This should have another name to make it clear it's related to the
-//       heat map collection.
-export interface CanvasImageUrlMessage extends FromEngineMessage<"canvas-image-url"> {
-  payload: {
-    /**
-     * The height of the image.
-     */
-    height: number;
-    /**
-     * The width of the image.
-     */
-    width: number;
-    /**
-     * The base64 encoded image in the PNG format.
-     */
-    data: string;
-  };
-}