GPUCommandEncoder: copyBufferToTexture() 方法

语法

copyBufferToTexture(source, destination, copySize)

参数

source

一个定义要从中复制数据的缓冲区，以及缓冲区中要复制到纹理的数据的布局的对象。结合 copySize，它定义了源缓冲区的区域。source 可以包含以下属性：

buffer

要从中复制数据的 GPUBuffer。

offset 可选

从 data 开始到要复制的图像数据开始处的字节偏移量。如果省略，offset 默认为 0。

bytesPerRow 可选

一个数字，表示每个块行（即，一个完整的 texel 块行）和后续块行之间的字节步长。如果存在多个块行（即，复制高度或深度大于一个块），则此项是必需的。

rowsPerImage 可选

每张图像中的块行数。bytesPerRow × rowsPerImage 将给出每张完整图像开始之间的字节步幅。如果要复制多张图像，则需要此项。

destination

一个定义要将数据写入的纹理的对象。结合 copySize，它定义了目标纹理子资源区域。destination 可以包含以下属性：

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 对象。

copySize

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

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

返回值

无 (Undefined)。

验证

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

对于 source：

• source.bytesPerRow 是 256 的倍数。
• source.buffer 的 GPUBuffer.usage 包含 GPUBufferUsage.COPY_SRC 标志。

对于 destination：

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

示例

commandEncoder.copyBufferToTexture(
  {
    buffer: sourceBuffer,
  },
  {
    texture: destinationTexture,
  },
  {
    width: 16,
    height: 16,
    depthOrArrayLayers: 2,
  },
);

规范

浏览器兼容性

另见

• WebGPU API