GPUDevice: createTexture()-Methode

descriptor

Ein Objekt, das die folgenden Eigenschaften enthält:

dimension Optional

Ein Aufzählungswert, der die Dimensionsebene der Textur angibt. Mögliche Werte sind:

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

dimension hat den Standardwert "2d", wenn der Wert weggelassen wird.

format

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

Hinweis:

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

label Optional

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

mipLevelCount Optional

Eine Zahl, die die Anzahl der Mip-Ebenen angibt, die die Textur enthalten wird. Wenn weggelassen, beträgt dieser Standardwert 1.

sampleCount Optional

Eine Zahl, die die Anzahl der Proben der Textur angibt. Um gültig zu sein, muss der Wert 1 oder 4 sein. Wenn weggelassen, beträgt dieser Standardwert 1. Ein höherer Wert als 1 bedeutet eine mehrfach abgetastete Textur.

size

Ein Objekt oder Array, das die Breite, Höhe und Tiefe/Array-Ebenenanzahl der Textur angibt. Der Wert für die Breite muss immer angegeben werden, während die Werte für die Höhe und die Tiefe/Array-Ebenenanzahl optional sind und standardmäßig 1 betragen, wenn sie weggelassen werden.

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

usage

Die bitweisen Flags, die die zulässigen Verwendungen für die GPUTexture darstellen. Die möglichen Werte befinden sich in der GPUTexture.usage-Wert-Tabelle.

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

Hinweis:

• Das bgra8unorm-storage-Feature muss aktiviert werden, um die STORAGE_BINDING-Verwendung für eine bgra8unorm-format-GPUTexture anzugeben.
• Das rg11b10ufloat-renderable-Feature muss aktiviert werden, um die RENDER_ATTACHMENT-Verwendung für eine rg11b10ufloat-format-GPUTexture anzugeben, sowie deren Blending und Multisampling.

viewFormats Optional

Ein Array von Aufzählungswerten, das andere Texturformate angibt, die beim Aufruf von GPUTexture.createView() auf dieser Textur zulässig sind, zusätzlich zu dem in ihrem format-Wert angegebenen Texturformat.

Eine GPUTexture-Objektinstanz.

Die folgenden Kriterien müssen beim Aufruf von createTexture() erfüllt sein, andernfalls wird ein GPUValidationError erzeugt und ein ungültiges GPUTexture-Objekt zurückgegeben:

• Eine gültige usage wird angegeben.
• Die in size (Breite, Höhe oder Tiefe/Array-Ebenenanzahl) angegebenen Werte sind größer als 0.
• mipLevelCount ist größer als 0.
• sampleCount ist gleich 1 oder 4.
• Wenn dimension auf "1d" eingestellt ist:
  • Der size-Breitwert ist kleiner oder gleich dem maxTextureDimension1D-Limit des GPUDevice.
  • Die size-Höhe und Tiefe/Array-Ebenenanzahl-Werte sind gleich 1.
  • Der sampleCount ist gleich 1.
  • Das format ist nicht gleich einem komprimierten Format oder einem depth-or-stencil format.
• Wenn dimension auf "2d" eingestellt ist:
  • Die size-Breiten- und Höhenwerte sind kleiner oder gleich dem maxTextureDimension2D-Limit des GPUDevice.
  • Der size-Tiefe/Array-Ebenenanzahl-Wert ist kleiner oder gleich dem maxTextureArrayLayers-Limit des GPUDevice.
• Wenn dimension auf "3d" eingestellt ist:
  • Die size-Breite, -Höhe und -Tiefe/Array-Ebenenanzahl-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 einem depth-or-stencil format.
• Der size-Breitwert 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-Ebenenanzahl-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 Multisampling.
• Der mipLevelCount-Wert ist kleiner oder gleich der maximalen Mip-Ebenenanzahl.
• 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 Farbrenderbares Format oder ein depth-or-stencil format).
  • dimension ist auf "2d" eingestellt.
• Wenn usage das GPUTextureUsage.STORAGE_BINDING-Flag enthält:
  • Das angegebene format enthält die STORAGE_BINDING-Fähigkeit (siehe die Tabelle einfache Farbformate als Referenz).

Im WebGPU-Beispiel Texturierte Würfel-Beispiel wird eine Textur zum Verwenden auf den Flächen eines Würfels erstellt durch:

• Laden des Bildes in ein HTMLImageElement und Erstellen eines Bild-Bitmaps mithilfe von createImageBitmap().
• Erstellen einer neuen Textur mit createTexture().
• Kopieren des Bild-Bitmaps 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