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