fix(createImage): make waiting on animation frame optional

Added configuration property waitForAnimationFrameAcquired. Default value is false.

Closes #502

BREAKING CHANGE:
 Waiting on animation frame was default behaviour since version 1.11.12. If you rely on this feature, explicitly set waitForAnimationFrameAcquired to true.

Author: Michal Biroš

src/clone-node.ts

@@ -9,12 +9,12 @@ import {
 import { getMimeType } from './mimes'
 import { resourceToDataURL } from './dataurl'
 
-async function cloneCanvasElement(canvas: HTMLCanvasElement) {
+async function cloneCanvasElement(canvas: HTMLCanvasElement, options: Options) {
   const dataURL = canvas.toDataURL()
   if (dataURL === 'data:,') {
     return canvas.cloneNode(false) as HTMLCanvasElement
   }
-  return createImage(dataURL)
+  return createImage(dataURL, options)
 }
 
 async function cloneVideoElement(video: HTMLVideoElement, options: Options) {
@@ -25,13 +25,13 @@ async function cloneVideoElement(video: HTMLVideoElement, options: Options) {
     canvas.height = video.clientHeight
     ctx?.drawImage(video, 0, 0, canvas.width, canvas.height)
     const dataURL = canvas.toDataURL()
-    return createImage(dataURL)
+    return createImage(dataURL, options)
   }
 
   const poster = video.poster
   const contentType = getMimeType(poster)
   const dataURL = await resourceToDataURL(poster, contentType, options)
-  return createImage(dataURL)
+  return createImage(dataURL, options)
 }
 
 async function cloneIFrameElement(iframe: HTMLIFrameElement, options: Options) {
@@ -55,7 +55,7 @@ async function cloneSingleNode<T extends HTMLElement>(
   options: Options,
 ): Promise<HTMLElement> {
   if (isInstanceOfElement(node, HTMLCanvasElement)) {
-    return cloneCanvasElement(node)
+    return cloneCanvasElement(node, options)
   }
 
   if (isInstanceOfElement(node, HTMLVideoElement)) {

src/index.ts

@@ -31,7 +31,7 @@ export async function toCanvas<T extends HTMLElement>(
 ): Promise<HTMLCanvasElement> {
   const { width, height } = getImageSize(node, options)
   const svg = await toSvg(node, options)
-  const img = await createImage(svg)
+  const img = await createImage(svg, options)
 
   const canvas = document.createElement('canvas')
   const context = canvas.getContext('2d')!

src/types.ts

@@ -86,6 +86,11 @@ export interface Options {
    * A boolean to turn off auto scaling for truly massive images..
    */
   skipAutoScale?: boolean
+  /**
+   * An option for rendering the image only when the image is visible on the frame.
+   * This might be useful for performance reasons when rendering a large number of images.
+   */
+  waitForAnimationFrameAcquired?: boolean
   /**
    * A string indicating the image format. The default type is image/png; that type is also used if the given type isn't supported.
    */

src/util.ts

@@ -196,12 +196,19 @@ export function canvasToBlob(
   })
 }
 
-export function createImage(url: string): Promise<HTMLImageElement> {
+export function createImage(
+  url: string,
+  options: Options = {},
+): Promise<HTMLImageElement> {
   return new Promise((resolve, reject) => {
     const img = new Image()
     img.onload = () => {
       img.decode().then(() => {
-        requestAnimationFrame(() => resolve(img))
+        if (options.waitForAnimationFrameAcquired) {
+          requestAnimationFrame(() => resolve(img))
+        } else {
+          resolve(img)
+        }
       })
     }
     img.onerror = reject