createImageBitmap MonkeyPatch

A monkey-patch to the HTML's `createImageBitmap` method.

Only Chromium based browsers currently support the full API, Firefox supporting it only partially and Safari not at all. This means that for cross-browser projects, we can't use it, despite its great usefulness and ease of use.

This monkey-patch aims at filling as much gaps as possible between all these browsers.

However, truth be told, it can not polyfill everything in this API, here is a list of what it supports in every browsers and what it doesn't:

Feature
createImageBitmap + cropping	native	native	✔ ⁽¹⁾
HTMLImageElement as source	native	native	✔
HTMLCanvasElement as source	native	native	✔
OffscreenCanvas as source	native	❌	❌
SVGImageElement as source	native	native	✔
ImageBitmap as source	native	native	✔
ImageData as source	native	native	✔
Raster image in Blob as source	native	native	✔
SVG image in Blob as source ⁽²⁾	✔	✔	✔
ImageBitmapOptions	native	✔	✔
resizeWidth & resizeHeight	native	✔	✔
resizeQuality: pixelated	native	✔	✔
resizeQuality: low	native	native	✔
resizeQuality: medium	native	❌	❌
resizeQuality: high	native	❌	❌
imageOrientation	native	✔	✔
colorSpaceConversion	native	❌	❌
premultiplyAlpha	native	❌	❌
Available in Workers	native	native ⁽³⁾	❌
Transferrable	native	native	❌

^{(1) Returns a modified HTMLCanvasElement instance in place of an ImageBitmap object.}
^{(2) Only for SVG images with an intrinsic width and height, as per the specs recommendation.}
^{(3) Only the native implementation is available in Workers}

How to use

You can include the bundled version available in /src/ in a <script> tag before the first use of createImageBitmap,

<script src="/path/to/the/script/createImageBitmap.js"></script>

or you can use the ESM modules available in /src/.

<script type="module" src="/path/to/the/script/monkeypatch.js"></script>

Why isn't the monkey-patch available in web Workers?

The monkey-patch makes most of its work on an HTMLCanvasElement 2d context, and relies in various places in the ability to have DOM Elements (for instance HTMLImageElements are used to load images from Blobs). Since Web-Workers don't have access to the DOM nor any Elements, the scope of what this monkey-patch could do currently seems too limited to be worth the pain.

Why isn't the monkey-patch available in node-js?

People at node-canvas probably are the best to implement such a thing. It should take only a few tweaks from here to get a node-canvas + jsdom version working though, so feel free to fork this repo and propose them a PR if you wish.

Why doesn't this monkey-patch add support for options like all resize qualities, colorSpaceConversion or *premultiplyAlpha**?

Mainly lack of time. We accept PR though ¯_(ツ)_/¯

Why no ImageBitmapRenderer at least?

Still lack of time, and a Safari weirdness where they do expose this interface, even though they don't have the ImageBitmap that goes with it, and which won't accept our "fake" version. But hopefully, this will be one of the first next additions.

What about my old Internet Explorer? Can I use it there?

Not as-is. The scripts are written using ES2021 syntax and are targeting recent browsers.
You should be able to transpile it to ES5 though, and it should work even in IE9, but it hasn't been tested there.

Does this mean even my shiny Chromium browser will use the less than optimal 2D context instead of a true ImageBitmap?

No, the monkey-patch only patches what it detects is not supported by the current browser. It leaves the native implementation do its job when it can do it.

rokoroku/createImageBitmap