GPUQueue: copyExternalImageToTexture() 方法

语法

copyExternalImageToTexture(source, destination, copySize)

参数

source

一个表示要写入目标的数据源及其原点的对象。它可以具有以下属性：

source

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

origin 可选

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

例如，您可以传递一个数组，如 [0, 0]，或其等效对象 { 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 可选

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

origin 可选

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

例如，您可以传递一个数组，如 [0, 0, 0]，或其等效对象 { x: 0, y: 0, z: 0 }。

premultipliedAlpha 可选

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

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

texture

一个表示要写入数据的 GPUTexture 对象。

copySize

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

例如，您可以传递一个数组，如 [16, 1, 1]，或其等效对象 { 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 的大小（转换为字节后，对于 TypedArrays）是 4 的倍数。

SecurityError DOMException

如果图像源数据是跨域的，则会抛出此错误。

验证

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

• mipLevel 小于目标 GPUTexture.mipLevelCount。
• origin.x 是目标 GPUTexture.format 的 texel 块宽度的倍数。
• origin.y 是目标 GPUTexture.format 的 texel 块高度的倍数。
• 如果目标 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 小于或等于 目标 GPUTexture 的 width。
• destination.origin.y + copySize.height 小于或等于 目标 GPUTexture 的 height。
• destination.origin.z + copySize.depthOrArrayLayers 小于或等于 目标 GPUTexture 的 depthOrArrayLayers。
• 目标 GPUTexture.width 是目标 GPUTexture.format 的 texel 块宽度的倍数。
• 目标 GPUTexture.height 是目标 GPUTexture.format 的 texel 块高度的倍数。

示例

在 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