GPUTexture: createView() Methode

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 des GPUTexture-Interfaces erstellt ein GPUTextureView, das 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-Ebenen für die Ansicht zugänglich sind, ausgehend von dem Wert baseArrayLayer.

Wenn arrayLayerCount weggelassen wird, erhält es einen Wert wie folgt:

  • 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 Farbe, Tiefe und Schablone bedeuten kann, abhängig von der Art des Formats.

"depth-only"

Nur der Tiefenaspekt eines Tiefen- oder Schablonenformats wird für die Ansicht zugänglich sein.

"stencil-only"

Nur der Schablonen-Aspekt eines Tiefen- oder Schablonenformats wird für die Ansicht zugänglich sein.

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

baseArrayLayer Optional

Eine Zahl, die den Index der ersten Array-Ebene definiert, die für die Ansicht zugänglich ist. Wenn weggelassen, nimmt baseArrayLayer den Wert 0 an.

baseMipLevel Optional

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

dimension Optional

Ein enumerierter Wert, der das Format angibt, wie die Textur betrachtet wird. Mögliche Werte sind:

  • "1d": Die Textur wird als eindimensionales Bild betrachtet.
  • "2d": Die Textur wird als einzelnes zweidimensionales Bild betrachtet.
  • "2d-array": Die Textur wird als ein Array von zweidimensionalen Bildern betrachtet.
  • "cube": Die Textur wird als Würfelansicht betrachtet. Die Ansicht hat 6 Array-Ebenen, die den [+X, -X, +Y, -Y, +Z, -Z]-Seiten des Würfels entsprechen. Das Sampling erfolgt nahtlos über die Seiten des Würfels.
  • "cube-array": Die Textur wird als gepacktes Array von N Würfeln betrachtet, jeder mit 6 Array-Ebenen, die den [+X, -X, +Y, -Y, +Z, -Z]-Seiten des Würfels entsprechen. Das Sampling erfolgt nahtlos über die Seiten der Würfel.
  • "3d": Die Textur wird als dreidimensionales Bild betrachtet.

Wenn dimension weggelassen wird, erhält es einen Wert wie folgt:

format Optional

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

Wenn format weggelassen wird, wird es einen Wert wie folgt erhalten:

label Optional

Eine Zeichenkette zur Bereitstellung einer Kennzeichnung, die zur Identifizierung des Objekts verwendet werden kann, zum Beispiel in GPUError-Nachrichten 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

Eine Menge von bitweise Flags, die eine Teilmenge der Nutzungsflags der Quelltextur (verfügbar in der GPUTexture.usage-Eigenschaft) darstellen, die mit dem ausgewählten Ansichtformat kompatibel sind. Dies kann verwendet werden, um die erlaubte Nutzung der Ansicht zu beschränken, wenn das Ansichtformat mit bestimmten Nutzungen inkompatibel ist. Die verfügbaren Nutzungsflags sind im GPUTexture.usage Wertetabelle aufgeführt.

Der Standardwert ist 0, was die vollständige Menge von Nutzungsflags der Quelltextur repräsentiert. 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, ansonsten wird ein GPUValidationError generiert und ein ungültiges GPUTextureView-Objekt wird zurückgegeben:

Beispiele

Typische createView()-Verwendung

Im WebGPU-Beispiel Cubemap-Demo sehen Sie mehrere Beispiele, wie createView() verwendet wird, sowohl um eine resource-Ansicht für einen Aufruf zu GPUDevice.createBindGroup() 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 Nutzungsbeschränkung

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

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