GPUDevice: importExternalTexture() method

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The importExternalTexture() method of the GPUDevice interface takes an HTMLVideoElement as an input and returns a GPUExternalTexture wrapper object containing a snapshot of the video that can be used as a frame in GPU rendering operations.

Syntax

js

importExternalTexture(descriptor)

Parameters

descriptor

An object containing the following properties:

colorSpace Optional

An enumerated value specifying the color space to use for the video frame. Possible values are "srgb" and "display-p3". If omitted, colorSpace defaults to "srgb".

label Optional

A string providing a label that can be used to identify the object, for example in GPUError messages or console warnings.

source

The HTMLVideoElement source of the video snapshot.

Return value

A GPUExternalTexture object instance.

Validation

The following criteria must be met when calling importExternalTexture(), otherwise a GPUValidationError is generated and an invalid GPUExternalTexture object is returned:

  • The video snapshot is usable (e.g. the video source is loaded properly, and doesn't have a width or height of 0).

Exceptions

SecurityError DOMException

Thrown if the video source data is cross-origin.

Examples

In the WebGPU samples Video Uploading sample, an importExternalTexture() call is used as the value of a bind group entry resource, specified when creating a GPUBindGroup via a GPUDevice.createBindGroup() call:

js

//...

const uniformBindGroup = device.createBindGroup({
  layout: pipeline.getBindGroupLayout(0),
  entries: [
    {
      binding: 1,
      resource: sampler,
    },
    {
      binding: 2,
      resource: device.importExternalTexture({
        source: video,
      }),
    },
  ],
});

//...

Specifications

Specification
WebGPU
# dom-gpudevice-importexternaltexture

Browser compatibility

BCD tables only load in the browser

See also