QRhiCommandBuffer Class

Dokumentation der Mitgliedsfunktionen

void QRhiCommandBuffer::beginComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {})

Datensätze, die einen neuen Berechnungsdurchlauf starten.

resourceUpdatesWenn der Wert nicht null ist, gibt er einen Ressourcenaktualisierungsstapel an, der bestätigt und dann freigegeben werden soll.

flags wird derzeit nicht verwendet.

void QRhiCommandBuffer::beginExternal()

Wird aufgerufen, wenn die Anwendung vor dem direkten Aufruf von Grafik-API-Funktionen Befehle in den Befehlspuffer des aktuellen Durchlaufs einreihen will.

Mit Vulkan, Metal oder Direct3D 12 kann man die nativen Befehlspuffer- oder Encoder-Objekte über nativeHandles() abfragen und Befehle in die Warteschlange stellen. Bei OpenGL oder Direct3D 11 kann der (Geräte-)Kontext über QRhi::nativeHandles() abgefragt werden. Dies darf jedoch nie geschehen, ohne sicherzustellen, dass der Zustand von QRhiCommandBuffer aktuell bleibt. Daher ist es erforderlich, jede extern hinzugefügte Befehlsaufzeichnung zwischen beginExternal() und endExternal() einzuschließen. Konzeptionell ist dies dasselbe wie die Funktionen beginNativePainting() und endNativePainting() von QPainter.

Speziell für OpenGL hat diese Funktion eine zusätzliche Aufgabe: Sie stellt sicher, dass der Kontext auf dem aktuellen Thread aktuell gemacht wird.

Siehe auch endExternal() und nativeHandles().

void QRhiCommandBuffer::beginPass(QRhiRenderTarget *rt, const QColor &colorClearValue, const QRhiDepthStencilClearValue &depthStencilClearValue, QRhiResourceUpdateBatch *resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {})

Datensätze, die einen neuen Rendering-Durchgang mit dem Rendering-Ziel rt starten.

resourceUpdatesWenn dieser Wert nicht Null ist, gibt er einen Ressourcenaktualisierungsstapel an, der übertragen und dann freigegeben werden soll.

Die Farb- und Tiefen-/Schablonenpuffer des Renderziels werden normalerweise gelöscht. Die Löschwerte sind in colorClearValue und depthStencilClearValue angegeben. Die Ausnahme ist, wenn das Rendering-Ziel mit QRhiTextureRenderTarget::PreserveColorContents und/oder QRhiTextureRenderTarget::PreserveDepthStencilContents erstellt wurde. Die Clear-Werte werden dann ignoriert.

Wenn rt ein QRhiTextureRenderTarget ist, führt beginPass() eine Überprüfung durch, um festzustellen, ob die Textur- und Renderbuffer-Objekte, auf die vom Rendering-Ziel verwiesen wird, aktuell sind. Dies ist vergleichbar mit dem, was setShaderResources() für QRhiShaderResourceBindings tut. Wenn eines der Attachments seit QRhiTextureRenderTarget::create() neu erstellt wurde, erfolgt ein impliziter Aufruf von create() auf rt. Wenn also rt einen QRhiTexture Farbanhang texture hat und man die Textur in eine andere Größe bringen muss, dann gilt Folgendes:

QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ { texture } });
rt->create();
// ...
texture->setPixelSize(new_size);
texture->create();
cb->beginPass(rt, colorClear, dsClear); // this is ok, no explicit rt->create() is required before

flags die Steuerung bestimmter erweiterter Funktionen erlauben. Ein häufig verwendetes Flag ist ExternalContents. Dieses sollte immer dann angegeben werden, wenn beginExternal() innerhalb des von dieser Funktion gestarteten Durchlaufs aufgerufen wird.

Siehe auch endPass() und BeginPassFlags.

void QRhiCommandBuffer::debugMarkBegin(const QByteArray &name)

Zeichnet eine benannte Debug-Gruppe im Befehlspuffer mit dem angegebenen name auf. Dies wird in Grafik-Debugging-Tools wie RenderDoc und XCode angezeigt. Das Ende der Gruppierung wird durch debugMarkEnd() angezeigt.

void QRhiCommandBuffer::debugMarkEnd()

Zeichnet das Ende einer Debug-Gruppe auf.

void QRhiCommandBuffer::debugMarkMsg(const QByteArray &msg)

Fügt eine Debug-Meldung msg in den Befehlsstrom ein.

void QRhiCommandBuffer::dispatch(int x, int y, int z)

Datensätze, die Rechenaufgaben verteilen, wobei x, y und z die Anzahl der lokalen Arbeitsgruppen in der entsprechenden Dimension angeben.

void QRhiCommandBuffer::draw(quint32 vertexCount, quint32 instanceCount = 1, quint32 firstVertex = 0, quint32 firstInstance = 0)

Zeichnet eine nicht-indizierte Zeichnung auf.

Die Anzahl der Scheitelpunkte wird in vertexCount angegeben. Für instanziertes Zeichnen setzen Sie instanceCount auf einen anderen Wert als 1. firstVertex ist der Index des ersten zu zeichnenden Vertex. Wenn mehrere Instanzen gezeichnet werden, wird die erste Instanz-ID durch firstInstance angegeben.

void QRhiCommandBuffer::drawIndexed(quint32 indexCount, quint32 instanceCount = 1, quint32 firstIndex = 0, qint32 vertexOffset = 0, quint32 firstInstance = 0)

Zeichnet eine indizierte Zeichnung auf.

Die Anzahl der Scheitelpunkte wird in indexCount angegeben. firstIndex ist der Basisindex. Der effektive Versatz im Indexpuffer wird durch indexOffset + firstIndex * n angegeben, wobei n je nach Indexelementtyp 2 oder 4 ist. indexOffset wird in setVertexInput() angegeben.

Für instanziertes Zeichnen setzen Sie instanceCount auf einen anderen Wert als 1. Wenn Sie mehrere Instanzen zeichnen, wird die erste Instanz-ID durch firstInstance angegeben.

vertexOffset (auch base vertex genannt) ist ein vorzeichenbehafteter Wert, der vor der Indizierung in den Scheitelpunktpuffer zum Elementindex addiert wird. Diese Funktion wird nicht immer unterstützt, und der Wert wird ignoriert, wenn das Feature QRhi::BaseVertex als nicht unterstützt gemeldet wird.

void QRhiCommandBuffer::endComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr)

Datensätze, die den aktuellen Rechendurchlauf beenden.

resourceUpdatesGibt, wenn nicht null, einen Ressourcenaktualisierungsstapel an, der bestätigt und dann freigegeben werden soll.

void QRhiCommandBuffer::endExternal()

Wird aufgerufen, sobald die extern hinzugefügten Befehle im Befehlspuffer oder Kontext aufgezeichnet sind.

Siehe auch beginExternal() und nativeHandles().

void QRhiCommandBuffer::endPass(QRhiResourceUpdateBatch *resourceUpdates = nullptr)

Datensätze, die den aktuellen Rendering-Durchgang beenden.

resourceUpdatesGibt, wenn nicht null, einen Ressourcenaktualisierungsstapel an, der übertragen und dann freigegeben werden soll.

Siehe auch beginPass().

double QRhiCommandBuffer::lastCompletedGpuTime()

Gibt den letzten verfügbaren Zeitstempel in Sekunden zurück, wenn QRhi::EnableTimestamps bei der Erstellung von QRhi aktiviert war. Der Wert gibt die auf der GPU verstrichene Zeit während des letzten abgeschlossenen Frames an.

Bei der Interpretation des Wertes ist Vorsicht geboten, da seine Genauigkeit und Granularität oft nicht von Qt kontrolliert wird und von der zugrunde liegenden Grafik-API und ihrer Implementierung abhängt. Insbesondere wird davon abgeraten, die Werte zwischen verschiedenen Grafik-APIs und Hardware zu vergleichen, da dies sinnlos sein kann.

Wenn das Bild mit beginFrame() und endFrame(), d.h. mit einer Swapchain, aufgezeichnet wurde, werden die Timing-Werte wahrscheinlich asynchron verfügbar sein. Der zurückgegebene Wert kann daher 0 sein (z. B. für die ersten 1-2 Frames) oder der letzte bekannte Wert, der sich auf einen früheren Frame bezieht. Der Wert kann unter bestimmten Bedingungen auch wieder 0 werden, z. B. wenn die Größe des Fensters geändert wird. Es ist zu erwarten, dass der aktuellste verfügbare Wert in beginFrame() abgerufen wird und über diese Funktion abfragbar wird, sobald beginFrame() zurückkehrt.

Andererseits ist der zurückgegebene Wert bei Offscreen-Frames aktuell, sobald endOffscreenFrame() zurückkehrt, da Offscreen-Frames das GPU-Pipelining reduzieren und die Befehle abwarten, bis sie abgeschlossen sind.

Achten Sie auf die Folgen von GPU-Frequenzskalierung und GPU-Taktänderungen, abhängig von der Plattform. Zum Beispiel kann unter Windows das zurückgegebene Timing zwischen Frames mit modernen Grafikkarten in einem ziemlich weiten Bereich variieren, selbst wenn Frames mit ähnlicher oder gleicher Arbeitslast gesendet werden. Dies ist für Qt im Allgemeinen nicht zu kontrollieren und zu lösen. Das D3D12 Backend ruft jedoch automatisch ID3D12Device::SetStablePowerState() auf, wenn die Umgebungsvariable QT_D3D_STABLE_POWER_STATE auf einen Wert ungleich Null gesetzt wird. Dies kann das Ergebnis erheblich stabilisieren. Es kann auch eine nicht unerhebliche Auswirkung auf die CPU-seitigen Timings haben, die z.B. über QElapsedTimer gemessen werden, insbesondere wenn Offscreen-Frames beteiligt sind.

Siehe auch QRhi::Timestamps und QRhi::EnableTimestamps.

const QRhiNativeHandles *QRhiCommandBuffer::nativeHandles()

Gibt einen Zeiger auf eine Backend-spezifische QRhiNativeHandles Unterklasse zurück, wie z.B. QRhiVulkanCommandBufferNativeHandles. Der zurückgegebene Wert ist nullptr, wenn die zugrundeliegenden nativen Ressourcen vom Backend nicht unterstützt werden oder für das Backend nicht anwendbar sind.

Siehe auch QRhiVulkanCommandBufferNativeHandles, QRhiMetalCommandBufferNativeHandles, beginExternal(), und endExternal().

[override virtual] QRhiResource::Type QRhiCommandBuffer::resourceType() const

Reimplements: QRhiResource::resourceType() const.

Gibt den Ressourcentyp zurück.

void QRhiCommandBuffer::resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates)

Manchmal ist das Übertragen von Ressourcenaktualisierungen notwendig oder einfach bequemer, ohne einen Renderdurchgang zu starten. Der Aufruf dieser Funktion mit resourceUpdates ist eine Alternative zur Übergabe von resourceUpdates an einen beginPass()-Aufruf (oder endPass(), was im Falle von Readbacks typisch wäre).

void QRhiCommandBuffer::setBlendConstants(const QColor &c)

Datensätze, die die aktiven Mischkonstanten auf c setzen.

Diese Funktion kann nur aufgerufen werden, wenn die gebundene Pipeline QRhiGraphicsPipeline::UsesBlendConstants gesetzt ist.

void QRhiCommandBuffer::setComputePipeline(QRhiComputePipeline *ps)

Zeichnet das Setzen einer neuen Berechnungspipeline ps auf.

void QRhiCommandBuffer::setGraphicsPipeline(QRhiGraphicsPipeline *ps)

Zeichnet das Setzen einer neuen Grafikpipeline ps auf.

void QRhiCommandBuffer::setScissor(const QRhiScissor &scissor)

Datensätze, die das in scissor angegebene aktive Scherenrechteck setzen.

Diese Funktion kann nur aufgerufen werden, wenn für die gebundene Pipeline UsesScissor gesetzt ist. Wenn das Flag in der aktiven Pipeline gesetzt ist, muss diese Funktion aufgerufen werden, da die Scherenprüfung aktiviert wird und daher ein Scherenrechteck bereitgestellt werden muss.

void QRhiCommandBuffer::setShaderResources(QRhiShaderResourceBindings *srb = nullptr, int dynamicOffsetCount = 0, const QRhiCommandBuffer::DynamicOffset *dynamicOffsets = nullptr)

Datensätze, die einen Satz von Shader-Ressourcen binden, z. B. einheitliche Puffer oder Texturen, die für eine oder mehrere Shader-Stufen sichtbar gemacht werden.

srb kann null sein, in diesem Fall wird die aktuelle Grafik- oder Berechnungspipeline verwendet, die QRhiShaderResourceBindings zugeordnet ist. Wenn srb nicht null ist, muss es layout-compatible sein, was bedeutet, dass das Layout (Anzahl der Bindungen, Typ und Bindungsnummer jeder Bindung) vollständig mit dem QRhiShaderResourceBindings übereinstimmen muss, das der Pipeline zum Zeitpunkt des Aufrufs von create() zugeordnet war.

Es gibt Fälle, in denen ein scheinbar unnötiger setShaderResources()-Aufruf obligatorisch ist: Beim Neuaufbau einer Ressource, die von srb referenziert wird, z. B. beim Ändern der Größe eines QRhiBuffer gefolgt von einem QRhiBuffer::create(), ist dies der Ort, an dem zugehörige native Objekte (wie Deskriptor-Sets im Falle von Vulkan) aktualisiert werden, um auf die aktuellen nativen Ressourcen zu verweisen, die die QRhiBuffer, QRhiTexture, QRhiSampler Objekte unterstützen, die von srb referenziert werden. In diesem Fall muss setShaderResources() auch dann aufgerufen werden, wenn srb derselbe Wert wie beim letzten Aufruf ist.

Wenn srb nicht null ist, wird auf das Objekt QRhiShaderResourceBindings, mit dem die Pipeline in create() erstellt wurde, garantiert in keiner Form zugegriffen. Tatsächlich muss es nicht einmal zu diesem Zeitpunkt gültig sein: Das Zerstören des der Pipeline zugeordneten srb nach create() und stattdessen die explizite Angabe eines anderen, layout compatible, in jedem setShaderResources()-Aufruf ist gültig.

dynamicOffsets erlaubt die Angabe von Puffer-Offsets für einheitliche Puffer, die mit srb über QRhiShaderResourceBinding::uniformBufferWithDynamicOffset() verknüpft wurden. Dies unterscheidet sich von der Angabe des Offsets in srb selbst: Dynamische Offsets erfordern nicht die Erstellung eines neuen QRhiShaderResourceBindings für jeden unterschiedlichen Offset, können das Schreiben der zugrundeliegenden Deskriptoren (mit Backends, wo anwendbar) vermeiden und sind daher möglicherweise effizienter. Jedes Element von dynamicOffsets ist ein Paar binding - offset. dynamicOffsetCount gibt die Anzahl der Elemente in dynamicOffsets an.

void QRhiCommandBuffer::setStencilRef(quint32 refValue)

Setzt den Referenzwert der aktiven Schablone auf refValue.

Diese Funktion kann nur aufgerufen werden, wenn für die gebundene Pipeline QRhiGraphicsPipeline::UsesStencilRef festgelegt wurde.

void QRhiCommandBuffer::setVertexInput(int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings, QRhiBuffer *indexBuf = nullptr, quint32 indexOffset = 0, QRhiCommandBuffer::IndexFormat indexFormat = IndexUInt16)

Zeichnet Scheitelpunkt-Eingabebindungen auf.

Der Indexpuffer, der von nachfolgenden drawIndexed() Befehlen verwendet wird, wird durch indexBuf, indexOffset und indexFormat spezifiziert. indexBuf kann auf Null gesetzt werden, wenn indiziertes Zeichnen nicht benötigt wird.

Scheitelpunktpuffer-Bindungen werden gestapelt. startBinding gibt die erste Bindungsnummer an. Der aufgezeichnete Befehl bindet dann jeden Puffer von bindings an den Bindungspunkt startBinding + i, wobei i der Index in bindings ist. Jedes Element in bindings gibt ein QRhiBuffer und einen Offset an.

Überflüssige Scheitelpunkt-Eingaben und Index-Änderungen im selben Durchgang werden bei den meisten Backends automatisch ignoriert, so dass Anwendungen nicht überoptimiert werden müssen, um Aufrufe dieser Funktion zu vermeiden.

Nehmen wir als einfaches Beispiel einen Vertex-Shader mit zwei Eingängen:

layout(location = 0) in vec4 position;
layout(location = 1) in vec3 color;

Wir nehmen an, dass die Daten im Interleaved-Format vorliegen und nur 2 Floats für die Position verwendet werden (also 5 Floats pro Vertex: x, y, r, g, b). Ein QRhiGraphicsPipeline für diesen Shader kann dann unter Verwendung des Eingangslayouts erstellt werden:

QRhiVertexInputLayout inputLayout;
inputLayout.setBindings({
    { 5 * sizeof(float) }
});
inputLayout.setAttributes({
    { 0, 0, QRhiVertexInputAttribute::Float2, 0 },
    { 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
});

Hier gibt es eine Pufferbindung (Bindungsnummer 0), die von zwei Eingängen referenziert wird. Bei der Aufzeichnung des Durchlaufs können die Scheitelpunktbindungen, sobald die Pipeline eingestellt ist, einfach wie folgt angegeben werden, vorausgesetzt, vbuf ist die QRhiBuffer mit allen verschachtelten Positions- und Farbdaten:

const QRhiCommandBuffer::VertexInput vbufBinding(vbuf, 0);
cb->setVertexInput(0, 1, &vbufBinding);

void QRhiCommandBuffer::setViewport(const QRhiViewport &viewport)

Setzt das in viewport angegebene aktive Ansichtsfenster-Rechteck.

Bei Backends, bei denen die zugrundeliegende Grafik-API die Schere immer aktiviert hat, setzt diese Funktion auch die Schere so, dass sie mit dem Ansichtsfenster übereinstimmt, wenn für das aktive QRhiGraphicsPipeline nicht UsesScissor gesetzt ist.