GPUDevice: createTexture() 方法

descriptor

包含以下属性的对象

dimension 可选

一个枚举值，指示纹理的维度级别。可能的值为

• "1d"：纹理是一维的。
• "2d"：纹理是二维的或二维层的数组。
• "3d"：纹理是三维的。

如果省略 dimension 的值，则默认为 "2d"。

format

一个枚举值，指定纹理的格式。有关所有可能的值，请参阅规范的 纹理格式 部分。

label 可选

一个字符串，提供一个标签，可用于标识对象，例如在 GPUError 消息或控制台警告中。

mipLevelCount 可选

一个数字，指定纹理将包含的 mip 级别数。如果省略，则默认为 1。

sampleCount 可选

一个数字，指定纹理的样本数。要有效，该值必须为 1 或 4。如果省略，则默认为 1。大于 1 的值表示多样本纹理。

size

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

以下是一个 size 数组示例

js

size: [16, 16, 2];

等效的对象如下所示

js

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

usage

表示 GPUTexture 允许用法的 按位标志。可能的值在 GPUTexture.usage 值表 中。

请注意，可以通过用管道符号分隔值来指定多个可能的用法，例如

js

usage: GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT;

viewFormats 可选

一个枚举值数组，指定在调用 GPUTexture.createView() 时允许使用的其他 纹理格式，除了在其 format 值中指定的纹理格式之外。

一个 GPUTexture 对象实例。

调用 createTexture() 时必须满足以下条件，否则将生成 GPUValidationError 并返回一个无效的 GPUTexture 对象

• 指定了有效的 usage。
• size 中指定的值（宽度、高度或深度/数组层数）大于 0。
• mipLevelCount 大于 0。
• sampleCount 等于 1 或 4。
• 如果 dimension 设置为 "1d"
  • size 宽度值小于或等于 GPUDevice 的 maxTextureDimension1D 限制。
  • size 高度和深度/数组层数值等于 1。
  • sampleCount 等于 1。
  • format 不等于 压缩格式 或 深度或模板格式。
• 如果 dimension 设置为 "2d"
  • size 宽度和高度值小于或等于 GPUDevice 的 maxTextureDimension2D 限制。
  • size 深度/数组层数值小于或等于 GPUDevice 的 maxTextureArrayLayers 限制。
• 如果 dimension 设置为 "3d"
  • size 宽度、高度和深度/数组层数值小于或等于 GPUDevice 的 maxTextureDimension3D 限制。
  • sampleCount 值等于 1。
  • format 不等于 压缩格式 或 深度或模板格式。
• size 宽度值是 纹素块宽度 的倍数。
• size 高度值是 纹素块高度 的倍数。
• 如果 sampleCount 大于 1
  • mipLevelCount 等于 1。
  • size 深度/数组层数值等于 1。
  • usage 包含 GPUTextureUsage.RENDER_ATTACHMENT 标志。
  • usage 不包含 GPUTextureUsage.STORAGE_BINDING 标志。
  • 指定的格式支持多样本。
• mipLevelCount 值小于或等于 最大 mip 级别数。
• format 和 viewFormats 中指定的格式彼此 兼容。
• 如果 usage 包含 GPUTextureUsage.RENDER_ATTACHMENT 标志
  • format 是可渲染格式（即颜色可渲染格式或 深度或模板格式）。
  • dimension 设置为 "2d"。
• 如果 usage 包含 GPUTextureUsage.STORAGE_BINDING 标志
  • 指定的 format 包含 STORAGE_BINDING 功能（请参阅 纯色格式 表以供参考）。

在 WebGPU 示例 纹理立方体示例 中，用于立方体面的纹理通过以下方式创建：

• 将图像加载到 HTMLImageElement 中，并使用 createImageBitmap() 创建图像位图。
• 使用 createTexture() 创建新的纹理。
• 使用 GPUQueue.copyExternalImageToTexture() 将图像位图复制到纹理中。

//...

let cubeTexture;

{
  const img = document.createElement("img");
  img.src = new URL(
    "../../../assets/img/Di-3d.png",
    import.meta.url,
  ).toString();
  await img.decode();
  const imageBitmap = await createImageBitmap(img);

  cubeTexture = device.createTexture({
    size: [imageBitmap.width, imageBitmap.height, 1],
    format: "rgba8unorm",
    usage:
      GPUTextureUsage.TEXTURE_BINDING |
      GPUTextureUsage.COPY_DST |
      GPUTextureUsage.RENDER_ATTACHMENT,
  });
  device.queue.copyExternalImageToTexture(
    { source: imageBitmap },
    { texture: cubeTexture },
    [imageBitmap.width, imageBitmap.height],
  );
}

//...

• WebGPU API