GPUQueue: writeTexture() 方法

语法

writeTexture(destination, data, dataLayout, size)

参数

destination

一个定义要写入数据源的纹理子资源和起点的对象，可以包含以下属性：

aspect 可选

一个枚举值，定义要向纹理写入数据的哪个方面。可能的值有：

"all"

将写入纹理格式的所有可用方面，这可能意味着颜色、深度和模板中的全部或任何一个，具体取决于您处理的格式类型。

"depth-only"

仅将数据写入 深度或模板格式 的深度方面。

"stencil-only"

仅将数据写入深度或模板格式的模板方面。

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

mipLevel 可选

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

origin 可选

一个对象或数组，指定复制的起点——要将数据写入的纹理区域的最小角。与 size 一起，这定义了要复制区域的完整范围。如果省略了 origin 中的任何一个（x、y、z），则它们默认为 0。

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

texture

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

data

一个对象，表示要写入 GPUTexture 的数据源。它可以是 ArrayBuffer、TypedArray 或 DataView。

dataLayout

一个对象，定义 data 中包含的内容的布局。可能的值有：

offset 可选

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

bytesPerRow 可选

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

rowsPerImage 可选

单个纹理图像的块行数。bytesPerRow × rowsPerImage 将给出每个完整图像开始之间的字节步长。如果要复制多个图像，则此项是必需的。

size

一个对象或数组，指定复制的范围——要将数据写入的纹理区域的最远角。与 destination.origin 一起，这定义了要复制区域的完整范围。有关对象/数组结构的示例，请参见 destination.origin。

返回值

无 (Undefined)。

验证

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

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

示例

在 高效渲染 glTF 模型 中，定义了一个用于创建纯色纹理的函数。

function createSolidColorTexture(r, g, b, a) {
  const data = new Uint8Array([r * 255, g * 255, b * 255, a * 255]);
  const texture = device.createTexture({
    size: { width: 1, height: 1 },
    format: "rgba8unorm",
    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
  });
  device.queue.writeTexture({ texture }, data, {}, { width: 1, height: 1 });
  return texture;
}

这可用于为材质库定义标准纹理。

const opaqueWhiteTexture = createSolidColorTexture(1, 1, 1, 1);
const transparentBlackTexture = createSolidColorTexture(0, 0, 0, 0);
const defaultNormalTexture = createSolidColorTexture(0.5, 0.5, 1, 1);

规范

浏览器兼容性

另见

• WebGPU API