QRhiCommandBuffer Class

Dokumentation der Mitgliedsfunktionen

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

Protokolliert den Start eines neuen Rechenlaufs.

resourceUpdates, sofern nicht null, gibt einen Ressourcenaktualisierungsstapel an, der festgeschrieben und anschließend freigegeben werden soll.

flags wird derzeit nicht verwendet.

void QRhiCommandBuffer::beginExternal()

Wird aufgerufen, wenn die vorangehende Anwendung im Begriff ist, Befehle durch direkten Aufruf von Grafik-API-Funktionen in den Befehlspuffer des aktuellen Durchlaufs einzureihen.

Mit Vulkan, Metal oder Direct3D 12 kann man die nativen Befehlspuffer- oder Encoder-Objekte über ` nativeHandles()` abfragen und Befehle in diese einreihen. Mit OpenGL oder Direct3D 11 kann der (Geräte-)Kontext über ` QRhi::nativeHandles()` abgerufen werden. Dies darf jedoch niemals geschehen, ohne sicherzustellen, dass der Status von „ QRhiCommandBuffer “ auf dem neuesten Stand bleibt. Daher ist es erforderlich, jede extern hinzugefügte Befehlsaufzeichnung zwischen „beginExternal()“ und „ endExternal()“ einzuschließen. Konzeptionell entspricht dies den Funktionen „ beginNativePainting()“ und „ endNativePainting()“ von „ QPainter “.

Insbesondere für OpenGL hat diese Funktion eine zusätzliche Aufgabe: Sie stellt sicher, dass der Kontext im aktuellen Thread als aktueller Kontext gesetzt wird.

Siehe auch „ endExternal()“ und „ nativeHandles()“.

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

Zeichnet den Start eines neuen Render-Durchgangs auf, der auf das Renderziel rt abzielt.

resourceUpdates, sofern nicht null, gibt einen Ressourcen-Update-Batch an, der festgeschrieben und anschließend freigegeben werden soll.

Die Farb- und Tiefen-/Stencil-Puffer des Renderziels werden normalerweise gelöscht. Die Löschwerte werden in ` colorClearValue ` und ` depthStencilClearValue` angegeben. Eine Ausnahme bildet der Fall, in dem das Renderziel mit ` QRhiTextureRenderTarget::PreserveColorContents ` und/oder ` QRhiTextureRenderTarget::PreserveDepthStencilContents` erstellt wurde. In diesem Fall werden die Löschwerte ignoriert.

Wenn „ rt “ ein „ QRhiTextureRenderTarget “ ist, führt „beginPass()“ eine Überprüfung durch, um festzustellen, ob die vom Renderziel referenzierten Textur- und Renderbuffer-Objekte auf dem neuesten Stand sind. Dies ähnelt der Funktionsweise von ` setShaderResources()` für ` QRhiShaderResourceBindings`. Falls eines der Attachments seit dem Aufruf von ` QRhiTextureRenderTarget::create()` neu erstellt wurde, erfolgt ein impliziter Aufruf von `create()` für ` rt`. Wenn also ` rt ` ein ` QRhiTexture `-Farb-Attachment ` texture` enthält und die Textur auf eine andere Größe geändert werden soll, ist Folgendes zulässig:

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 Ermöglicht die Steuerung bestimmter erweiterter Funktionen. Ein häufig verwendetes Flag ist ExternalContents. Dieses sollte immer dann angegeben werden, wenn beginExternal() innerhalb des durch diese Funktion gestarteten Durchgangs aufgerufen wird.

Siehe auch endPass() und BeginPassFlags.

void QRhiCommandBuffer::debugMarkBegin(const QByteArray &name)

Zeichnet eine benannte Debug-Gruppe im Befehlspuffer unter Verwendung der angegebenen „ name “ auf. Diese wird in Grafik-Debugging-Tools wie RenderDoc und XCode angezeigt. Das Ende der Gruppierung wird durch „ debugMarkEnd()“ gekennzeichnet.

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)

Protokolliert die Verteilung von Rechen-Workitems, 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 einen nicht indizierten Zug auf.

Die Anzahl der Eckpunkte wird in „ vertexCount “ angegeben. Für instanziertes Zeichnen setzen Sie „ instanceCount “ auf einen Wert ungleich 1. „ firstVertex “ ist der Index des ersten zu zeichnenden Eckpunkts. Beim Zeichnen mehrerer Instanzen wird die ID der ersten Instanz durch „ firstInstance “ angegeben.

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

Zeichnet einen indizierten Draw auf.

Die Anzahl der Eckpunkte wird in ` indexCount` angegeben. ` firstIndex ` ist der Basisindex. Der effektive Offset im Indexpuffer ergibt sich aus ` indexOffset + firstIndex * n `, wobei ` n ` je nach Typ des Indexelements 2 oder 4 ist. ` indexOffset ` wird in ` setVertexInput()` angegeben.

vertexOffset (auch als „ base vertex “ bezeichnet) ist ein vorzeichenbehafteter Wert, der zum Elementindex addiert wird, bevor die Indizierung in den Vertex-Puffer erfolgt. Die Unterstützung hierfür ist nicht immer verfügbar, und der Wert wird ignoriert, wenn die Funktion „ QRhi::BaseVertex “ als nicht unterstützt gemeldet wird.

Für das Zeichnen von Instanzen setzen Sie „ instanceCount “ auf einen anderen Wert als 1. Beim Zeichnen mehrerer Instanzen wird die erste Instanz-ID durch „ firstInstance “ angegeben.

[since 6.12] void QRhiCommandBuffer::drawIndexedIndirect(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset, quint32 drawCount, quint32 stride = sizeof(QRhiIndexedIndirectDrawCommand))

Zeichnet einen indizierten, indirekten Aufruf auf.

Die Abrufparameter werden durch den in ` indirectBuffer` angegebenen Puffer bereitgestellt, der ein Array mit Elementen vom Typ ` QRhiIndexedIndirectDrawCommand` enthalten muss. Die Parameter in ` QRhiIndexedIndirectDrawCommand ` haben dieselbe Bedeutung wie in ` drawIndexed()`.

Der Offset in Bytes, ab dem die Parameter aus dem Puffer gelesen werden, wird durch ` indirectBufferOffset` festgelegt.

drawCount gibt die Anzahl der auszuführenden Zeichenbefehle an.

stride Gibt die Byte-Größe jeder einzelnen Zeichnungsbefehlsstruktur im Puffer an. Dies ermöglicht bei Bedarf das Einfügen benutzerdefinierter Daten zwischen den Befehlen. Der Wert muss ein Vielfaches von 4 und größer oder gleich sizeof(QRhiIndexedIndirectDrawCommand) sein.

Diese Funktion wurde in Qt 6.12 eingeführt.

[since 6.12] void QRhiCommandBuffer::drawIndirect(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset, quint32 drawCount, quint32 stride = sizeof(QRhiIndirectDrawCommand))

Zeichnet einen nicht indizierten, indirekten Zeichnungsvorgang auf.

Die Abrufparameter werden durch den in ` indirectBuffer` angegebenen Puffer bereitgestellt, der ein Array mit Elementen vom Typ ` QRhiIndirectDrawCommand` enthalten muss. Die Parameter in ` QRhiIndirectDrawCommand ` haben dieselbe Bedeutung wie in ` draw()`.

Der Offset in Byte, ab dem die Parameter aus dem Puffer gelesen werden, wird durch ` indirectBufferOffset` angegeben.

drawCount gibt die Anzahl der auszuführenden Zeichenbefehle an.

stride Gibt die Byte-Größe jeder einzelnen Zeichnungsbefehlsstruktur im Puffer an. Dies ermöglicht bei Bedarf das Einfügen benutzerdefinierter Daten zwischen den Befehlen. Der Wert muss ein Vielfaches von 4 und größer oder gleich sizeof(QRhiIndirectDrawCommand) sein.

Diese Funktion wurde in Qt 6.12 eingeführt.

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

Datensätze, die den aktuellen Rechenlauf beenden.

resourceUpdates, sofern nicht null, gibt einen Ressourcen-Aktualisierungsstapel an, der festgeschrieben und anschließend freigegeben werden soll.

void QRhiCommandBuffer::endExternal()

Wird aufgerufen, sobald die extern hinzugefügten Befehle im Befehlspuffer oder Kontext gespeichert wurden.

Siehe auch „ beginExternal()“ und „ nativeHandles()“.

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

Zeichnet den aktuellen Render-Durchlauf ab.

resourceUpdates, sofern nicht null, gibt einen Ressourcen-Update-Batch an, der festgeschrieben und anschließend freigegeben werden soll.

Siehe auch ` beginPass()`.

double QRhiCommandBuffer::lastCompletedGpuTime()

Gibt den letzten verfügbaren Zeitstempel in Sekunden zurück, sofern die Funktion „ QRhi::EnableTimestamps “ beim Erstellen der „ QRhi “ aktiviert war. Der Wert gibt die auf der GPU während des zuletzt abgeschlossenen Frames verstrichene Zeit an.

Bei der Interpretation des Werts ist Vorsicht geboten, da dessen Genauigkeit und Granularität oft nicht von Qt gesteuert werden und von der zugrunde liegenden Grafik-API sowie deren Implementierung abhängen. Insbesondere wird davon abgeraten, die Werte verschiedener Grafik-APIs und Hardware miteinander zu vergleichen, da dies möglicherweise aussagekräftig ist.

Die Zeitwerte werden wahrscheinlich asynchron verfügbar. 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, wie z. B. beim Ändern der Fenstergröße, auch wieder 0 werden. Es ist zu erwarten, dass der aktuellste verfügbare Wert in `beginFrame()` abgerufen wird und über diese Funktion abgefragt werden kann, sobald `beginFrame()` zurückkehrt.

Beachten Sie die Auswirkungen von GPU-Frequenzskalierung und Änderungen der GPU-Taktfrequenz, die je nach Plattform variieren können. Unter Windows beispielsweise kann die zurückgegebene Zeitangabe bei modernen Grafikkarten von Frame zu Frame in einem recht großen Bereich schwanken, selbst wenn Frames mit ähnlicher oder identischer Auslastung übermittelt werden. Dies liegt generell außerhalb des Einflussbereichs von Qt und kann von Qt nicht gesteuert oder behoben werden. Das D3D12-Backend ruft jedoch automatisch `ID3D12Device::SetStablePowerState()` auf, sobald die Umgebungsvariable ` QT_D3D_STABLE_POWER_STATE ` auf einen Wert ungleich Null gesetzt ist. Dies kann das Ergebnis erheblich stabilisieren. Es kann zudem einen nicht unerheblichen Einfluss auf die CPU-seitigen Zeitwerte haben, die beispielsweise ü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 Unterklasse von ` QRhiNativeHandles ` zurück, beispielsweise ` QRhiVulkanCommandBufferNativeHandles`. Der Rückgabewert ist ` nullptr `, wenn die Offenlegung der zugrunde liegenden nativen Ressourcen vom Backend nicht unterstützt wird oder nicht anwendbar ist.

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

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

Implementiert neu: ` QRhiResource::resourceType()` const.

Gibt den Ressourcentyp zurück.

void QRhiCommandBuffer::resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates)

Manchmal ist es notwendig oder einfach praktischer, Ressourcenaktualisierungen zu übernehmen, ohne einen Render-Durchlauf zu starten. Der Aufruf dieser Funktion mit ` resourceUpdates ` ist eine Alternative zur Übergabe von ` resourceUpdates ` an einen Aufruf von ` beginPass()` (oder ` endPass()`, was bei Readbacks üblich wäre).

void QRhiCommandBuffer::setBlendConstants(const QColor &c)

Datensätze, in denen die aktiven Mischkonstanten auf „ c “ festgelegt sind.

Dies kann nur aufgerufen werden, wenn für die gebundene Pipeline „ QRhiGraphicsPipeline::UsesBlendConstants “ festgelegt ist.

void QRhiCommandBuffer::setComputePipeline(QRhiComputePipeline *ps)

Zeichnet eine neue Rechenpipeline auf ps.

void QRhiCommandBuffer::setGraphicsPipeline(QRhiGraphicsPipeline *ps)

Zeichnet Befehle auf, die eine neue Grafik-Pipeline festlegen: ps.

Das Festlegen einer Grafikpipeline ohne das Flag „ UsesScissor “ deaktiviert entweder das Scissoring bei Grafik-APIs, bei denen dies möglich ist, oder legt das Scissor-Rechteck so fest, dass es mit dem zuletzt festgelegten Viewport übereinstimmt (bei Grafik-APIs, bei denen das Scissoring praktisch immer aktiv ist), um ein einheitliches Verhalten über alle „ QRhi “-Backends hinweg zu gewährleisten.

void QRhiCommandBuffer::setScissor(const QRhiScissor &scissor)

Speichert das aktive Scherenrechteck, das unter „ scissor “ festgelegt wurde.

Diese Funktion kann nur aufgerufen werden, wenn für die gebundene Pipeline das Flag „ UsesScissor “ gesetzt ist. Ist das Flag für die aktive Pipeline gesetzt, muss diese Funktion aufgerufen werden, da der Scheren-Test aktiviert wird und daher ein Scherenrechteck angegeben werden muss.

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

Datensätze, die eine Reihe von Shader-Ressourcen – wie beispielsweise Uniform-Puffer oder Texturen – bündeln, die für eine oder mehrere Shader-Stufen sichtbar gemacht werden.

srb kann null sein; in diesem Fall wird das zugehörige ` QRhiShaderResourceBindings ` der aktuellen Grafik- oder Rechenpipeline verwendet. Wenn ` srb ` nicht null ist, muss es ` layout-compatible` sein, d. h., das Layout (Anzahl der Bindungen, Typ und Bindungsnummer jeder Bindung) muss vollständig mit dem ` QRhiShaderResourceBindings ` übereinstimmen, das zum Zeitpunkt des Aufrufs von `create()` der Pipeline zugeordnet war.

Es gibt Fälle, in denen ein scheinbar unnötiger Aufruf von `setShaderResources()` zwingend erforderlich ist: beim Neuerstellen einer Ressource, auf die von ` srb` verwiesen wird, beispielsweise beim Ändern der Größe einer ` QRhiBuffer `, gefolgt von einem Aufruf von ` QRhiBuffer::create()`, an dieser Stelle werden die zugehörigen nativen Objekte (wie z. B. Deskriptorsätze im Fall von Vulkan) aktualisiert, damit sie auf die aktuellen nativen Ressourcen verweisen, die die von srb referenzierten Objekte QRhiBuffer, QRhiTexture und QRhiSampler unterstützen. In diesem Fall muss `setShaderResources()` aufgerufen werden, auch wenn srb mit dem Wert des letzten Aufrufs identisch ist.

Wenn ` srb ` nicht null ist, wird garantiert, dass auf das ` QRhiShaderResourceBindings `-Objekt, mit dem die Pipeline in `create()` erstellt wurde, in keiner Form zugegriffen wird. Tatsächlich muss es zu diesem Zeitpunkt nicht einmal gültig sein: Es ist zulässig, das der Pipeline zugeordnete `srb` nach `create()` zu löschen und stattdessen bei jedem Aufruf von `setShaderResources()` explizit ein anderes, ` layout compatible `-Objekt anzugeben.

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

[since 6.9] void QRhiCommandBuffer::setShadingRate(const QSize &coarsePixelSize)

Setzt die Shading-Rate für die folgenden Draw-Calls auf „ coarsePixelSize “.

Der Standardwert ist 1x1.

Funktioniert nur, wenn die Funktion „ QRhi::VariableRateShading “ als unterstützt gemeldet wird und die im Befehlspuffer gebundenen „ QRhiGraphicsPipeline “ bei ihrer Erstellung „ QRhiGraphicsPipeline::UsesShadingRate “ deklariert haben.

Rufen Sie „ QRhi::supportedShadingRates()“ auf, um zu prüfen, welche Shading-Raten für eine bestimmte Sample-Anzahl unterstützt werden.

Wenn sowohl ein ` QRhiShadingRateMap ` als auch diese Funktion verwendet werden, wird für jede Kachel die höhere der beiden Shading-Raten verwendet. Derzeit gibt es keine Möglichkeit, das Verhalten des Kombinators zu steuern.

Diese Funktion wurde in Qt 6.9 eingeführt.

void QRhiCommandBuffer::setStencilRef(quint32 refValue)

Setzt den aktiven Stencil-Referenzwert auf „ refValue “.

Diese Funktion kann nur aufgerufen werden, wenn für die gebundene Pipeline „ QRhiGraphicsPipeline::UsesStencilRef “ gesetzt ist.

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

Speichert die Eingabebindungen der Knoten.

Der von nachfolgenden drawIndexed()-Befehlen verwendete Indexpuffer wird durch indexBuf, indexOffset und indexFormat festgelegt. indexBuf kann auf null gesetzt werden, wenn kein indexiertes Zeichnen erforderlich ist.

Vertex-Puffer-Bindungen werden gebündelt. startBinding gibt die Nummer der ersten Bindung 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 einen QRhiBuffer und einen Offset an.

Überflüssige Änderungen an Vertex-Eingaben und Indizes im selben Durchgang werden bei den meisten Backends automatisch ignoriert, sodass Anwendungen keine übermäßige Optimierung vornehmen müssen, um Aufrufe dieser Funktion zu vermeiden.

Nehmen wir als einfaches Beispiel einen Vertex-Shader mit zwei Eingaben:

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

und nehmen wir an, die Daten liegen im Interleaved-Format vor, wobei 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 folgenden Eingabelayouts 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), auf die zwei Eingänge verweisen. Bei der Aufzeichnung des Durchgangs können, sobald die Pipeline eingerichtet ist, die Vertex-Bindungen einfach wie folgt festgelegt werden, vorausgesetzt, „vbuf“ ist der „ QRhiBuffer “ mit allen verschachtelten Positions- und Farbdaten:

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

void QRhiCommandBuffer::setViewport(const QRhiViewport &viewport)

Speichert das aktive Ansichtsfenster-Rechteck, das unter viewport angegeben ist.

Bei Backends, bei denen in der zugrunde liegenden Grafik-API das „Scissoring“ stets aktiviert ist, legt diese Funktion außerdem das „Scissor“-Rechteck so fest, dass es mit dem Ansichtsbereich übereinstimmt, sofern für das aktive „ QRhiGraphicsPipeline “ der Parameter „ UsesScissor “ nicht gesetzt ist.