GPUQueue: copyExternalImageToTexture() 方法

source

表示写入目标的源及其原点的对象。它可以包含以下属性

source

提供要复制的快照源的对象。它可以是 ImageBitmap、HTMLVideoElement、VideoFrame、HTMLCanvasElement 或 OffscreenCanvas。图像源数据在调用 copyExternalImageToTexture() 的那一刻被捕获。

origin 可选

指定复制原点的对象或数组——要从中复制的源子区域的左上角。与 copySize 一起，这定义了源子区域的完整范围。如果省略 origin 的任何或所有部分，则 x 和 y 值默认为 0。

以下是一个数组示例

js

origin: [0, 0];

等效的对象如下所示

js

origin: {
  x: 0,
  y: 0
}

flipY 可选

布尔值。如果设置为 true，则图像捕获将垂直翻转。如果省略，则 flipY 默认为 false。

destination

定义要将捕获的图像写入的纹理子资源和原点，以及编码元数据的对象。它可以包含以下属性

aspect 可选

定义将图像写入纹理的哪些方面的枚举值。可能的值为

"all"

将写入纹理格式的所有可用方面，这可能意味着所有或任何颜色、深度和模板，具体取决于您正在处理的格式类型。

"depth-only"

仅写入深度或模板格式的深度方面。

"stencil-only"

仅写入深度或模板格式的模板方面。

如果省略，则aspect取值为"all"。

colorSpace 可选

一个枚举值，描述用于将数据编码到目标纹理的颜色空间和编码。可能的值为"srgb"和"display-p3"。如果省略，则colorSpace默认为"srgb"。

注意：如果目标纹理的格式可以表示，则编码可能会导致写入目标纹理的值超出范围[0, 1]。否则，结果将被钳制到目标纹理格式的范围。如果colorSpace与源图像颜色空间匹配，则可能不需要转换。

mipLevel 可选

表示要将图像写入到的纹理的mipmap级别的一个数字。如果省略，则mipLevel默认为0。

origin 可选

一个对象或数组，指定复制的原点——要将图像数据写入到的纹理区域的最小角。与copySize一起，这定义了要复制到的区域的完整范围。如果省略了origin的任何或所有x、y和z值，则默认为0。

以下是一个数组示例

js

origin: [0, 0, 0];

等效的对象如下所示

js

origin: {
  x: 0,
  y: 0,
  z: 0
}

premultipliedAlpha 可选

一个布尔值。如果设置为true，则写入纹理的图像数据的RGB通道将乘以alpha通道。如果省略，则premultipliedAlpha默认为false。

注意：如果此选项设置为true并且source也进行了预乘，则即使源RGB值超过其对应的alpha值，也必须保留源RGB值。

纹理

一个GPUTexture对象，表示要将数据写入到的纹理。

复制大小

一个对象或数组，指定要复制的区域的width、height和depthOrArrayLayers。

以下是一个数组示例

js

origin: [16, 1, 1];

等效的对象如下所示

js

origin: {
  width: 16,
  height: 1,
  depthOrArrayLayers: 1
}

必须包含width值。如果省略了height或depthOrArrayLayers值，则默认为1。

无(Undefined)。

OperationError DOMException

如果以下条件未满足，则方法会抛出OperationError

• source.origin.x加上要复制到的区域的宽度小于或等于源图像的宽度。
• source.origin.y加上要复制到的区域的高度小于或等于源图像的高度。
• source.origin.z加上要复制到的区域的depthOrArrayLayers小于或等于1。
• dataOffset等于或小于data的大小。
• data的大小（在TypedArray的情况下转换为字节）是4的倍数。

SecurityError DOMException

如果图像源数据跨源，则抛出此异常。

调用writeTexture()时必须满足以下条件，否则会生成GPUValidationError，并且GPUQueue将变为无效

• mipLevel小于目标GPUTexture.mipLevelCount。
• origin.x是目标GPUTexture.format的纹理块宽度的倍数。
• origin.y是目标GPUTexture.format的纹理块高度的倍数。
• 如果目标GPUTexture.format是深度或模板格式，则图像捕获大小等于size。
• 目标GPUTexture.usage包含GPUTextureUsage.COPY_DST和GPUTextureUsage.RENDER_ATTACHMENT标志。
• 目标GPUTexture.dimension为"2d"。
• 目标GPUTexture.sampleCount为1。
• 目标GPUTexture.format是以下格式之一（支持GPUTextureUsage.RENDER_ATTACHMENT用法）
  • "r8unorm"
  • "r16float"
  • "r32float"
  • "rg8unorm"
  • "rg16float"
  • "rg32float"
  • "rgba8unorm"
  • "rgba8unorm-srgb"
  • "bgra8unorm"
  • "bgra8unorm-srgb"
  • "rgb10a2unorm"
  • "rgba16float"
  • "rgba32float"
• destination.origin.x + copySize.width小于或等于destination GPUTexture width。
• destination.origin.y + copySize.height小于或等于destination GPUTexture height。
• destination.origin.z + copySize.depthOrArrayLayers小于或等于destination GPUTexture depthOrArrayLayers。
• destination GPUTexture.width是目标GPUTexture.format的纹理块宽度的倍数。
• destination GPUTexture.height是目标GPUTexture.format的纹理块高度的倍数。

在WebGPU示例纹理立方体示例中，以下代码段用于获取图像并将其上传到GPUTexture

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],
  );
}

• WebGPU API