GPUTexture: createView() Methode

Limited availability

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

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

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 Interface 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 ab dem Wert baseArrayLayer für die Ansicht zugänglich sind.

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 aufzählbarer Wert, der festlegt, 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 Schablonen-Aspekt eines depth-or-stencil-Formats ist für die Ansicht zugänglich.

Wenn aspect weggelassen wird, erhält es den Wert "all".

baseArrayLayer Optional

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

baseMipLevel Optional

Eine Zahl, die das erste (detaillierteste) Mipmap-Level darstellt, das für die Ansicht zugänglich ist. Wenn weggelassen, erhält baseMipLevel den Wert 0.

dimension Optional

Ein aufzählbarer Wert, der angibt, in welchem Format die Textur angesehen 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 Array von zweidimensionalen Bildern betrachtet.
  • "cube": Die Textur wird als Würfelkarte 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 Flächen der Würfelkarte hinweg.
  • "cube-array": Die Textur wird als gepacktes Array von N Würfelkarten angesehen, jede mit 6 Array-Ebenen, die den [+X, -X, +Y, -Y, +Z, -Z]-Flächen des Würfels entsprechen. Das Sampling erfolgt nahtlos über die Flächen der Würfelkarten hinweg.
  • "3d": Die Textur wird als dreidimensionales Bild betrachtet.

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

format Optional

Ein aufzählbarer Wert, der das Format der Texturansicht bestimmt. Siehe den Abschnitt Texturformate der Spezifikation für alle möglichen Werte.

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

label Optional

Eine Zeichenkette, die ein Label bereitstellt, welches verwendet werden kann, um das Objekt z. B. in GPUError-Meldungen oder Konsolenwarnungen zu identifizieren.

mipLevelCount Optional

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

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

usage Optional

Eine Menge von bitweisen Flags, die eine Teilmenge der Nutzungsflags der Quelltextur (verfügbar in der GPUTexture.usage-Eigenschaft) darstellen, die mit dem ausgewählten Ansichtsformat kompatibel sind. Dies kann verwendet werden, um die erlaubte Ansichtsverwendung in Fällen einzuschränken, in denen das Ansichtsformat mit bestimmten Verwendungen unvereinbar ist. Die verfügbaren Nutzungsflags sind in der GPUTexture.usage Werte-Tabelle aufgeführt.

Der Standardwert ist 0, was das vollständige Set 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 Nutzungen der Ansicht müssen explizit angegeben werden.

Rückgabewert

Eine Instanz eines GPUTextureView Objekts.

Validierung

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

Beispiele

Typische Verwendung von createView()

Im WebGPU Samples 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() Deskriptors 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 Beispiel erstellen wir eine Textur und anschließend eine Ansicht, deren Nutzung mithilfe der 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