A user account is required in order to edit this wiki, but we've had to disable public user registrations due to spam.

To request an account, ask an autoconfirmed user on IRC (such as one of these permanent autoconfirmed members) or send an e-mail to admin@wiki.whatwg.org with your desired username and an explanation of the first edit you'd like to make. (Do not use this e-mail address for any other inquiries, as they will be ignored or politely declined.)

ImageBitmap Constructor taking URL

From WHATWG Wiki
Jump to: navigation, search
Allows creating an ImageBitmap from the URL of an image.

Use Case Description

ImageBitmap provides a useful abstraction for image data that can be drawn to a 2D canvas context or uploaded to a texture in a WebGL canvas context. It attempts to move all of the image decoding and preparation work out of the critical path, so that by the time an ImageBitmap is constructed, the data it contains is in exactly the right format for rendering. ImageBitmap Options provides control over the image decoding process so that the resulting bitmap is in exactly the desired form. For example, it can be used to disable the user agent's premultiplication of the alpha channel into the color channels.

Currently an ImageBitmap can only be constructed from a fully-loaded media resource such as an HTMLImageElement. Unfortunately, most user agents decode the image data before calling HTMLImageElement's onload handler, and it is only legal to construct an ImageBitmap after the HTMLImageElement's onload handler is called. If the ImageBitmap options would specify different decoding parameters than the browser's default, the image must be decoded twice, which is inefficient. Further, some user agents discard the compressed image data from HTMLImageElements before firing the onload handler.

This proposal adds URL to the [ImageBitmapSource union type], which is the first argument to [createImageBitmap]. The image is downloaded from that URL, decoded, and processed as part of the construction of the ImageBitmap, taking into account the ImageBitmap options. If any errors occur during the downloading or decoding process, including if the image is not single-origin after honoring the crossOrigin attribute of the ImageBitmap options, the Promise returned from createImageBitmap is rejected. If image downloading and decoding succeeds, then the promise is resolved with the new ImageBitmap as its value.

Current Limitations

The intent of ImageBitmap is to prepare the image data in the desired form for drawing or texture uploading before resolving the promise returned from createImageBitmap. Unfortunately, most user agents decode the image before calling the onload handler, and it's only legal to pass an HTMLImageElement to createImageBitmap once the image's onload handler has been called. This means that at a minimum, in order to respect the ImageBitmap Options argument to createImageBitmap, two decodes of the image must be done, which is inefficient.

Further, some user agents discard the compressed image data for an HTMLImageElement after decoding it, and before calling the onload handler. Honoring ImageBitmap Options in these user agents is not possible without rearchitecting their image decoding subsystem.

Current Usage and Workarounds

Most WebGL applications encode normal maps or other non-image data into images, and upload these images to textures using WebGL-specific options that skip the alpha premultiplication or color correction the user agent may perform. Some WebGL implementers have pointed out that the current mechanisms usually result in a synchronous image re-decode. Switching to use ImageBitmap to provide control over these image decoding options will be more efficient, and allow the WebGL mechanisms to be removed in the next version of that specification.


Provides the most efficient image decoding path for canvas applications requiring control over image decoding.

Requests for this Feature

  • Microsoft has requested this feature in order to provide an efficient path for uploading WebGL images to textures.
  • Other WebGL implementers (Apple, Google, Mozilla) support adding this feature and will implement it.
  • The WebGL 2.0 specification under development will remove the WebGL-specific image decoding options and rely on this mechanism instead.

Proposed Solutions

Processing Model

Compared to constructing an ImageBitmap from an HTMLImageElement, this alternative construction path downloads and decodes the image data as part of resolving the promise returned by createImageBitmap.


Only supports single images. There's no provision for downloading other types of media from URLs.


Browser vendors would trigger their usual image downloading and decoding code paths upon creating an ImageBitmap from a URL. Browsers would implement this new API in order to provide more efficient image handling for 2D and WebGL canvas applications.


WebGL application authors in particular would readily update their code in order to use this new API because it will provide more efficient uploading of images into textures. It's straightforward to add conditional code which prefers this new, more efficient, mechanism, and which uses the older texture upload paths if it's not available.