Decode image data synchronously.
The data must be a Buffer of an encoded image -- an ArrayBuffer or
typed array throws -- or a data: URL. The optional second argument
sets Image.src for identification only; it is never fetched, so
it need not be a valid URL.
Constructing from data is this library's addition: a browser's Image
constructor takes only a width and a height.
Optionaldata: string | URL | Buffer<ArrayBufferLike>Optionalsrc: stringReadonlycompleteWhether the image has finished loading, successfully or not.
Derived from load state, as in the browser: assigning to it has never done anything, here or there.
Called with the Error if loading or decoding failed. Assigning
replaces the previous handler rather than adding a second one; use
on("error", ...) to stack listeners.
Called once the image has loaded and decoded. The image is passed as the
argument and is also this, so a non-arrow function can use either.
🧪 Not in the HTML Canvas standard.
How long each frame is shown, in milliseconds.
One entry per frame, so this array is always frames long. A still image
reports a single 0: it is shown until something else is drawn, which is
not a duration.
A 0 on an animated frame is reported as stored, and does not mean the
frame is shown instantly. Viewers clamp a very short GIF delay upward --
Firefox renders anything of 10ms or less at 100ms -- so a zero-delay
frame is the slowest one, not the fastest.
🧪 Not in the HTML Canvas standard.
How many frames the image holds.
1 for a still image. Animated GIF, WebP and APNG report every frame
they contain -- the last of them demuxed by this library, since Skia
opens an APNG as the still image its IDAT holds and reports one frame.
Height of the decoded image in pixels, read-only for the same reason Image.width is.
The image's intrinsic height. As naturalWidth, this equals height.
The image's intrinsic width.
The same number as width here. They differ in a browser only because an
<img> can be resized by attribute or by CSS, and there is no layout in
this environment for that to happen in.
Where the image was loaded from. Assigning starts a load and, when it
finishes, fires load or error.
The setter takes more than the standard's URL string: an http(s) URL, a
local file path, a data: URL, a Buffer of encoded bytes, or a Sharp
image. Assigning again abandons a load already in flight rather than
racing it.
Loads a new image, from the same sources loadImage takes. The
decode is asynchronous: wait on Image.decode or the complete
flag before drawing.
Width of the decoded image in pixels, and read-only: drawImage uses
the intrinsic size, so assigning could not have meant anything. 0
until the image loads.
An SVG with no intrinsic size is rasterized at a height of 150 with the
width taken from its viewBox aspect.
Resolves once the image is ready to draw, and rejects if it failed.
Unlike the browser's, which resolves with undefined, this resolves
with the image itself. On an image whose src was never set it rejects
rather than waiting forever.
🧪 Not in the HTML Canvas standard.
One frame of the image, as an Image of its own.
Frames that cover only part of the canvas are composited against the ones before them, so every frame comes back whole and drawable, and they may be asked for in any order.
Nothing advances a frame on its own -- there is no clock here. An animation plays because the caller picks the frame each of its own output frames shows:
const spinner = await loadImage("spinner.gif")
for (let i = 0; i < 24; i++) {
ctx.drawImage(spinner.frame(i % spinner.frames), 0, 0)
canvas.newPage()
}
A negative index counts from the end, so frame(-1) is the last one --
the rule page follows in the export options, and the one
Array.prototype.at follows. A fractional index truncates toward zero
before the end is counted from, as at does.
Optionalindex: number
A decoded image, ready to be drawn with CanvasRenderingContext2D.drawImage.
Loading is asynchronous unless the data is already in hand: pass a
Bufferor a data URL to the constructor and the image is Image.complete immediately. Otherwise assign Image.src and wait for theloadevent, Image.decode, or use loadImage.MDN Reference