GPUCommandEncoder: copyTextureToTexture() 方法

语法

copyTextureToTexture(source, destination, copySize)

参数

source

一个定义要从中复制数据的纹理的对象（参见 Copy texture object structure）。结合 copySize，这定义了源纹理子资源的区域。

destination

一个定义要写入数据的纹理的对象（参见 Copy texture object structure）。结合 copySize，这定义了目标纹理子资源的区域。

copySize

一个对象或数组，指定复制数据的宽度、高度和深度/数组层数。宽度值必须始终指定，而高度和深度/数组层数是可选的，如果省略则默认为 1。

例如，您可以传递一个数组 [16, 16, 2]，或等效的对象 { width: 16, height: 16, depthOrArrayLayers: 2 }。

Copy texture object structure

复制纹理对象具有以下结构

aspect 可选

一个枚举值，定义了要从中/向其复制数据的纹理的哪些方面。可能的值为：

"all"

纹理格式的所有可用方面都将从中/向其复制，这可能意味着颜色、深度和模板中的所有或任何方面，具体取决于您处理的格式类型。

"depth-only"

仅从/向 深度或模板格式 复制深度方面。

"stencil-only"

仅从中/向深度或模板格式复制模板方面。

如果省略，aspect 的值为 "all"。

mipLevel 可选

一个数字，表示要从中/向其复制数据的纹理的 mipmap 级别。如果省略，mipLevel 默认为 0。

origin 可选

一个对象或数组，指定复制/目标的起点——要从中/向其复制数据的纹理区域的最小角。与 size 一起，这定义了要从中/向其复制的区域的完整范围。如果省略了 origin 的任何部分（或全部），则 x、y 和 z 值默认为 0。

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

texture

一个 GPUTexture 对象，代表要从中/向其复制数据的纹理。

返回值

无 (Undefined)。

验证

调用 copyTextureToTexture() 时必须满足以下条件，否则将生成 GPUValidationError，并且 GPUCommandEncoder 会失效。

对于 source：

• source 的 GPUTexture.usage 包含 GPUTextureUsage.COPY_SRC 标志。

对于 destination：

• source 的 GPUTexture.usage 包含 GPUTextureUsage.COPY_DST 标志。

对于 source 和 destination

• mipLevel 小于 GPUTexture.mipLevelCount。
• origin.x 是 GPUTexture.format 的 texel 块宽度的倍数。
• origin.y 是 GPUTexture.format 的 texel 块高度的倍数。
• 源和目标 texture 的 GPUTexture.format 是可复制兼容的。
• 源和目标 texture 的 GPUTexture.sampleCount 相等。
• 如果 GPUTexture.format 是 深度或模板格式，或者 GPUTexture.sampleCount 大于 1，则子资源大小等于 size。
• texture 的 GPUTexture.sampleCount 为 1。
• aspect 指的是 GPUTexture.format 的单个方面。
• 该方面根据 深度或模板格式 是有效的图像复制源/目标。
• texture 与 copySize 兼容。

示例

commandEncoder.copyTextureToTexture(
  {
    texture: sourceTexture,
  },
  {
    texture: destinationTexture,
  },
  {
    width: 16,
    height: 16,
    depthOrArrayLayers: 2,
  },
);

规范

浏览器兼容性

另见

• WebGPU API