GPUDevice: createTexture() Methode

Syntax

createTexture(descriptor)

Parameter

descriptor

Ein Objekt mit den folgenden Eigenschaften:

dimension Optional

Ein enumerierter Wert, der das Dimensionsniveau der Textur angibt. Mögliche Werte sind:

• "1d": Die Textur ist eindimensional.
• "2d": Die Textur ist zweidimensional oder ein Array aus zweidimensionalen Schichten.
• "3d": Die Textur ist dreidimensional.

dimension hat standardmäßig den Wert "2d", wenn der Wert ausgelassen wird.

format

Ein enumerierter Wert, der das Format der Textur angibt. Siehe den Abschnitt Texturformate der Spezifikation für alle möglichen Werte.

Hinweis:

• Die depth32float-stencil8 Funktion muss aktiviert sein, um depth32float-stencil8-Format-GPUTextures zu erstellen.
• Die texture-compression-bc Funktion muss aktiviert sein, um zweidimensionale (dimension: "2d") BC-komprimierte GPUTextures zu erstellen: 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 und bc7-rgba-unorm-srgb Formate.
• Die texture-compression-bc und texture-compression-bc-sliced-3d Funktionen müssen aktiviert sein, um dreidimensionale BC-komprimierte GPUTextures zu erstellen (die gleichen format-Werte wie im vorherigen Punkt, aber mit dimension auf 3d gesetzt).
• Die texture-compression-astc Funktion muss aktiviert sein, um zweidimensionale (dimension: "2d") ASTC-komprimierte GPUTextures zu erstellen: 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 und astc-12x12-unorm-srgb Formate.
• Die texture-compression-astc und texture-compression-astc-sliced-3d Funktionen müssen aktiviert sein, um dreidimensionale BC-komprimierte GPUTextures zu erstellen (die gleichen format-Werte wie im vorherigen Punkt, aber mit dimension auf 3d gesetzt).
• Die texture-compression-etc2 Funktion muss aktiviert sein, um zweidimensionale ETC2-komprimierte GPUTextures zu erstellen: etc2-rgb8unorm, etc2-rgb8unorm-srgb, etc2-rgb8a1unorm, etc2-rgb8a1unorm-srgb, etc2-rgba8unorm, etc2-rgba8unorm-srgb, eac-r11unorm, eac-r11snorm, eac-rg11unorm und eac-rg11snorm Formate.
• Siehe den Abschnitt Tier 1 und Tier 2 Texturformate für weitere Informationen über diese Texturformat-Sets und die Anforderungen, sie zu erstellen.

label Optional

Ein String, der ein Etikett bereitstellt, das verwendet werden kann, um das Objekt beispielsweise in GPUError-Meldungen oder Konsolenwarnungen zu identifizieren.

mipLevelCount Optional

Eine Zahl, die die Anzahl der Mip-Ebenen angibt, die die Textur enthalten wird. Wenn ausgelassen, ist der Standardwert 1.

sampleCount Optional

Eine Zahl, die die Sampling-Anzahl der Textur angibt. Um gültig zu sein, muss der Wert 1 oder 4 sein. Wenn ausgelassen, ist der Standardwert 1. Ein höherer Wert als 1 zeigt eine multisample Textur an.

size

Ein Objekt oder Array, das die Breite, Höhe und Tiefe/Array-Schichtebene der Textur angibt. Der Wert für die Breite muss immer angegeben werden, während die Höhe und die Tiefe/Array-Schichtebene optional sind und auf 1 voreingestellt sind, wenn sie ausgelassen werden.

Zum Beispiel, Sie können ein Array wie [16, 16, 2] oder sein gleichwertiges Objekt { width: 16, height: 16, depthOrArrayLayers: 2 } übergeben.

usage

Die Bitmasken, die die erlaubten Nutzungen für die GPUTexture darstellen. Die möglichen Werte sind in der GPUTexture.usage Werttabelle zu finden.

Beachten Sie, dass mehrere mögliche Nutzungen angegeben werden können, indem Werte mit bitwise OR getrennt werden, z.B.: GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT.

Hinweis:

• Die bgra8unorm-storage Funktion muss aktiviert sein, um STORAGE_BINDING Nutzung für ein bgra8unorm-format GPUTexture anzugeben.
• Die rg11b10ufloat-renderable Funktion muss aktiviert sein, um RENDER_ATTACHMENT Nutzung für ein rg11b10ufloat-format GPUTexture anzugeben, ebenso wie sein Blending und Multisampling.

viewFormats Optional

Ein Array von enumerierten Werten, das andere erlaubte Texturformate angibt, wenn GPUTexture.createView() auf dieser Textur aufgerufen wird, zusätzlich zu dem im format-Wert angegebenen Texturformat.

Rückgabewert

Eine GPUTexture Objektinstanz.

Validierung

Die folgenden Kriterien müssen bei der Aufruf von createTexture() erfüllt sein, ansonsten wird ein GPUValidationError ausgelöst und ein ungültiges GPUTexture Objekt zurückgegeben:

• Eine gültige usage ist angegeben.
• Die in size angegebenen Werte (Breite, Höhe oder Tiefe/Array-Schichtebene) sind größer als 0.
• mipLevelCount ist größer als 0.
• sampleCount ist gleich 1 oder 4.
• Wenn dimension auf "1d" gesetzt ist:
  • Der size Breitenwert ist kleiner oder gleich der GPUDevice maxTextureDimension1D Grenze.
  • Die size Höhen- und Tiefe/Array-Schichtebenenwerte sind gleich 1.
  • Der sampleCount ist gleich 1.
  • Das format ist nicht gleich einem komprimierten Format oder Tiefen- oder Stencil-Format.
• Wenn dimension auf "2d" gesetzt ist:
  • Die size Breiten- und Höhenwerte sind kleiner oder gleich der GPUDevice maxTextureDimension2D Grenze.
  • Der size Tiefe/Array-Schichtebenenwert ist kleiner oder gleich der GPUDevice maxTextureArrayLayers Grenze.
• Wenn dimension auf "3d" gesetzt ist:
  • Die size Breite, Höhe und Tiefe/Array-Schichtebenenwerte sind kleiner oder gleich der GPUDevice maxTextureDimension3D Grenze.
  • Der sampleCount Wert ist gleich 1.
  • Das format ist nicht gleich einem komprimierten Format oder Tiefen- oder Stencil-Format.
• Der size Breitenwert ist ein Vielfaches der Texel-Block-Breite.
• Der size Höhenwert ist ein Vielfaches der Texel-Block-Höhe.
• Wenn sampleCount größer als 1 ist:
  • mipLevelCount ist gleich 1.
  • Der size Tiefe/Array-Schichtebenenwert ist gleich 1.
  • usage enthält das GPUTextureUsage.RENDER_ATTACHMENT Flag.
  • usage enthält nicht das GPUTextureUsage.STORAGE_BINDING Flag.
  • Das angegebene Format unterstützt Multisampling.
• Der mipLevelCount Wert ist kleiner als oder gleich der maximalen Mip-Ebenenzahl.
• Die in format und viewFormats angegebenen Formate sind kompatibel zueinander.
• Wenn usage das GPUTextureUsage.RENDER_ATTACHMENT Flag enthält:
  • format ist ein renderbares Format (ein farbrenderbares Format oder ein Tiefen- oder Stencil-Format).
  • dimension ist auf "2d" gesetzt.
• Wenn usage das GPUTextureUsage.STORAGE_BINDING Flag enthält:
  • Das angegebene format umfasst die STORAGE_BINDING Fähigkeit (siehe die Tabelle der einfachen Farbformate als Referenz).

Tier 1 und Tier 2 Texturformate

Dieser Abschnitt beschreibt die WebGPU Tier 1 und Tier 2 Texturformate.

Tier 1

Die Tier 1 Sammlungen von Texturformaten sind entworfen, um Entwicklern eine Übertragung bestehender Inhalte auf das Web zu ermöglichen, ohne dass diese es neu schreiben müssen, um die niedrigeren Fähigkeiten von WebGPU zu nutzen. Um diesen Satz zu nutzen, aktivieren Sie die texture-formats-tier1 Funktion (siehe GPUSupportedFeatures).

Diese Funktion zu aktivieren, erlaubt:

• Die folgenden formate mit usagen von RENDER_ATTACHMENT (inklusive misch- und multisamplingfähiger Fähigkeiten) und STORAGE_BINDING (mit read-only und write-only access) zu verwenden:
  • r16unorm
  • r16snorm
  • rg16unorm
  • rg16snorm
  • rgba16unorm
  • rgba16snorm
• Die folgenden formate mit der RENDER_ATTACHMENT usage (inklusive misch- und multisamplingfähiger Fähigkeiten) zu verwenden:
  • r8snorm
  • rg8snorm
  • rgba8snorm
• Die folgenden formate mit der STORAGE_BINDING usage (mit read-only und write-only access) zu verwenden:
  • r8unorm
  • r8snorm
  • r8uint
  • r8sint
  • rg8unorm
  • rg8snorm
  • rg8uint
  • rg8sint
  • r16uint
  • r16sint
  • r16float
  • rg16uint
  • rg16sint
  • rg16float
  • rgb10a2uint
  • rgb10a2unorm
  • rg11b10ufloat
• Das Verwenden der folgenden GPUTexture Formate im Ziel-texture von GPUQueue.copyExternalImageToTexture() Aufrufen:
  • r16unorm
  • rg16unorm
  • rgba16unorm

Tier 2

Die Tier 2 Sammlungen von Texturformaten unterstützen Speichertexturformate, die in "Kern"-WebGPU keine Unterstützung haben und für fortgeschrittenen Einsatz benötigt werden. Um diesen Satz zu nutzen, aktivieren Sie die texture-formats-tier2 Funktion (siehe GPUSupportedFeatures).

Diese Funktion zu aktivieren, erlaubt die Verwendung der folgenden formate mit der STORAGE_BINDING usage (mit read-write access):

• r8unorm
• r8uint
• r8sint
• rgba8unorm
• rgba8uint
• rgba8sint
• r16uint
• r16sint
• r16float
• rgba16uint
• rgba16sint
• rgba16float
• rgba32uint
• rgba32sint
• rgba32float

Beispiele

Im WebGPU Beispiel Textured Cube sample wird eine Textur erstellt, die auf den Flächen eines Würfels verwendet wird, durch:

• Laden des Bildes in ein HTMLImageElement und Erstellen eines Bildbitmaps mit createImageBitmap().
• Erstellen einer neuen Textur mit createTexture().
• Kopieren des Bildbitmaps in die Textur mit 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],
  );
}

// …

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Die WebGPU API