GPUTexture: Methode createView()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die createView()-Methode der GPUTexture-Schnittstelle erstellt eine GPUTextureView, die eine spezifische Ansicht der GPUTexture darstellt.

Syntax

js
createView()
createView(descriptor)

Parameter

descriptor Optional

Ein Objekt, das die folgenden Eigenschaften enthält:

arrayLayerCount Optional

Eine Zahl, die definiert, wie viele Array-Schichten für die Ansicht zugänglich sind, beginnend mit dem Wert baseArrayLayer.

Wenn arrayLayerCount weggelassen wird, erhält es folgenden Wert:

  • Wenn dimension "1d", "2d" oder "3d" ist, ist arrayLayerCount 1.
  • Wenn dimension "cube" ist, ist arrayLayerCount 6.
  • Wenn dimension "2d-array" oder "cube-array" ist, ist arrayLayerCount GPUTexture.depthOrArrayLayers - baseArrayLayer.
aspect Optional

Ein enumerierter Wert, der angibt, welche Aspekte der Textur für die Texturansicht zugänglich sind. Mögliche Werte sind:

"all"

Alle verfügbaren Aspekte des Texturformats sind für die Ansicht zugänglich, was je nach Formatfarbe, Tiefe und Schablone bedeuten kann.

"depth-only"

Nur der Tiefenaspekt eines depth-or-stencil format ist für die Ansicht zugänglich.

"stencil-only"

Nur der Schablonaspekt eines Tiefen-oder-Schablonenformats ist für die Ansicht zugänglich.

Wenn weggelassen, nimmt aspect den Wert "all" an.

baseArrayLayer Optional

Eine Zahl, die den Index der ersten für die Ansicht zugänglichen Arrayschicht definiert. Wenn weggelassen, nimmt baseArrayLayer den Wert 0 an.

baseMipLevel Optional

Eine Zahl, die die erste (detaillierteste) Mipmap-Ebene angibt, die für die Ansicht zugänglich ist. Wenn weggelassen, nimmt baseMipLevel den Wert 0 an.

dimension Optional

Ein enumerierter Wert, der das Format bestimmt, in dem die Textur angezeigt wird. Mögliche Werte sind:

  • "1d": Die Textur wird als eindimensionales Bild angezeigt.
  • "2d": Die Textur wird als einzelnes zweidimensionales Bild angezeigt.
  • "2d-array": Die Textur wird als Array von zweidimensionalen Bildern angezeigt.
  • "cube": Die Textur wird als Würfelkarte angezeigt. Die Ansicht hat 6 Arrayschichten, die den [+X, -X, +Y, -Y, +Z, -Z]-Flächen des Würfels entsprechen. Die Abtastung erfolgt nahtlos über die Flächen der Würfelkarte.
  • "cube-array": Die Textur wird als gepackte Anordnung von N Würfelkarten angezeigt, jede mit 6 Arrayschichten, entsprechend den [+X, -X, +Y, -Y, +Z, -Z]-Flächen des Würfels. Die Abtastung erfolgt nahtlos über die Flächen der Würfelkarten.
  • "3d": Die Textur wird als dreidimensionales Bild angezeigt.

Wenn dimension weggelassen wird, erhält es folgenden Wert:

format Optional

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

Wenn format weggelassen wird, erhält es folgenden Wert:

label Optional

Ein Zeichenfolge-Label, das zur Identifizierung des Objekts verwendet werden kann, beispielsweise in GPUError-Meldungen oder Konsolenwarnungen.

mipLevelCount Optional

Eine Zahl, die angibt, wie viele Mipmap-Ebenen für die Ansicht zugänglich sind, beginnend mit dem Wert baseMipLevel.

Wenn mipLevelCount weggelassen wird, erhält es den Wert GPUTexture.mipLevelCount - baseMipLevel.

usage Optional

Ein Satz von Bitweise-Flags, die eine Teilmenge der Nutzungsflags der Quellentextur (verfügbar in der GPUTexture.usage-Eigenschaft) darstellen, die mit dem gewählten Ansichtsformat kompatibel sind. Dies kann verwendet werden, um die zulässige Nutzung der Ansicht einzuschränken, wenn das Ansichtsformat mit bestimmten Nutzungen unvereinbar ist. Die verfügbaren Nutzungsflags sind in der GPUTexture.usage-Wertetabelle aufgelistet.

Der Standardwert ist 0, was die vollständige Menge der Nutzungsflags der Quellentextur darstellt. Wenn das format der Ansicht nicht alle Nutzungen der Textur unterstützt, schlägt der Standard fehl, und die Nutzung der Ansicht muss explizit angegeben werden.

Rückgabewert

Ein GPUTextureView-Objektinstanz.

Validierung

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

Beispiele

Typische Verwendung von createView()

Im WebGPU-Beispiel Cubemap-Demo sehen Sie mehrere Beispiele, wie createView() verwendet wird, sowohl um eine resource-Ansicht für einen GPUDevice.createBindGroup()-Aufruf zu erstellen, als auch um eine view im depthStencilAttachment-Objekt eines GPUCommandEncoder.beginRenderPass()-Descriptors bereitzustellen.

js
const uniformBindGroup = device.createBindGroup({
  layout: pipeline.getBindGroupLayout(0),
  entries: [
    {
      binding: 0,
      resource: {
        buffer: uniformBuffer,
        offset: 0,
        size: uniformBufferSize,
      },
    },
    {
      binding: 1,
      resource: sampler,
    },
    {
      binding: 2,
      resource: cubemapTexture.createView({
        dimension: "cube",
      }),
    },
  ],
});

const renderPassDescriptor: GPURenderPassDescriptor = {
  colorAttachments: [
    {
      view: undefined, // Assigned later
      loadOp: "clear",
      storeOp: "store",
    },
  ],
  depthStencilAttachment: {
    view: depthTexture.createView(),

    depthClearValue: 1.0,
    depthLoadOp: "clear",
    depthStoreOp: "store",
  },
};

// …

const commandEncoder = device.createCommandEncoder();
const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);

// …

createView() mit Nutzungseinschränkung

In diesem Snippet erstellen wir eine Textur und dann eine Ansicht, deren Nutzung über die usage-Eigenschaft eingeschränkt wird.

js
const texture = myDevice.createTexture({
  size: [4, 4],
  format: "rgba8unorm",
  usage:
    GPUTextureUsage.RENDER_ATTACHMENT |
    GPUTextureUsage.TEXTURE_BINDING |
    GPUTextureUsage.STORAGE_BINDING,
  viewFormats: ["rgba8unorm-srgb"],
});

const view = texture.createView({
  format: "rgba8unorm-srgb",
  usage: GPUTextureUsage.RENDER_ATTACHMENT, // Restrict allowed usage
});

Spezifikationen

Specification
WebGPU
# dom-gputexture-createview

Browser-Kompatibilität

Siehe auch