Fix copyImageToCanvas bug and add ReadImageToCanvasOptions

common/api/core-frontend.api.md

@@ -8230,7 +8230,7 @@ export class OffScreenTarget extends Target {
     // (undocumented)
     onResized(): void;
     // (undocumented)
-    readImageToCanvas(): HTMLCanvasElement;
+    readImageToCanvas(options?: ReadImageToCanvasOptions): HTMLCanvasElement;
     // (undocumented)
     setViewRect(rect: ViewRect, temporary: boolean): void;
     // (undocumented)
@@ -8314,7 +8314,7 @@ export class OnScreenTarget extends Target {
     // (undocumented)
     pickOverlayDecoration(pt: XAndY): CanvasDecoration | undefined;
     // (undocumented)
-    readImageToCanvas(): HTMLCanvasElement;
+    readImageToCanvas(options?: ReadImageToCanvasOptions): HTMLCanvasElement;
     // (undocumented)
     setRenderToScreen(toScreen: boolean): HTMLCanvasElement | undefined;
     // (undocumented)
@@ -9066,6 +9066,11 @@ export interface ReadImageBufferArgs {
     upsideDown?: boolean;
 }
 
+// @public
+export interface ReadImageToCanvasOptions {
+    includeCanvasDecorations?: boolean;
+}
+
 // @internal (undocumented)
 export function readImdlContent(args: ImdlReaderCreateArgs & {
     parseDocument?: (parseOpts: ImdlParserOptions) => Promise<ImdlModel.Document | ImdlParseError>;
@@ -10347,7 +10352,7 @@ export abstract class RenderTarget implements IDisposable, RenderMemory.Consumer
     // @internal (undocumented)
     readImageBuffer(_args?: ReadImageBufferArgs): ImageBuffer | undefined;
     // @internal (undocumented)
-    readImageToCanvas(): HTMLCanvasElement;
+    readImageToCanvas(_options?: ReadImageToCanvasOptions): HTMLCanvasElement;
     // @internal (undocumented)
     abstract readPixels(rect: ViewRect, selector: Pixel.Selector, receiver: Pixel.Receiver, excludeNonLocatable: boolean, excludedElements?: Iterable<Id64String>): void;
     // @internal (undocumented)
@@ -11608,7 +11613,7 @@ export abstract class Target extends RenderTarget implements RenderTargetDebugCo
     // (undocumented)
     computeEdgeWeight(pass: RenderPass, baseWeight: number): number;
     // (undocumented)
-    copyImageToCanvas(): HTMLCanvasElement;
+    copyImageToCanvas(options?: ReadImageToCanvasOptions): HTMLCanvasElement;
     // (undocumented)
     createPlanarClassifier(properties?: ActiveSpatialClassifier): PlanarClassifier;
     // (undocumented)
@@ -14744,7 +14749,7 @@ export abstract class Viewport implements IDisposable, TileUser {
     // @deprecated
     readImage(rect?: ViewRect, targetSize?: Point2d, flipVertically?: boolean): ImageBuffer | undefined;
     readImageBuffer(args?: ReadImageBufferArgs): ImageBuffer | undefined;
-    readImageToCanvas(): HTMLCanvasElement;
+    readImageToCanvas(options?: ReadImageToCanvasOptions): HTMLCanvasElement;
     readPixels(rect: ViewRect, selector: Pixel.Selector, receiver: Pixel.Receiver, excludeNonLocatable?: boolean): void;
     readPixels(args: ReadPixelsArgs): void;
     // @internal

common/api/summary/core-frontend.exports.csv

@@ -582,6 +582,7 @@ public;function;readGltfGraphics
 public;interface;ReadGltfGraphicsArgs
 beta;function;readGltfTemplate
 public;interface;ReadImageBufferArgs
+public;interface;ReadImageToCanvasOptions
 internal;function;readImdlContent
 public;interface;ReadMeshArgs
 internal;class;ReadonlyTileUserSet

common/changes/@itwin/core-frontend/andremig-decoration_2025-01-10-16-41.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-frontend",
+      "comment": "Add ReadImageToCanvasOptions",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-frontend"
+}

core/frontend/src/Viewport.ts

@@ -262,6 +262,16 @@ export interface ReadPixelsArgs {
   excludedElements?: Iterable<Id64String>;
 }
 
+/** Arguments supplied to [[Viewport.readImageToCanvas]].
+ * @public
+ */
+export interface ReadImageToCanvasOptions {
+  /** If defined, canvas decorations will be included in the saved image.
+   * @note This only affects single viewport applications. For multi-viewport applications, the canvas decorations are always included.
+   */
+  includeCanvasDecorations?: boolean;
+}
+
 /** A Viewport renders the contents of one or more [GeometricModel]($backend)s onto an `HTMLCanvasElement`.
  *
  * It holds a [[ViewState]] object that defines its viewing parameters; the ViewState in turn defines the [[DisplayStyleState]],
@@ -2703,8 +2713,8 @@ export abstract class Viewport implements IDisposable, TileUser {
   /** Reads the current image from this viewport into an HTMLCanvasElement with a Canvas2dRenderingContext such that additional 2d graphics can be drawn onto it.
    * @see [[readImageBuffer]] to obtain the image as an array of RGBA pixels.
    */
-  public readImageToCanvas(): HTMLCanvasElement {
-    return this.target.readImageToCanvas();
+  public readImageToCanvas(options?: ReadImageToCanvasOptions): HTMLCanvasElement {
+    return this.target.readImageToCanvas(options);
   }
 
   /** Used internally by `waitForSceneCompletion`.

core/frontend/src/render/RenderTarget.ts

@@ -12,7 +12,7 @@ import { Point2d, XAndY } from "@itwin/core-geometry";
 import { IModelConnection } from "../IModelConnection";
 import { HiliteSet } from "../SelectionSet";
 import { SceneContext } from "../ViewContext";
-import { ReadImageBufferArgs, Viewport } from "../Viewport";
+import { ReadImageBufferArgs, ReadImageToCanvasOptions, Viewport } from "../Viewport";
 import { ViewRect } from "../common/ViewRect";
 import { CanvasDecoration } from "./CanvasDecoration";
 import { Decorations } from "./Decorations";
@@ -176,7 +176,7 @@ export abstract class RenderTarget implements IDisposable, RenderMemory.Consumer
   /** @internal */
   public readImageBuffer(_args?: ReadImageBufferArgs): ImageBuffer | undefined { return undefined; }
   /** @internal */
-  public readImageToCanvas(): HTMLCanvasElement { return document.createElement("canvas"); }
+  public readImageToCanvas(_options?: ReadImageToCanvasOptions): HTMLCanvasElement { return document.createElement("canvas"); }
   /** @internal */
   public collectStatistics(_stats: RenderMemory.Statistics): void { }
 

core/frontend/src/render/webgl/Target.ts

@@ -15,7 +15,7 @@ import { ViewRect } from "../../common/ViewRect";
 import { canvasToImageBuffer, canvasToResizedCanvasWithBars, imageBufferToCanvas } from "../../common/ImageUtil";
 import { HiliteSet, ModelSubCategoryHiliteMode } from "../../SelectionSet";
 import { SceneContext } from "../../ViewContext";
-import { ReadImageBufferArgs, Viewport } from "../../Viewport";
+import { ReadImageBufferArgs, ReadImageToCanvasOptions, Viewport } from "../../Viewport";
 import { IModelConnection } from "../../IModelConnection";
 import { CanvasDecoration } from "../CanvasDecoration";
 import { Decorations } from "../Decorations";
@@ -64,6 +64,7 @@ import { FrameStatsCollector } from "../FrameStats";
 import { ActiveSpatialClassifier } from "../../SpatialClassifiersState";
 import { AnimationNodeId } from "../../common/internal/render/AnimationNodeId";
 import { _implementationProhibited } from "../../common/internal/Symbols";
+import { IModelApp } from "../../IModelApp";
 
 function swapImageByte(image: ImageBuffer, i0: number, i1: number) {
   const tmp = image.data[i0];
@@ -1177,12 +1178,24 @@ export abstract class Target extends RenderTarget implements RenderTargetDebugCo
     return image;
   }
 
-  public copyImageToCanvas(): HTMLCanvasElement {
+  public copyImageToCanvas(options?: ReadImageToCanvasOptions): HTMLCanvasElement {
     const image = this.readImageBuffer();
     const canvas = undefined !== image ? imageBufferToCanvas(image, false) : undefined;
     const retCanvas = undefined !== canvas ? canvas : document.createElement("canvas");
     const pixelRatio = this.devicePixelRatio;
     retCanvas.getContext("2d")!.scale(pixelRatio, pixelRatio);
+
+      const vp = IModelApp.viewManager.selectedView;
+      // vp.rendersToScreen tells us if the view is being rendered directly to the webgl canvas on screen, which happens in the case of a single viewport.
+      // In that case, we need to combine the 2d canvas with the webgl canvas or we will lose canvas decorations in the copied image.
+      // options.includeCanvasDecorations will be true if the caller wants to include the decorations in the copied image.
+      if (vp && vp.rendersToScreen && options?.includeCanvasDecorations) {
+        const twoDCanvas = vp.canvas;
+        const ctx = retCanvas.getContext("2d")!;
+        ctx.drawImage(twoDCanvas, 0, 0);
+      }
+
+
     return retCanvas;
   }
 
@@ -1512,8 +1525,8 @@ export class OnScreenTarget extends Target {
     return toScreen ? this._webglCanvas.canvas : undefined;
   }
 
-  public override readImageToCanvas(): HTMLCanvasElement {
-    return this._usingWebGLCanvas ? this.copyImageToCanvas() : this._2dCanvas.canvas;
+  public override readImageToCanvas(options?: ReadImageToCanvasOptions): HTMLCanvasElement {
+    return this._usingWebGLCanvas ? this.copyImageToCanvas(options) : this._2dCanvas.canvas;
   }
 }
 
@@ -1556,8 +1569,8 @@ export class OffScreenTarget extends Target {
     this.renderSystem.frameBufferStack.pop();
   }
 
-  public override readImageToCanvas(): HTMLCanvasElement {
-    return this.copyImageToCanvas();
+  public override readImageToCanvas(options?: ReadImageToCanvasOptions): HTMLCanvasElement {
+    return this.copyImageToCanvas(options);
   }
 }
 

test-apps/display-test-app/public/locales/en/SVTTools.json

@@ -55,6 +55,9 @@
     "SaveImage": {
       "keyin": "dta save image"
     },
+    "SaveImageWithCanvasDecorations": {
+      "keyin": "dta save image with decorations"
+    },
     "OutputShaders": {
       "keyin": "dta output shaders"
     },

test-apps/display-test-app/src/frontend/App.ts

@@ -57,7 +57,7 @@ import { MarkupTool, ModelClipTool, ZoomToSelectedElementsTool } from "./Viewer"
 import { MacroTool } from "./MacroTools";
 import { RecordTileSizesTool } from "./TileSizeRecorder";
 import { TerrainDrapeTool } from "./TerrainDrapeTool";
-import { SaveImageTool } from "./SaveImageTool";
+import { SaveImageTool, SaveImageWithCanvasDecorationsTool } from "./SaveImageTool";
 import { ToggleSecondaryIModelTool } from "./TiledGraphics";
 import { BingTerrainMeshProvider } from "./BingTerrainProvider";
 import { AttachCustomRealityDataTool, registerRealityDataSourceProvider } from "./RealityDataProvider";
@@ -358,6 +358,7 @@ export class DisplayTestApp {
       ResizeWindowTool,
       RestoreWindowTool,
       SaveImageTool,
+      SaveImageWithCanvasDecorationsTool,
       ShutDownTool,
       SignInTool,
       SignOutTool,

test-apps/display-test-app/src/frontend/SaveImageTool.ts

@@ -5,8 +5,8 @@
 
 import { ProcessDetector } from "@itwin/core-bentley";
 import { Point2d } from "@itwin/core-geometry";
-import { imageBufferToPngDataUrl, IModelApp, openImageDataUrlInNewWindow, Tool } from "@itwin/core-frontend";
-import { parseArgs } from "@itwin/frontend-devtools";
+import { imageBufferToPngDataUrl, IModelApp, openImageDataUrlInNewWindow, ReadImageToCanvasOptions, Tool } from "@itwin/core-frontend";
+import { parseArgs, parseToggle } from "@itwin/frontend-devtools";
 
 interface SaveImageOptions {
   copyToClipboard?: boolean;
@@ -89,3 +89,49 @@ export class SaveImageTool extends Tool {
     return this.run(opts);
   }
 }
+
+export class SaveImageWithCanvasDecorationsTool extends Tool {
+  public static override toolId = "SaveImageWithCanvasDecorations";
+  public static override get minArgs() { return 0; }
+  public static override get maxArgs() { return 1; }
+
+  public override async run(showDecorations: boolean): Promise<boolean> {
+    const vp = IModelApp.viewManager.selectedView;
+    if (!vp)
+      return false;
+
+    const width = vp.viewRect.width;
+    const height = vp.viewRect.height;
+
+    await vp.waitForSceneCompletion();
+    const buffer = vp.readImageBuffer({ size: new Point2d(width, height) });
+    if (!buffer) {
+      alert("Failed to read image");
+      return true;
+    }
+
+    const options: ReadImageToCanvasOptions = {
+      includeCanvasDecorations: showDecorations,
+    }
+
+    const canvas = vp.readImageToCanvas(options);
+    const url = canvas.toDataURL();
+
+    if (!url) {
+      alert("Failed to produce PNG");
+      return true;
+    }
+
+    openImageDataUrlInNewWindow(url, "Saved View");
+    return true;
+  }
+
+  public override async parseAndRun(...args: string[]): Promise<boolean> {
+    let showDecorations;
+    if (!args[0])
+      showDecorations = true;
+    else
+      showDecorations = !!parseToggle(args[0]);
+    return this.run(showDecorations);
+  }
+}