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 でない場合、それは でなければなりません。つまり、レイアウト（バインディングの数、各バインディングのタイプとバインディング番号）は、パイプラインの 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 セットされていないときはいつでも、この関数はビューポートに一致するようにシザーもセットします。