GPUCommandEncoder: copyTextureToBuffer() 方法

实验性： 这是一个实验性技术
在生产环境中使用此功能前，请仔细查看浏览器兼容性表格。

安全上下文： 此功能仅在安全上下文（HTTPS）中可用，并且在部分或所有支持的浏览器中可用。

GPUCommandEncoder 接口的 **copyTextureToBuffer()** 方法会编码一个命令，用于将数据从 GPUTexture 复制到 GPUBuffer。

语法

copyTextureToBuffer(source, destination, copySize)

参数

源

一个对象，定义了要从中复制数据的纹理。结合 copySize，定义了源纹理子资源的区域。source 可以包含以下属性：

aspect 可选

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

"all": 将复制纹理格式的所有可用方面，这可能意味着复制颜色、深度和模板的所有或任何方面，具体取决于您正在处理的格式类型。
"depth-only": 仅复制深度或模板格式的深度方面。
"stencil-only": 仅复制深度或模板格式的模板方面。

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

mipLevel 可选

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

origin 可选

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

以下是一个示例数组

[0, 0, 0];

等效的对象如下所示

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

纹理

一个 GPUTexture 对象，表示要从中复制数据的纹理。

目标

一个对象，定义了要写入的缓冲区，以及写入缓冲区的数据布局。结合 copySize，定义了目标缓冲区的区域。source 可以包含以下属性：

缓冲区: 要写入的 GPUBuffer。
offset 可选: 从 data 的开头到开始写入复制数据的起始位置的偏移量（以字节为单位）。如果省略，则 offset 默认为 0。
bytesPerRow 可选: 一个表示每个块行（即完整纹理块的行）的开头与其后续块行之间的跨度（以字节为单位）的数字。如果有多个块行（即复制高度或深度大于一个块），则需要此参数。
rowsPerImage 可选: 数据内每个图像的块行数。bytesPerRow × rowsPerImage 将为您提供每个完整图像的开头之间的跨度（以字节为单位）。如果要复制多个图像，则需要此参数。

copySize

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

以下是一个 copySize 数组示例

[16, 16, 2];

等效的对象如下所示

{
  width: 16,
  height: 16,
  depthOrArrayLayers: 2
}

返回值

无 (Undefined).

验证

调用 **copyTextureToBuffer()** 时必须满足以下条件，否则将生成 GPUValidationError，并且 GPUCommandEncoder 将变为无效。

对于 source

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

对于 destination

destination.bytesPerRow 是 256 的倍数。
destination.buffer 的 GPUBuffer.usage 包含 GPUBufferUsage.COPY_DST 标志。

示例

commandEncoder.copyTextureToBuffer(
  {
    texture: sourceTexture,
  },
  {
    buffer: destinationBuffer,
  },
  {
    width: 16,
    height: 16,
    depthOrArrayLayers: 2,
  },
);

规范

规范
WebGPU # dom-gpucommandencoder-copytexturetobuffer

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅

WebGPU API