GPUCommandEncoder: beginRenderPass() Methode

descriptor

Ein Objekt, das die folgenden Eigenschaften enthält:

colorAttachments

Ein Array von Objekten (siehe Struktur des Farbanlageobjekts), die die Farbanlagen definieren, die beim Ausführen dieses Renderpasses ausgegeben werden.

depthStencilAttachment Optional

Ein Objekt (siehe Struktur des Tiefen-/Schablonanlageobjekts), das die Tiefen-/Schablonanlage definiert, die ausgegeben und getestet wird, wenn dieser Renderpass ausgeführt wird.

label Optional

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

maxDrawCount Optional

Eine Zahl, die die maximale Anzahl von Zeichnungsaufrufen angibt, die im Renderpass durchgeführt werden. Diese wird von einigen Implementierungen verwendet, um die vor dem Renderpass injizierte Arbeit zu dimensionieren. Sie sollten den Standardwert — 50000000 — beibehalten, es sei denn, Sie wissen, dass mehr Zeichnungsaufrufe durchgeführt werden.

occlusionQuerySet Optional

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

timestampWrites Optional

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

querySet

Ein GPUQuerySet des Typs "timestamp", in das die Zeitstempelabfrageergebnisse geschrieben werden.

beginningOfPassWriteIndex

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

endOfPassWriteIndex

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

Hinweis: Die timestamp-query Funktion muss aktiviert sein, um Zeitstempelabfragen zu verwenden. Zeitstempelabfragewerte werden in Nanosekunden geschrieben, jedoch ist die Bestimmung des Wertes implementierungsabhängig.

Farbanlageobjekte können die folgenden Eigenschaften haben:

clearValue Optional

Ein Farbwert, um die view-Textur vor der Ausführung des Renderpasses zu löschen. Dieser Wert wird ignoriert, wenn loadOp nicht auf "clear" gesetzt ist. clearValue nimmt ein Array oder Objekt an, 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 das entsprechende 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, der für diese Farbanlage, im Fall einer 3D GPUTextureView view, ausgegeben wird. Wenn angegeben, ermöglicht dies WebGPU direktes Rendern auf Schnitte von 3D-Texturen innerhalb von Renderpassagen.

loadOp

Ein aufzählbarer Wert, der angibt, welchen Ladebetrieb vor der Ausführung des Renderpasses auf view ausgeführt werden soll. Mögliche Werte sind:

• "clear": Lädt den clearValue für diese Anlage in den Renderpass.
• "load": Lädt den vorhandenen Wert für diese Anlage in den Renderpass.

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

storeOp

Ein aufzählbarer Wert, der angibt, welchen Speicherbetrieb nach der Ausführung des Renderpasses auf view ausgeführt werden soll. Mögliche Werte sind:

• "discard": Verwirft den Resultatwert des Renderpasses für diese Anlage.
• "store": Speichert den Resultatwert des Renderpasses für diese Anlage.

resolveTarget Optional

Ein GPUTextureView Objekt, das die Textur-Subressource darstellt, die den aufgelösten Output für diese Farbanlage erhält, falls view multisampled ist.

view

Ein GPUTextureView Objekt, das die Textur-Subressource darstellt, die für diese Farbanlage ausgegeben wird.

Hinweis: Jede Farb- oder Tiefen-/Schablonanlage muss eine eindeutige Textur-Subressource sein, und Textur-Subressourcen, die als Anlagen verwendet werden, können nicht innerhalb des Renderpasses verwendet werden.

Das depthStencilAttachment Objekt kann die folgenden Eigenschaften haben:

depthClearValue Optional

Eine Zahl, die angibt, auf welchen Wert die Tiefenkomponente von view vor der Ausführung des Renderpasses gelöscht wird. Dieser Wert wird ignoriert, wenn depthLoadOp nicht auf "clear" gesetzt ist.

Der Wert muss zwischen 0.0 und 1.0 liegen, einschließlich.

depthLoadOp Optional

Ein aufzählbarer Wert, der angibt, welchen Ladebetrieb vor der Ausführung des Renderpasses auf die Tiefenkomponente von view ausgeführt werden soll. Mögliche Werte sind:

• "clear": Lädt den clearValue für diese Anlage in den Renderpass.
• "load": Lädt den vorhandenen Wert für diese Anlage in den Renderpass.

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

depthReadOnly Optional

Ein Boolescher Wert. Setzt den Wert auf true, damit die Tiefenkomponente von view nur gelesen werden kann. Wenn depthReadOnly weggelassen wird, ist der Standardwert false.

depthStoreOp Optional

Ein aufzählbarer Wert, der angibt, welchen Speicherbetrieb nach der Ausführung des Renderpasses auf die Tiefenkomponente von view ausgeführt werden soll. Mögliche Werte sind:

• "discard": Verwirft den Resultatwert des Renderpasses für diese Anlage.
• "store": Speichert den Resultatwert des Renderpasses für diese Anlage.

stencilClearValue Optional

Eine Zahl, die angibt, auf welchen Wert die Schablonenkomponente von view vor der Ausführung des Renderpasses gelöscht wird. Dieser Wert wird ignoriert, wenn stencilLoadOp nicht auf "clear" gesetzt ist.

Wenn stencilClearValue weggelassen wird, ist der Standardwert 0.

stencilLoadOp Optional

Ein aufzählbarer Wert, der angibt, welchen Ladebetrieb vor der Ausführung des Renderpasses auf die Schablonenkomponente von view ausgeführt werden soll. Mögliche Werte sind:

• "clear": Lädt den clearValue für diese Anlage in den Renderpass.
• "load": Lädt den vorhandenen Wert für diese Anlage in den Renderpass.

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

stencilReadOnly Optional

Ein Boolescher Wert. Setzt den Wert auf true, damit die Schablonenkomponente von view nur gelesen werden kann. Wenn stencilReadOnly weggelassen wird, ist der Standardwert false.

stencilStoreOp Optional

Ein aufzählbarer Wert, der angibt, welchen Speicherbetrieb nach der Ausführung des Renderpasses auf die Schablonenkomponente von view ausgeführt werden soll. Mögliche Werte sind:

• "discard": Verwirft den Resultatwert des Renderpasses für diese Anlage.
• "store": Speichert den Resultatwert des Renderpasses für diese Anlage.

view

Ein GPUTextureView Objekt, das die Textur-Subressource darstellt, die für diese Tiefen-/Schablonanlage ausgegeben und gelesen wird.

Eine Instanz des GPURenderPassEncoder Objekts.

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

Allgemein:

• colorAttachments.length ist kleiner oder gleich der GPUDevice's maxColorAttachments Grenze.
• Wenn colorAttachments nur null-Werte enthält, wird depthStencilAttachment bereitgestellt.
• Alle views in colorAttachments und depthStencilAttachment haben gleiche GPUTexture.sampleCount Werte und Renderausdehnungen (GPUTexture.height, GPUTexture.width und GPUTexture.depthOrArrayLayers).
• Wenn occlusionQuerySet gesetzt ist, hat das referenzierte GPUQuerySet einen type von "occlusion".

Für Farbanlageobjekte

• Die view ist renderbar, und das Format der view (d.h. im Descriptor des ursprünglichen GPUTexture.createView() Aufrufs angegeben) ist ein farbrenderbares Format.
• Wenn resolveTarget bereitgestellt ist:
  • Der views Ursprungs-GPUTexture(/de/docs/Web/API/GPUTexture)'s sampleCount ist größer als 1.
  • Der resolveTargets Ursprungs-GPUTexture(/de/docs/Web/API/GPUTexture)'s sampleCount ist 1.
  • resolveTarget ist renderbar.
  • Die Größen der Subressourcen, die view und resolveTarget eine Ansicht bieten, stimmen überein.
  • views und resolveTargets Formate stimmen überein.
• Farbanlagen Bytes pro Sample ist kleiner oder gleich der GPUDevice's maxColorAttachmentBytesPerSample Grenze.

Für Tiefen-/Schablone-Anlageobjekte:

• Die view ist renderbar, und ihr Format ist ein depth-or-stencil Format.
• Wenn depthLoadOp auf "clear" gesetzt ist, wird ein gültiges depthClearValue bereitgestellt.
• Wenn das Format der view ein kombiniertes Tiefen- oder Schablonenformat ist, muss depthReadOnly mit stencilReadOnly übereinstimmen.
• 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 Schablonenaspekt hat und stencilReadOnly false ist, werden stencilLoadOp und stencilStoreOp bereitgestellt.
• Wenn das Format der view einen Schablonenaspekt hat und stencilReadOnly true ist, werden stencilLoadOp und stencilStoreOp nicht bereitgestellt.

Für Zeitstempelabfragen:

• Die timestamp-query Funktion ist im GPUDevice aktiviert.

In unserem Basic Render Demo werden eine Reihe von Befehlen über einen GPUCommandEncoder aufgezeichnet. Diese Befehle stammen vom GPURenderPassEncoder, der über beginRenderPass() erstellt wurde:

// …

// 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()]);

// …

• Die WebGPU API