GPUDevice: Methode createTexture()

descriptor

Ein Objekt, das die folgenden Eigenschaften enthält:

dimension Optional

Ein enumerierter Wert, der die Dimensionsebene der Textur angibt. Mögliche Werte sind:

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

dimension ist standardmäßig auf "2d" gesetzt, wenn der Wert weggelassen wird.

format

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

Hinweis:

• Das depth32float-stencil8- Merkmal muss aktiviert sein, um GPUTextures im depth32float-stencil8-Format zu erstellen.
• Das Merkmal texture-compression-bc muss aktiviert sein, um zweidimensionale BC-komprimierte GPUTextures zu erstellen: Formate wie bc1-rgba-unorm, bc1-rgba-unorm-srgb, bc2-rgba-unorm, etc.
• Das Merkmal texture-compression-astc muss aktiviert sein, um zweidimensionale ASTC-komprimierte GPUTextures zu erstellen: Formate wie astc-4x4-unorm, astc-4x4-unorm-srgb, etc.
• Das Merkmal texture-compression-etc2 muss aktiviert sein, um zweidimensionale ETC2-komprimierte GPUTextures zu erstellen: Formate wie etc2-rgb8unorm, etc2-rgb8unorm-srgb, etc.

label Optional

Ein String, der ein Label bereitstellt, das zur Identifizierung des Objekts, zum Beispiel in GPUError-Meldungen oder Konsolenwarnungen, verwendet werden kann.

mipLevelCount Optional

Eine Zahl, die die Anzahl der Mip-Ebenen angibt, die die Textur enthalten wird. Wenn weggelassen, ist dieser Wert standardmäßig 1.

sampleCount Optional

Eine Zahl, die die Anzahl der Samples der Textur angibt. Um gültig zu sein, muss der Wert 1 oder 4 sein. Wenn weggelassen, ist dieser Wert standardmäßig 1. Ein Wert höher als 1 gibt eine Multi-Sample-Textur an.

size

Ein Objekt oder Array, das die Breite, Höhe und die Tiefe/Array-Schichtebene der Textur angibt. Der Breitenwert muss immer angegeben werden, während die Höhen- und Tiefen/Array-Schichtwerte optional sind und standardmäßig 1 sind, wenn sie weggelassen werden.

Beispielsweise kann ein Array wie [16, 16, 2] oder dessen äquivalentes Objekt { width: 16, height: 16, depthOrArrayLayers: 2 } übergeben werden.

usage

Die Bit-Flags, die die erlaubten Verwendungen für die GPUTexture repräsentieren. Die möglichen Werte finden sich in der GPUTexture.usage-Wertetabelle.

Beachten Sie, dass mehrere mögliche Verwendungen angegeben werden können, indem Werte mit Bitwise OR getrennt werden, zum Beispiel: GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT.

Hinweis:

• Das bgra8unorm-storage- Merkmal muss aktiviert sein, um STORAGE_BINDING-Verwendung für eine bgra8unorm- format GPUTexture anzugeben.
• Das rg11b10ufloat-renderable- Merkmal muss aktiviert sein, um RENDER_ATTACHMENT-Verwendung für eine rg11b10ufloat- format GPUTexture sowie dessen Blending und Multisampling anzugeben.

viewFormats Optional

Ein Array von enumerierten Werten, die andere Texturformate angeben, die beim Aufrufen von GPUTexture.createView() auf dieser Textur zulässig sind, zusätzlich zu dem im format-Wert angegebenen Texturformat.

Eine Instanz des GPUTexture-Objekts.

Die folgenden Kriterien müssen erfüllt sein, wenn createTexture() aufgerufen wird, andernfalls wird ein GPUValidationError generiert und ein ungültiges GPUTexture-Objekt zurückgegeben:

• Ein gültiges usage ist angegeben.
• Die in size angegebenen Werte (Breite, Höhe oder Tiefe/Array-Schichtanzahl) 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 dem maxTextureDimension1D- Limit des GPUDevice.
  • Die size-Höhen- und Tiefen/Array-Schichtwerte 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 dem maxTextureDimension2D- Limit des GPUDevice.
  • Der size-Tiefen/Array-Schichtwert ist kleiner oder gleich dem maxTextureArrayLayers- Limit des GPUDevice.
• Wenn dimension auf "3d" gesetzt ist:
  • Die size-Breite, -Höhe und -Tiefen/Array-Schichtwerte sind kleiner oder gleich dem maxTextureDimension3D- Limit des GPUDevice.
  • 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-Blockbreite.
• Der size-Höhenwert ist ein Vielfaches der Texel-Blockhöhe.
• Wenn sampleCount größer als 1 ist:
  • mipLevelCount ist gleich 1.
  • Der size-Tiefen/Array-Schichtwert 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 Multi-Sampling.
• Der mipLevelCount-Wert ist kleiner oder gleich der maximalen Mip-Ebenenzahl.
• Die in format und viewFormats angegebenen Formate sind kompatibel miteinander.
• Wenn usage das GPUTextureUsage.RENDER_ATTACHMENT-Flag enthält:
  • format ist ein renderbares Format (das bedeutet ein farb-rendbares Format oder ein Tiefen- oder Stencil-Format).
  • dimension ist auf "2d" gesetzt.
• Wenn usage das GPUTextureUsage.STORAGE_BINDING-Flag enthält:
  • Das angegebene format hat die STORAGE_BINDING-Fähigkeit (siehe die Tabelle der uniformen Farbformate zur Referenz).

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

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

// …

• Die WebGPU API