GPUCommandEncoder: beginRenderPass() Methode

Syntax

beginRenderPass(descriptor)

Parameter

descriptor

Ein Objekt, das die folgenden Eigenschaften enthält:

colorAttachments

Ein Array von Objekten (siehe Struktur von Farbattachment-Objekten), die die Farbattachments definieren, auf die beim Ausführen dieses Render-Passes ausgegeben wird.

depthStencilAttachment Optional

Ein Objekt (siehe Struktur von Tiefen-/Stencilattachment-Objekten), das das Tiefen-/Stencilattachment definiert, auf das ausgegeben wird und gegen das getestet wird, wenn dieser Render-Pass ausgeführt wird.

label Optional

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

maxDrawCount Optional

Eine Zahl, die die maximale Anzahl an Draw-Calls angibt, die im Render-Pass ausgeführt werden. Dies wird von einigen Implementierungen verwendet, um Arbeiten zu dimensionieren, die vor dem Render-Pass eingefügt werden. Sie sollten den Standardwert – 50000000 – beibehalten, es sei denn, Sie wissen, dass mehr Draw-Calls ausgeführt werden.

occlusionQuerySet Optional

Das GPUQuerySet, das die Okklusionsabfrageergebnisse für diesen Pass speichert.

timestampWrites Optional

Ein Array von Objekten, die definieren, wo und wann Zeitstempelabfragewerte für diesen Pass geschrieben werden. Diese Objekte haben die folgenden Eigenschaften:

querySet

Ein GPUQuerySet vom Typ "timestamp", in das die Ergebnisse der Zeitstempelabfrage geschrieben werden.

beginningOfPassWriteIndex

Eine Zahl, die den Abfrageindex in querySet angibt, in den der Zeitstempel zu Beginn des Render-Passes geschrieben wird. Dies ist optional – wenn nicht definiert, wird kein Zeitstempel für den Beginn des Passes geschrieben.

endOfPassWriteIndex

Eine Zahl, die den Abfrageindex in querySet angibt, in den der Zeitstempel am Ende des Render-Passes geschrieben wird. Dies ist optional – wenn nicht definiert, wird kein Zeitstempel für das Ende des Passes geschrieben.

Hinweis: Die timestamp-query Funktion muss aktiviert sein, um Zeitstempelabfragen verwenden zu können. Zeitstempelabfragewerte werden in Nanosekunden geschrieben, jedoch ist es implementierungsdefiniert, wie der Wert bestimmt wird.

Struktur von Farbattachment-Objekten

Farbattachment-Objekte können die folgenden Eigenschaften haben:

clearValue Optional

Ein Farbwert, um die view-Textur vor der Ausführung des Render-Passes zu löschen. Dieser Wert wird ignoriert, wenn loadOp nicht auf "clear" gesetzt ist. clearValue nimmt ein Array oder Objekt, das die vier Farbkomponenten r, g, b und a als Dezimalzahlen darstellt.

Zum Beispiel können Sie ein Array wie [0.0, 0.5, 1.0, 1.0] oder sein äquivalentes Objekt { r: 0.0, g: 0.5, b: 1.0, a: 1.0 } übergeben.

Wenn clearValue weggelassen wird, ist der Standardwert { r: 0, g: 0, b: 0, a: 0 }.

depthSlice Optional

Eine Zahl, die den Index des 3D-Tiefenschnitts darstellt, auf den für dieses Farbattachment bei einem 3D GPUTextureView view ausgegeben wird. Wenn angegeben, ermöglicht dies WebGPU, direkt auf Scheiben von 3D-Texturen innerhalb von Render-Pässen zu rendern.

loadOp

Ein enumerierter Wert, der die Ladeoperation angibt, die auf view vor der Ausführung des Render-Passes ausgeführt werden soll. Mögliche Werte sind:

• "clear": Lädt den clearValue für dieses Attachment in den Render-Pass.
• "load": Lädt den vorhandenen Wert für dieses Attachment in den Render-Pass.

Hinweis: Es wird empfohlen, immer "clear" zu verwenden, wenn der Initialwert keine Rolle spielt, da dies auf einigen Geräten, wie z. B. Mobilgeräten, eine bessere Leistung bietet.

storeOp

Ein enumerierter Wert, der die Speicheroperation angibt, die auf view nach der Ausführung des Render-Passes ausgeführt werden soll. Mögliche Werte sind:

• "discard": Verwirft den resultierenden Wert des Render-Passes für dieses Attachment.
• "store": Speichert den resultierenden Wert des Render-Passes für dieses Attachment.

resolveTarget Optional

Ein Objekt, das die Textur-Subressource darstellt, die den aufgelösten Output für dieses Farbattachment empfängt, wenn view multisampled ist. Dies kann eines der folgenden sein:

• GPUTextureView
• GPUTexture: Kann anstelle eines GPUTextureView verwendet werden, vorausgesetzt, eine Standardansicht ist gewünscht. In diesem Kontext ist GPUTexture gleichbedeutend mit einem GPUTextureView-Objekt, das mit einem GPUTexture.createView()-Aufruf ohne angegebenes Argument erstellt wurde.

view

Ein Objekt, das die Textur-Subressource darstellt, die für dieses Farbattachment ausgegeben wird. Dies kann eines der folgenden sein:

• GPUTextureView
• GPUTexture: Kann anstelle eines GPUTextureView verwendet werden, vorausgesetzt, eine Standardansicht ist gewünscht. In diesem Kontext ist GPUTexture gleichbedeutend mit einem GPUTextureView-Objekt, das mit einem GPUTexture.createView()-Aufruf ohne angegebenes Argument erstellt wurde.

Hinweis: Jedes Farb- oder Tiefen-/Stencilattachment muss eine eindeutige Textur-Subressource sein, und Textur-Subressourcen, die als Attachments verwendet werden, können nicht innerhalb des Render-Passes verwendet werden.

Struktur von Tiefen-/Stencilattachment-Objekten

Das depthStencilAttachment-Objekt kann die folgenden Eigenschaften haben:

depthClearValue Optional

Eine Zahl, die den Wert angibt, auf den die Tiefenkomponente von view vor der Ausführung des Render-Passes gelöscht wird. Dies wird ignoriert, wenn depthLoadOp nicht auf "clear" gesetzt ist.

Der Wert muss zwischen 0,0 und 1,0 liegen, inklusive.

depthLoadOp Optional

Ein enumerierter Wert, der die Ladeoperation angibt, die auf die Tiefenkomponente von view vor der Ausführung des Render-Passes ausgeführt wird. Mögliche Werte sind:

• "clear": Lädt den clearValue für dieses Attachment in den Render-Pass.
• "load": Lädt den vorhandenen Wert für dieses Attachment in den Render-Pass.

Hinweis: Es wird empfohlen, immer "clear" zu verwenden, wenn der Initialwert keine Rolle spielt, da dies auf einigen Geräten, wie z. B. Mobilgeräten, eine bessere Leistung bietet.

depthReadOnly Optional

Ein boolescher Wert. Wenn der Wert auf true gesetzt ist, wird die Tiefenkomponente von view schreibgeschützt. Wenn depthReadOnly weggelassen wird, ist der Standardwert false.

depthStoreOp Optional

Ein enumerierter Wert, der die Speicheroperation angibt, die auf die Tiefenkomponente von view nach der Ausführung des Render-Passes ausgeführt wird. Mögliche Werte sind:

• "discard": Verwirft den resultierenden Wert des Render-Passes für dieses Attachment.
• "store": Speichert den resultierenden Wert des Render-Passes für dieses Attachment.

stencilClearValue Optional

Eine Zahl, die den Wert angibt, auf den die Stencilkomponente von view vor der Ausführung des Render-Passes gelöscht wird. Dies wird ignoriert, wenn stencilLoadOp nicht auf "clear" gesetzt ist.

Wenn stencilClearValue weggelassen wird, ist der Standardwert 0.

stencilLoadOp Optional

Ein enumerierter Wert, der die Ladeoperation angibt, die auf die Stencilkomponente von view vor der Ausführung des Render-Passes ausgeführt wird. Mögliche Werte sind:

• "clear": Lädt den clearValue für dieses Attachment in den Render-Pass.
• "load": Lädt den vorhandenen Wert für dieses Attachment in den Render-Pass.

Hinweis: Es wird empfohlen, immer "clear" zu verwenden, wenn der Initialwert keine Rolle spielt, da dies auf einigen Geräten, wie z. B. Mobilgeräten, eine bessere Leistung bietet.

stencilReadOnly Optional

Ein boolescher Wert. Wenn der Wert auf true gesetzt ist, wird die Stencilkomponente von view schreibgeschützt. Wenn stencilReadOnly weggelassen wird, ist der Standardwert false.

stencilStoreOp Optional

Ein enumerierter Wert, der die Speicheroperation angibt, die auf die Stencilkomponente von view nach der Ausführung des Render-Passes ausgeführt wird. Mögliche Werte sind:

• "discard": Verwirft den resultierenden Wert des Render-Passes für dieses Attachment.
• "store": Speichert den resultierenden Wert des Render-Passes für dieses Attachment.

view

Ein Objekt, das die Textur-Subressource darstellt, die für dieses Tiefen-/Stencilattachment ausgegeben und von ihr gelesen wird. Dies kann eines der folgenden sein:

• GPUTextureView
• GPUTexture: Kann anstelle eines GPUTextureView verwendet werden, vorausgesetzt, eine Standardansicht ist gewünscht. In diesem Kontext ist GPUTexture gleichbedeutend mit einem GPUTextureView-Objekt, das mit einem GPUTexture.createView()-Aufruf ohne angegebenes Argument erstellt wurde.

Rückgabewert

Eine Instanz des GPURenderPassEncoder Objekts.

Validierung

Die folgenden Kriterien müssen erfüllt sein, wenn beginRenderPass() aufgerufen wird, andernfalls wird ein GPUValidationError generiert und ein ungültiger GPURenderPassEncoder zurückgegeben.

Allgemein:

• colorAttachments.length ist kleiner oder gleich dem maxColorAttachments Limit des GPUDevice.
• Wenn colorAttachments nur null-Werte enthält, wird depthStencilAttachment bereitgestellt.
• Alle views in colorAttachments und depthStencilAttachment haben gleichwertige GPUTexture.sampleCount Werte und Render-Umfänge (GPUTexture.height, GPUTexture.width und GPUTexture.depthOrArrayLayers).
• Wenn occlusionQuerySet gesetzt ist, hat das referenzierte GPUQuerySet einen type von "occlusion".

Für Farbattachment-Objekte:

• Die view ist renderbar, und das Format der view (d.h. angegeben im Descriptor des ursprünglichen GPUTexture.createView()-Aufrufs) ist ein renderbares Farbformat.
• Wenn resolveTarget bereitgestellt wird:
  • Die originelle GPUTexture der view hat eine sampleCount von größer als 1.
  • Die originelle GPUTexture der resolveTarget hat eine sampleCount von 1.
  • resolveTarget ist renderbar.
  • Die Größen der Subressourcen, die view und resolveTarget bereitstellen, stimmen überein.
  • Die Formate von view und resolveTarget stimmen überein.
• Farbattachments Bytes pro Sample sind kleiner oder gleich dem maxColorAttachmentBytesPerSample Limit des GPUDevice.

Für Tiefen-/Stencilattachment-Objekte:

• Die view ist renderbar und ihr Format ist ein depth-or-stencil Format.
• Wenn depthLoadOp auf "clear" gesetzt ist, wird ein gültiger depthClearValue bereitgestellt.
• Wenn das Format der view ein kombiniertes depth-or-stencil Format ist, stimmen depthReadOnly und stencilReadOnly überein.
• Wenn das Format der view einen Tiefenaspekt hat und depthReadOnly false ist, werden depthLoadOp und depthStoreOp bereitgestellt.
• Wenn das Format der view einen Tiefenaspekt hat und depthReadOnly true ist, werden depthLoadOp und depthStoreOp nicht bereitgestellt.
• Wenn das Format der view einen Stencilaspekt hat und stencilReadOnly false ist, werden stencilLoadOp und stencilStoreOp bereitgestellt.
• Wenn das Format der view einen Stencilaspekt hat und stencilReadOnly true ist, werden stencilLoadOp und stencilStoreOp nicht bereitgestellt.

Für Zeitstempelabfragen:

• Die timestamp-query Funktion ist im GPUDevice aktiviert.

Beispiele

In unserem grundlegenden Render-Demo werden eine Vielzahl von Befehlen über einen GPUCommandEncoder aufgezeichnet. Diese Befehle stammen aus dem GPURenderPassEncoder, der über beginRenderPass() erstellt wird:

// …

// Create GPUCommandEncoder
const commandEncoder = device.createCommandEncoder();

// Create GPURenderPassDescriptor to tell WebGPU which texture to draw into, then initiate render pass

const renderPassDescriptor = {
  colorAttachments: [
    {
      clearValue: clearColor,
      loadOp: "clear",
      storeOp: "store",
      view: context.getCurrentTexture().createView(),
    },
  ],
};

const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);

// Draw a triangle

passEncoder.setPipeline(renderPipeline);
passEncoder.setVertexBuffer(0, vertexBuffer);
passEncoder.draw(3);

// End the render pass

passEncoder.end();

device.queue.submit([commandEncoder.finish()]);

// …

Spezifikation

Browser-Kompatibilität

Siehe auch

• Die WebGPU API