ThecopyExternalImageToTexture() method of theGPUQueue interface copies a snapshot taken from a source image, video, or canvas into a givenGPUTexture.

Using this function allows the user agent to determine the most efficient way to copy the data over for each source type.

Syntax

copyExternalImageToTexture(source, destination, copySize)

Parameters

source

An object representing the source to write to the destination, and its origin. This can take the following properties:

source

An object providing the source of the snapshot to copy. This can be anHTMLCanvasElement,HTMLImageElement,HTMLVideoElement,ImageBitmap,ImageData,OffscreenCanvas, orVideoFrame object. The image source data is captured at the exact momentcopyExternalImageToTexture() is invoked.

originOptional

An object or array specifying the origin of the copy — the top-left corner of the source sub-region to copy from. Together withcopySize, this defines the full extent of the source sub-region. Thex andy values default to 0 if any of all oforigin is omitted.

For example, you can pass an array like[0, 0], or its equivalent object{ x: 0, y: 0 }.

flipYOptional

A boolean. If set totrue, the image capture is flipped vertically. If omitted,flipY defaults tofalse.

destination

An object defining the texture subresource and origin to write the captured image to, plus encoding metadata. This can take the following properties:

aspectOptional

An enumerated value defining which aspects of the texture to write the image to. Possible values are:

"all"

All available aspects of the texture format will be written to, which can mean all or any of color, depth, and stencil, depending on what kind of format you are dealing with.

"depth-only"

Only the depth aspect of adepth-or-stencil format will be written to.

"stencil-only"

Only the stencil aspect of a depth-or-stencil format will be written to.

If omitted,aspect takes a value of"all".

colorSpaceOptional

An enumerated value describing the color space and encoding used to encode data into the destination texture. Possible values are"srgb" and"display-p3". If omitted,colorSpace defaults to"srgb".

Note:The encoding may result in values outside of the range[0, 1] being written to the target texture, if its format can represent them. Otherwise, the results are clamped to the target texture format's range. Conversion may not be necessary ifcolorSpace matches the source image color space.

mipLevelOptional

A number representing the mip-map level of the texture to write the image to. If omitted,mipLevel defaults to 0.

originOptional

An object or array specifying the origin of the copy — the minimum corner of the texture region to write the image data to. Together withcopySize, this defines the full extent of the region to copy to. Thex,y, andz values default to 0 if any of all oforigin is omitted.

For example, you can pass an array like[0, 0, 0], or its equivalent object{ x: 0, y: 0, z: 0 }.

premultipliedAlphaOptional

A boolean. If set totrue, the image data written into the texture will have its RGB channels premultiplied by the alpha channel. If omitted,premultipliedAlpha defaults tofalse.

Note:If this option is set totrue and thesource is also premultiplied, the source RGB values must be preserved even if they exceed their corresponding alpha values.

texture

AGPUTexture object representing the texture to write the data to.

copySize

An object or array specifyingwidth,height, anddepthOrArrayLayers — of the region to copy from/to.

For example, you can pass an array like[16, 1, 1], or its equivalent object{ width: 16, height: 1, depthOrArrayLayers: 1 }.

Thewidth value has to be included. If theheight ordepthOrArrayLayers values are omitted, they default to 1.

Return value

None (Undefined).

Exceptions

OperationErrorDOMException

The method throws anOperationError if the following criteria are not met:

• source.origin.x + the width of the region to copy to is less than or equal to the width of the source image.
• source.origin.y + the height of the region to copy to is less than or equal to the height of the source image.
• source.origin.z + the depthOrArrayLayers of the region to copy to is less than or equal to 1.
• dataOffset is equal to or smaller than the size ofdata.
• The size ofdata (when converted to bytes, in the case ofTypedArrays) is a multiple of 4.

SecurityErrorDOMException

Thrown if the image source data is cross-origin.

Validation

The following criteria must be met when callingwriteTexture(), otherwise aGPUValidationError is generated and theGPUQueue becomes invalid:

• mipLevel is less than the destinationGPUTexture.mipLevelCount.
• origin.x is a multiple of the texel block width of the destinationGPUTexture.format.
• origin.y is a multiple of the texel block height of the destinationGPUTexture.format.
• If the destinationGPUTexture.format is adepth-or-stencil format, the image capture size is equal tosize.
• The destinationGPUTexture.usage includes theGPUTextureUsage.COPY_DST andGPUTextureUsage.RENDER_ATTACHMENT flags.
• The destinationGPUTexture.dimension is"2d".
• The destinationGPUTexture.sampleCount is 1.
• The destinationGPUTexture.format is one of the following (which supportGPUTextureUsage.RENDER_ATTACHMENT usage):
  • "r8unorm"
  • "r16float"
  • "r32float"
  • "rg8unorm"
  • "rg16float"
  • "rg32float"
  • "rgba8unorm"
  • "rgba8unorm-srgb"
  • "bgra8unorm"
  • "bgra8unorm-srgb"
  • "rgb10a2unorm"
  • "rgba16float"
  • "rgba32float"
• destination.origin.x +copySize.width is less than or equal to thedestinationGPUTexturewidth.
• destination.origin.y +copySize.height is less than or equal to thedestinationGPUTextureheight.
• destination.origin.z +copySize.depthOrArrayLayers is less than or equal to thedestinationGPUTexturedepthOrArrayLayers.
• ThedestinationGPUTexture.width is a multiple of the texel block width of the destinationGPUTexture.format.
• ThedestinationGPUTexture.height is a multiple of the texel block height of the destinationGPUTexture.format.

Examples

In the WebGPU SamplesTextured Cube example, the following snippet is used to fetch an image and upload it into aGPUTexture:

let cubeTexture;{  const img = document.createElement("img");  img.src = new URL(    "../../../assets/img/Di-3d.png",    import.meta.url,  ).toString();  await img.decode();  const imageBitmap = await createImageBitmap(img);  cubeTexture = device.createTexture({    size: [imageBitmap.width, imageBitmap.height, 1],    format: "rgba8unorm",    usage:      GPUTextureUsage.TEXTURE_BINDING |      GPUTextureUsage.COPY_DST |      GPUTextureUsage.RENDER_ATTACHMENT,  });  device.queue.copyExternalImageToTexture(    { source: imageBitmap },    { texture: cubeTexture },    [imageBitmap.width, imageBitmap.height],  );}

Specifications

Browser compatibility

See also

• TheWebGPU API