GPUCommandEncoder: copyBufferToTexture() 方法

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

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

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

语法

copyBufferToTexture(source, destination, copySize)

参数

source

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

buffer: 要从中复制的 GPUBuffer。
offset 可选: 从data开头到要复制的图像数据的起始位置的偏移量（以字节为单位）。如果省略，则offset默认为0。
bytesPerRow 可选: 表示每个块行（即完整纹理块的行）的起始位置与其后续块行之间的步长（以字节为单位）的数字。如果有多个块行（即复制高度或深度大于一个块），则需要此参数。
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。

以下是一个示例copySize数组

[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 的纹理块宽度的倍数。
origin.y是 GPUTexture.format 的纹理块高度的倍数。
如果 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 # dom-gpucommandencoder-copybuffertotexture

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅

WebGPU API