QRhiCommandBuffer Class

メンバ関数のドキュメント

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

新しい演算パスを開始するレコード。

resourceUpdates, null でない場合、コミットされた後に解放されるリソース更新バッチを指定します。

flags は現在使用されていません。

void QRhiCommandBuffer::beginExternal()

直前のアプリケーションが、グラフィックスAPI関数を直接呼び出して、現在のパス用のコマンドバッファにコマンドをキューに入れようとしている際に呼び出されます。

Vulkan、Metal、または Direct3D 11 では、nativeHandles() を通じてネイティブのコマンドバッファまたはエンコーダオブジェクトを照会し、それらにコマンドをキューイングすることができます。OpenGL または Direct3D 11 では、QRhi::nativeHandles() から（デバイス）コンテキストを取得できます。 ただし、QRhiCommandBuffer の状態が常に最新であることを確認せずに、この操作を行ってはなりません。そのため、外部から追加されたコマンド記録は、beginExternal()とendExternal()の間にラップする必要があります。概念的には、これはQPainter のbeginNativePainting()およびendNativePainting()関数と同じです。

特に OpenGL の場合、この関数には追加の役割があります。それは、現在のスレッド上でコンテキストがアクティブになることを保証することです。

endExternal() およびnativeHandles()も参照してください 。

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

レンダリングターゲット「rt 」を対象とする新しいレンダリングパスを開始するレコード。

resourceUpdatesが null でない場合、コミットされた後に解放されるリソース更新バッチを指定します。

通常、レンダリングターゲットの色バッファおよび深度/ステンシルバッファはクリアされます。クリア値は、colorClearValue およびdepthStencilClearValue で指定されます。ただし、レンダリングターゲットがQRhiTextureRenderTarget::PreserveColorContents および/またはQRhiTextureRenderTarget::PreserveDepthStencilContents で作成された場合は例外です。その場合、クリア値は無視されます。

rt がQRhiTextureRenderTarget である場合、beginPass()は、レンダリングターゲットから参照されるテクスチャおよびレンダリングバッファオブジェクトが最新であるかどうかを確認します。 これは、setShaderResources()がQRhiShaderResourceBindings に対して行う処理と類似しています。QRhiTextureRenderTarget::create()以降にアタッチメントのいずれかが再構築されていた場合、rt に対してcreate()への暗黙的な呼び出しが行われます。したがって、rt にQRhiTexture カラーアタッチメントtexture があり、そのテクスチャのサイズを変更する必要がある場合、以下の記述は有効です：

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 特定の高度な機能を制御できるようにします。よく使用されるフラグの一つにExternalContents があります。この関数によって開始されたパス内でbeginExternal()が呼び出される場合は、常にこれを指定する必要があります。

endPass() およびBeginPassFlagsも参照してください 。

void QRhiCommandBuffer::debugMarkBegin(const QByteArray &name)

指定されたname を使用して、コマンドバッファに名前付きデバッググループを記録します。これは、RenderDocや XCodeなどのグラフィックスデバッグツールに表示されます。グループ化の終了は、debugMarkEnd()によって示されます。

void QRhiCommandBuffer::debugMarkEnd()

デバッググループの終了を記録します。

void QRhiCommandBuffer::debugMarkMsg(const QByteArray &msg)

コマンドストリームにデバッグメッセージ「msg 」を挿入します。

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

x 、y 、z を使用して、対応する次元におけるローカルワークグループの数を指定し、コンピュートワークアイテムをディスパッチします。

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

インデックスなしの描画を記録します。

頂点数はvertexCount で指定されます。インスタンス化された描画を行う場合は、instanceCount を1以外の値に設定してください。firstVertex は、最初に描画する頂点のインデックスです。複数のインスタンスを描画する場合、最初のインスタンスIDはfirstInstance で指定されます。

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

インデックス付きドローを記録します。

頂点数はindexCount で指定されます。firstIndex はベースインデックスです。インデックスバッファ内の実効オフセットは、indexOffset + firstIndex * n で与えられます。ここで、n はインデックス要素の型に応じて2または4となります。indexOffset はsetVertexInput()で指定されます。

vertexOffset （base vertex とも呼ばれる）は、頂点バッファへのインデックス指定の前に要素インデックスに加算される符号付き値です。この機能は常に利用可能とは限らず、QRhi::BaseVertex 機能が非対応と報告された場合、この値は無視されます。

インスタンス化された描画を行う場合は、instanceCount を1以外の値に設定してください。複数のインスタンスを描画する場合、最初のインスタンスIDはfirstInstance によって指定されます。

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

インデックス付きの間接描画を記録します。

描画パラメータは、indirectBuffer で指定されたバッファによって提供されます。このバッファには、QRhiIndexedIndirectDrawCommand 型の要素からなる配列が含まれている必要があります。QRhiIndexedIndirectDrawCommand 内のパラメータの意味は、drawIndexed()の場合と同じです。

バッファ内からパラメータを読み取る開始位置（バイト単位）は、indirectBufferOffset で指定されます。

drawCount 発行するこのような描画コマンドの数を指定します。

stride は、バッファ内の個々の描画コマンド構造体のバイトサイズを示します。これにより、必要に応じてコマンド間にカスタムデータを挟み込むことができます。この値は 4 の倍数であり、かつ sizeof(QRhiIndexedIndirectDrawCommand) 以上でなければなりません。

この関数は Qt 6.12 で導入されました。

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

インデックス化されていない間接描画を記録します。

読み取りパラメータは、indirectBuffer で指定されたバッファによって提供されます。このバッファには、QRhiIndirectDrawCommand 型の要素からなる配列が含まれている必要があります。QRhiIndirectDrawCommand 内のパラメータの意味は、draw()の場合と同じです。

バッファ内からパラメータを読み取る開始位置（バイト単位）は、indirectBufferOffset で指定されます。

drawCount 発行するこのような描画コマンドの数を指定します。

stride は、バッファ内の個々の描画コマンド構造体のバイトサイズを示します。これにより、必要に応じてコマンド間にカスタムデータを挟み込むことができます。この値は 4 の倍数であり、かつ sizeof(QRhiIndirectDrawCommand) 以上である必要があります。

この関数は Qt 6.12 で導入されました。

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

現在の計算パスを終了するレコード。

resourceUpdates, nullでない場合、コミットされた後に解放されるリソース更新バッチを指定します。

void QRhiCommandBuffer::endExternal()

外部から追加されたコマンドがコマンドバッファまたはコンテキストに記録された後に一度呼び出されます。

beginExternal() およびnativeHandles()も参照してください 。

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

現在のレンダリングパスを終了するレコード。

resourceUpdates, nullでない場合、コミットされた後に解放されるリソース更新バッチを指定します。

beginPass()も参照してください 。

double QRhiCommandBuffer::lastCompletedGpuTime()

QRhi の作成時にQRhi::EnableTimestamps が有効になっていた場合、利用可能な最新のタイムスタンプを秒単位で返します。この値は、最後に完了したフレームの処理中にGPU上で経過した時間を示します。

値の解釈には注意が必要です。その精度と粒度は多くの場合 Qt によって制御されておらず、基盤となるグラフィックス API およびその実装に依存するからです。特に、異なるグラフィックス API やハードウェア間の値を比較することは推奨されず、意味をなさない場合があります。

タイミング値は非同期的に利用可能になる可能性が高いです。そのため、戻り値は 0 になる場合（例：最初の 1～2 フレーム）や、以前のフレームを参照する最後の既知の値になる場合があります。 また、ウィンドウのサイズ変更時など、特定の条件下では値が再び 0 になることもあります。beginFrame() 内で利用可能な最新の値が取得され、beginFrame() が返却された後にこの関数を通じてその値を照会できるようになると予想されます。

プラットフォームによっては、GPU 周波数スケーリングや GPU クロックの変化による影響に注意してください。たとえば、Windows では、最新のグラフィックスカードを使用している場合、類似または同一のワークロードでフレームを送信しても、フレーム間の返されるタイミングがかなり広い範囲で変動することがあります。一般的に言えば、これは Qt が制御・解決できる範囲外です。 ただし、D3D12バックエンドは、環境変数QT_D3D_STABLE_POWER_STATE が0以外の値に設定されている場合、自動的にID3D12Device::SetStablePowerState()を呼び出します。 これにより、結果が大幅に安定化します。また、特にオフスクリーンフレームが関与する場合、QElapsedTimer などを介して測定されるCPU側のタイミングにも、無視できない影響を与える可能性があります。

「 QRhi::Timestamps 」および「QRhi::EnableTimestamps 」も参照してください 。

const QRhiNativeHandles *QRhiCommandBuffer::nativeHandles()

バックエンド固有のQRhiNativeHandles サブクラス（例：QRhiVulkanCommandBufferNativeHandles ）へのポインタを返します。バックエンドが基盤となるネイティブリソースの公開をサポートしていない場合、または適用できない場合は、戻り値はnullptr となります。

QRhiVulkanCommandBufferNativeHandles 、QRhiMetalCommandBufferNativeHandles 、beginExternal()、およびendExternal()も参照してください 。

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

QRhiResource::resourceType() const を再実装します。

リソースの型を返します。

void QRhiCommandBuffer::resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates)

場合によっては、レンダリングパスを開始せずにリソースの更新をコミットする必要がある、あるいは単にその方が便利なことがあります。resourceUpdates を引数としてこの関数を呼び出すことは、beginPass()の呼び出し（または、リードバックの場合に典型的なendPass()）にresourceUpdates を渡すことの代替手段となります。

void QRhiCommandBuffer::setBlendConstants(const QColor &c)

アクティブなブレンド定数をc に設定するレコード。

これは、バインドされたパイプラインでQRhiGraphicsPipeline::UsesBlendConstants が設定されている場合にのみ呼び出すことができます。

void QRhiCommandBuffer::setComputePipeline(QRhiComputePipeline *ps)

新しい演算パイプラインを設定するレコードps 。

void QRhiCommandBuffer::setGraphicsPipeline(QRhiGraphicsPipeline *ps)

新しいグラフィックスパイプラインを設定するレコード `ps`。

UsesScissor フラグを持たないグラフィックスパイプラインを設定すると、該当するグラフィックス API ではシザリングが無効になるか、QRhi バックエンド間で一貫した動作を確保するために、シザリングが事実上常に有効になっているグラフィックス API では、シザリング矩形が最後に設定されたビューポートに合わせて設定されます。

void QRhiCommandBuffer::setScissor(const QRhiScissor &scissor)

scissor で指定されたアクティブなシザー矩形を設定するレコード。

これは、バインドされたパイプラインでUsesScissor が設定されている場合にのみ呼び出すことができます。アクティブなパイプラインでこのフラグが設定されている場合、シザーテストが有効になるため、シザー矩形を指定する必要があることから、この関数を呼び出す必要があります。

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

1つ以上のシェーダーステージから参照可能となる、ユニフォームバッファやテクスチャなどのシェーダーリソースのセットをバインドするレコード。

srb nullに設定できる場合があり、その場合は現在のグラフィックスまたはコンピュートパイプラインに関連付けられたQRhiShaderResourceBindings が使用される。srb がnullでない場合、それはlayout-compatible でなければならない。つまり、レイアウト（バインディング数、各バインディングの型およびバインディング番号）は、パイプラインのcreate()を呼び出した時点でパイプラインに関連付けられていたQRhiShaderResourceBindings と完全に一致しなければならない。

一見不要に見える setShaderResources() の呼び出しが必須となる場合があります。例えば、srb から参照されているリソースを再構築する場合、QRhiBuffer のサイズを変更した後、QRhiBuffer::create() を呼び出す場合などです。 この時点で、関連するネイティブオブジェクト（Vulkan の場合の記述子セットなど）が更新され、srb から参照されるQRhiBuffer 、QRhiTexture 、QRhiSampler オブジェクトを裏付ける現在のネイティブリソースを指すようになります。この場合、srb が前回の呼び出し時と同じであっても、setShaderResources() を呼び出す必要があります。

srb がnullでない場合、create()でパイプラインの構築に使用されたQRhiShaderResourceBindings オブジェクトには、いかなる形でもアクセスされないことが保証されます。実際、この時点ではそのオブジェクトが有効である必要さえありません。create()の後にパイプラインに関連付けられたsrbを破棄し、代わりにsetShaderResources()の呼び出しごとに別のlayout compatible オブジェクトを明示的に指定することも有効です。

dynamicOffsets QRhiShaderResourceBinding::uniformBufferWithDynamicOffset()を介して に関連付けられたユニフォームバッファに対して、バッファオフセットを指定できるようにします。これは、 自体でオフセットを指定することとは異なります。動的オフセットでは、オフセットが異なるたびに新しい を構築する必要がなく、（該当するバックエンドでは）基となる記述子の書き込みを回避できるため、より効率的である可能性があります。 の各要素は、 と のペアです。 は、 に含まれる要素の数を指定します。srb srb QRhiShaderResourceBindings dynamicOffsets binding offset dynamicOffsetCount dynamicOffsets

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

以降の描画呼び出しのシェーディングレートをcoarsePixelSize に設定します。

デフォルトは 1x1 です。

この関数は、QRhi::VariableRateShading 機能がサポートされていると報告されており、かつコマンドバッファにバインドされたQRhiGraphicsPipeline が、作成時にQRhiGraphicsPipeline::UsesShadingRate を宣言している場合にのみ機能します。

QRhi::supportedShadingRates() を呼び出して、指定されたサンプル数に対してどのシェーディングレートがサポートされているかを確認してください。

QRhiShadingRateMap とこの関数の両方が使用されている場合、各タイルに対して 2 つのシェーディングレートのうち高い方が使用されます。現在、コンバイナの動作を制御する手段は提供されていません。

この関数は Qt 6.9 で導入されました。

void QRhiCommandBuffer::setStencilRef(quint32 refValue)

アクティブなステンシル参照値をrefValue に設定するレコード。

これは、バインドされたパイプラインでQRhiGraphicsPipeline::UsesStencilRef が設定されている場合にのみ呼び出すことができます。

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

頂点入力のバインディングを記録します。

後続のdrawIndexed()コマンドで使用されるインデックスバッファは、indexBuf 、indexOffset 、およびindexFormat によって指定されます。インデックス付き描画が必要ない場合は、indexBuf をnullに設定できます。

頂点バッファのバインディングはバッチ処理されます。startBinding は最初のバインディング番号を指定します。その後、記録されたコマンドは、bindings からstartBinding + i のバインディングポイントまで、各バッファをバインドします。ここで、i はbindings 内のインデックスです。bindings の各要素は、QRhiBuffer とオフセットを指定します。

同じパス内での余分な頂点入力およびインデックスの変更は、ほとんどのバックエンドで自動的に無視されるため、アプリケーションはこの関数の呼び出しを避けるために過度な最適化を行う必要はありません。

簡単な例として、2 つの入力を持つ頂点シェーダーを考えてみましょう。

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

また、データがインターリーブ形式で利用可能であり、位置情報に2つのfloatのみを使用すると仮定します（つまり、1頂点あたり5つのfloat：x、y、r、g、b）。このシェーダー用のQRhiGraphicsPipeline は、以下の入力レイアウトを使用して作成できます：

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

ここでは、1つのバッファバインディング（バインディング番号0）があり、2つの入力がそれを参照しています。パスを記録する際、パイプラインの設定が完了したら、vbufをインターリーブされた位置＋色データを含むQRhiBuffer と仮定して、頂点バインディングは次のように簡単に指定できます：

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

void QRhiCommandBuffer::setViewport(const QRhiViewport &viewport)

viewport で指定されたアクティブなビューポート矩形を設定するレコード。

基盤となるグラフィックスAPIでシザリングが常に有効になっているバックエンドの場合、この関数は、アクティブなQRhiGraphicsPipeline にUsesScissor が設定されていないときは、ビューポートに合わせてシザリングを設定します。