QRhiCommandBuffer Class

メンバ関数ドキュメント

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

新しいコンピュート・パスの開始を記録する。

resourceUpdatesNULLでない場合は、コミットされ、その後リリースされるリソース更新バッチを指定します。

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

void QRhiCommandBuffer::beginExternal()

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

Vulkan、Metal、または Direct3D 12 では、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 を対象とした新しいレンダーパスの開始を記録する。

resourceUpdatesNULLでない場合、コミットされ、その後リリースされるリソース更新バッチを指定します。

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

rt がQRhiTextureRenderTarget の場合、beginPass() は、レンダーターゲットから参照されるテクスチャとレンダーバッファオブジェクトが最新であるかどうかのチェックを実行する。これは、QRhiShaderResourceBindings に対してsetShaderResources() が行うことと同様である。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 特定の高度な機能を制御できるようにします。よく使われるフラグの1つは です。これは、この関数によって開始されるパス内で () が呼び出されるときは常に指定する必要があります。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() で指定します。

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

vertexOffset ( とも呼ばれる) は符号付き値で、頂点バッファにインデックスを付ける前に要素インデックスに追加されます。この値は、 がサポートされていないと報告された場合は無視されます。base vertex QRhi::BaseVertex

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

現在のコンピュートパスを終了するレコード。

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

void QRhiCommandBuffer::endExternal()

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

beginExternal() およびnativeHandles()も参照 。

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

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

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

beginPass()も参照 。

double QRhiCommandBuffer::lastCompletedGpuTime()

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

値の精度と粒度は Qt では制御できないことが多く、基盤となるグラフィックス API とその実装に依存するため、値の解釈には注意が必要です。特に、異なるグラフィックスAPIやハードウェア間で値を比較することは推奨されませんし、意味がないかもしれません。

フレームがbeginFrame() とendFrame() で記録された場合、つまりスワップチェーンで記録された場合、タイミング値はおそらく非同期で利用可能になります。そのため、返される値は0（最初の1～2フレームなど）であったり、ある前のフレームを参照した最後の既知の値であったりします。また、ウィンドウのサイズを変更した場合など、特定の条件下では値が再び0になることもあります。利用可能な最新の値は beginFrame() で取得され、beginFrame() が返ると、この関数で問い合わせ可能になることが期待できます。

一方、オフスクリーンフレームでは、endOffscreenFrame() が返ると、返される値は最新のものになります。これは、オフスクリーンフレームでは GPU のパイプライン処理が削減され、コマンドが完了するのを待つからです。

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

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

const QRhiNativeHandles *QRhiCommandBuffer::nativeHandles()

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

QRhiVulkanCommandBufferNativeHandles 、QRhiMetalCommandBufferNativeHandles 、beginExternal()、endExternal()も参照 。

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

再実装：QRhiResource::resourceType() const.

リソース型を返します。

void QRhiCommandBuffer::resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates)

リソースの更新をコミットすることが必要な場合や、レンダーパスを開始しない方が便利な場合がある。この関数をresourceUpdates で呼び出すと、beginPass() 呼び出しにresourceUpdates を渡す代わりに使用できます（リードバックの場合はendPass() が一般的です）。

void QRhiCommandBuffer::setBlendConstants(const QColor &c)

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

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

void QRhiCommandBuffer::setComputePipeline(QRhiComputePipeline *ps)

新しい計算パイプラインps の設定を記録する。

void QRhiCommandBuffer::setGraphicsPipeline(QRhiGraphicsPipeline *ps)

新しいグラフィックスパイプラインps の設定を記録する。

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 であってもよく、その場合は現在のグラフィックスまたはコンピュートパイプラインの関連する が使用されます。 が NULL でない場合、それは でなければなりません。つまり、レイアウト（バインディングの数、各バインディングのタイプとバインディング番号）は、パイプラインの create() を呼び出した時点でパイプラインに関連付けられていた と完全に一致しなければなりません。QRhiShaderResourceBindings srb layout-compatible QRhiShaderResourceBindings

一見不要に見える setShaderResources() 呼び出しが必須である場合があります。srb から参照されるリソースを再構築するとき、たとえばQRhiBuffer のサイズを変更し、その後にQRhiBuffer::create() が続く場合、これは関連するネイティブオブジェクト（Vulkan の場合はディスクリプタセットなど）が更新され、srb から参照されるQRhiBuffer,QRhiTexture,QRhiSampler オブジェクトをバックする現在のネイティブリソースを参照する場所です。この場合、setShaderResources() は、srb が前回の呼び出しと同じであっても呼び出されなければならない。

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

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

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;

このシェーダでは、 を呼び出すことができます。このシェーダ用のQRhiGraphicsPipeline は、入力レイアウトを使用して作成できます：

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

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

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

void QRhiCommandBuffer::setViewport(const QRhiViewport &viewport)

viewport で指定されたアクティブビューポート矩形の設定を記録する。

基礎となるグラフィックスAPIが常にシザリングを有効にしているバックエンドでは、アクティブなQRhiGraphicsPipeline がUsesScissor を設定していないときはいつでも、この関数はビューポートに一致するようにシザリングも設定します。