GPUDevice: createTexture() 方法

语法

createTexture(descriptor)

参数

描述符（descriptor）

包含以下属性的对象：

dimension 可选

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

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

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

格式（format）

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

备注

• 要创建 depth32float-stencil8 格式的 GPUTexture，需要启用 depth32float-stencil8 功能。
• 要创建二维（dimension: "2d"）BC 压缩的 GPUTexture，需要启用 texture-compression-bc 功能：bc1-rgba-unorm、bc1-rgba-unorm-srgb、bc2-rgba-unorm、bc2-rgba-unorm-srgb、bc3-rgba-unorm、bc3-rgba-unorm-srgb、bc4-r-unorm、bc4-r-snorm、bc5-rg-unorm、bc5-rg-snorm、bc6h-rgb-ufloat、bc6h-rgb-float、bc7-rgba-unorm 和 bc7-rgba-unorm-srgb 格式。
• 要创建三维 BC 压缩的 GPUTexture，需要启用 texture-compression-bc 和 texture-compression-bc-sliced-3d 功能（与上一个项目符号中指定的 format 值相同，但 dimension 设置为 3d）。
• 要创建二维（dimension: "2d"）ASTC 压缩的 GPUTexture，需要启用 texture-compression-astc 功能：astc-4x4-unorm、astc-4x4-unorm-srgb、astc-5x4-unorm、astc-5x4-unorm-srgb、astc-5x5-unorm、astc-5x5-unorm-srgb、astc-6x5-unorm、astc-6x5-unorm-srgb、astc-6x6-unorm、astc-6x6-unorm-srgb、astc-8x5-unorm、astc-8x5-unorm-srgb、astc-8x6-unorm、astc-8x6-unorm-srgb、astc-8x8-unorm、astc-8x8-unorm-srgb、astc-10x5-unorm、astc-10x5-unorm-srgb、astc-10x6-unorm、astc-10x6-unorm-srgb、astc-10x8-unorm、astc-10x8-unorm-srgb、astc-10x10-unorm、astc-10x10-unorm-srgb、astc-12x10-unorm、astc-12x10-unorm-srgb、astc-12x12-unorm 和 astc-12x12-unorm-srgb 格式。
• 要创建三维 BC 压缩的 GPUTexture，需要启用 texture-compression-astc 和 texture-compression-astc-sliced-3d 功能（与上一个项目符号中指定的 format 值相同，但 dimension 设置为 3d）。
• 要创建二维 ETC2 压缩的 GPUTexture，需要启用 texture-compression-etc2 功能：etc2-rgb8unorm、etc2-rgb8unorm-srgb、etc2-rgb8a1unorm、etc2-rgb8a1unorm-srgb、etc2-rgba8unorm、etc2-rgba8unorm-srgb、eac-r11unorm、eac-r11snorm、eac-rg11unorm 和 eac-rg11snorm 格式。

label 可选

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

mipLevelCount 可选

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

sampleCount 可选

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

size

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

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

usage

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

请注意，可以通过使用按位 OR 分隔值来指定多个可能的用途，例如：GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT。

备注

• 要为 bgra8unorm-format GPUTexture 指定 STORAGE_BINDING 用途，需要启用 bgra8unorm-storage 功能。
• 要为 rg11b10ufloat-format GPUTexture 指定 RENDER_ATTACHMENT 用途，以及其混合和多重采样，需要启用 rg11b10ufloat-renderable 功能。

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 的宽度值是 texel 块宽度 的倍数。
• size 的高度值是 texel 块高度 的倍数。
• 如果 sampleCount 大于 1：
  • mipLevelCount 等于 1。
  • size 的深度/数组层数的值等于 1。
  • usage 包含 GPUTextureUsage.RENDER_ATTACHMENT 标志。
  • usage 不包含 GPUTextureUsage.STORAGE_BINDING 标志。
  • 指定的格式支持多重采样。
• mipLevelCount 的值小于或等于 最大 mipmap 级别数。
• format 和 viewFormats 中指定的格式彼此兼容。
• 如果 usage 包含 GPUTextureUsage.RENDER_ATTACHMENT 标志：
  • format 是一个可渲染格式（即颜色可渲染格式，或 深度或模板格式）。
  • dimension 设置为 "2d"。
• 如果 usage 包含 GPUTextureUsage.STORAGE_BINDING 标志：
  • 指定的 format 包含 STORAGE_BINDING 功能（有关参考，请参阅 Plain color formats 表）。

示例

在 WebGPU 示例 Textured Cube sample 中，通过以下步骤创建用于立方体面的纹理：

• 将图像加载到 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