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 aus zweidimensionalen Schichten.
• "3d": Die Textur ist dreidimensional.

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

format

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

Hinweis:

• Das depth32float-stencil8- Feature muss aktiviert sein, um depth32float-stencil8-Format-GPUTextures zu erstellen.
• Das texture-compression-bc-Feature muss aktiviert sein, um zweidimensionale 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.
• Das texture-compression-astc-Feature muss aktiviert sein, um zweidimensionale 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, und astc-12x12-unorm``astc-12x12-unorm-srgb-Formate.
• Das texture-compression-etc2-Feature 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.

label Optional

Ein String, der eine Bezeichnung angibt, mit der das Objekt z. B. in GPUError-Meldungen oder Konsolenwarnungen identifiziert werden kann.

mipLevelCount Optional

Eine Zahl, die angibt, wie viele Mip-Ebenen die Textur enthalten wird. Wenn dieser Wert weggelassen wird, ist der Standardwert 1.

sampleCount Optional

Eine Zahl, die die Anzahl der Abtastungen der Textur angibt. Um gültig zu sein, muss der Wert 1 oder 4 sein. Wird er weggelassen, ist der Standardwert 1. Ein Wert größer als 1 gibt eine multi-abgetastete Textur an.

size

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

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

usage

Die bitweisen Flags, die die erlaubten Nutzungen für das GPUTexture darstellen. Die möglichen Werte befinden sich in der GPUTexture.usage-Wertetabelle.

Beachten Sie, dass mehrere mögliche Nutzungen angegeben werden können, indem die Werte mit bitweise ODER getrennt werden, zum Beispiel: GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT.

Hinweis:

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

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 Texturformat, das in seinem format-Wert angegeben ist.

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:

• Es wird ein gültiger usage angegeben.
• Die in size (Breite, Höhe oder Tiefe/Array-Schichtenanzahl) angegebenen Werte 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-Schichtenanzahl-Werte 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-Schichtenanzahl-Wert ist kleiner oder gleich dem maxTextureArrayLayers- Limit des GPUDevice.
• Wenn dimension auf "3d" gesetzt ist:
  • Die size-Breiten-, Höhen- und Tiefen-/Array-Schichtenanzahl-Werte 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-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-Tiefen-/Array-Schichtenanzahl-Wert 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 (d.h. ein farblich renderbares Format oder ein Tiefen-oder-Stencil-Format).
  • dimension ist auf "2d" gesetzt.
• Wenn usage das GPUTextureUsage.STORAGE_BINDING-Flag enthält:
  • Das angegebene format enthält die STORAGE_BINDING-Fähigkeit (siehe die einfachen Farbformate-Tabelle zur Referenz).

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

• Das Bild in ein HTMLImageElement geladen und ein Bild-Bitmap mit createImageBitmap() erstellt wird.
• Eine neue Textur mit createTexture() erstellt wird.
• Das Bild-Bitmap mit GPUQueue.copyExternalImageToTexture() in die Textur kopiert wird.

//...

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