QSGRenderNode Class

メンバ関数の説明

[override virtual noexcept] QSGRenderNode::~QSGRenderNode()

レンダーノードをデストラクトします。派生クラスは、ここでreleaseResources() と同様のクリーンアップを実行することが期待される。

低レベルのグラフィックスAPIが使用されているとき、シーングラフは、シーングラフのノードが削除される前に、GPUがシーングラフのグラフィックスコマンドキューに提出されたすべての作業を完了するために、CPU側の待ち時間があることを確認します。したがって、render （）の実装が追加のコマンド・キューを使用していない限り、ここで追加の待ちを発行する必要はありません。

QRhi 、QRhiBuffer 、QRhiTexture 、QRhiGraphicsPipeline などのリソースでは、std::unique_ptr などのスマート・ポインタを使用すると、デストラクタを実装する必要がなくなり、ソース・コードがよりコンパクトになります。しかし、releaseResources() を実装し、unique_ptrに対して多くのreset()コールを発行することが重要であることに留意してください。

releaseResources()も参照のこと 。

[virtual] QSGRenderNode::StateFlags QSGRenderNode::changedStates() const

基礎となるレンダリングAPIがOpenGLである場合、この関数は、各ビットがrender() 関数によって変更されたグラフィックス状態を表すマスクを返す必要があります：

OpenGL以外のAPIでは、コマンドリスト/バッファに記録された動的な状態変化に対応する値のみが関連する。例えば、D3D11 の場合、RSSetViewports、RSSetScissorRects、OMSetBlendState、OMSetDepthStencilState、Vulkan の場合、vkCmdSetViewport、vkCmdSetScissor、vkCmdSetBlendConstants、vkCmdSetStencilRef などで、このようなコマンドが QSGRendererInterface を介して照会されたシーングラフのコマンドリストに追加された場合のみです：CommandList リソース列挙型(CommandList resource enum)を介して照会されたシーングラフのコマンドリストに追加された場合のみです。パイプライン状態オブジェクトに設定された状態は、ここで報告する必要はありません。同様に、描画呼び出しに関連する設定（パイプラインステート、記述子セット、頂点またはインデックスバッファバインディング、ルート署名、記述子ヒープなど）は、常にシーングラフによって再度設定されるため、render （）は自由に変更できます。

RenderTargetState は、Vulkan のような API ではサポートされなくなりました。これは性質によるものです。()は、Qt Quick scenegraphのメインコマンドバッファがレンダーパスを記録している間に呼び出されるため、ターゲットを変更して別のレンダーパスを開始する可能性はありません（少なくともそのコマンドバッファ上では）。そのため、 が設定された値を返すことは賢明ではありません。render RenderTargetState

この関数はレンダラーによって呼び出されるため、レンダラーはこのノードをレンダリングした後に状態をリセットできます。これにより、render （）の実装は、これらの状態を照会してリストアする必要がなくなるため、シンプルになる。

デフォルトの実装では、render() で関連する状態が変更されなかったことを意味する 0 を返します。

const QSGClipNode *QSGRenderNode::clipList() const

現在のクリップリストを返します。

[since 6.6] QRhiCommandBuffer *QSGRenderNode::commandBuffer() const

現在のコマンドバッファを返します。

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

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

[virtual] QSGRenderNode::RenderingFlags QSGRenderNode::flags() const

レンダーノードの動作を表すフラグを返します。

デフォルトの実装は 0 を返します。

RenderingFlag およびrect() も参照して ください。

qreal QSGRenderNode::inheritedOpacity() const

現在の実効不透明度を返します。

const QMatrix4x4 *QSGRenderNode::matrix() const

現在のモデルビュー行列へのポインタを返します。

[virtual, since 6.0] void QSGRenderNode::prepare()

フレーム準備フェーズから呼び出されます。render() を呼び出すたびに、その前にこの関数が呼び出されます。

render() とは異なり、この関数は、scenegraph が現在のフレームのレンダーパスを基礎となるコマンドバッファに記録し始める前に呼び出されます。これは、コピータイプの操作がレンダーパスの前に記録される必要がある、VulkanなどのグラフィックスAPIでレンダリングを行う場合に便利です。

デフォルトの実装は空です。

レンダリングにQRhi を使用するQSGRenderNode を実装する場合は、QQuickWindow::rhi() を介してQQuickWindow からQRhi オブジェクトを照会します。作業を提出するためのQRhiCommandBuffer を取得するには、commandBuffer() を呼び出す。アクティブなレンダーターゲットに関する情報を照会するには、renderTarget （）を呼び出します。詳細は{Scene Graph - Custom QSGRenderNode} の例を参照してください。

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

[since 6.5] const QMatrix4x4 *QSGRenderNode::projectionMatrix() const

現在の投影行列へのポインタを返します。

render() では、これは RenderState::projectionMatrix() から返されるのと同じ行列です。このゲッターが存在するのは、prepare() にも投影行列を問い合わせる方法があるためです。

最新のグラフィックスAPIや、Qt自身のグラフィックス抽象化レイヤで作業する場合、*projectionMatrix() * *matrix() を均一なバッファにロードしたい場合が多いでしょう。しかし、これはprepare() で行う必要があるため、レンダリングパスの記録外です。そのため、prepare() とrender() の両方で、QSGRenderNode から直接行列を問い合わせることができます。

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

[virtual] QRectF QSGRenderNode::rect() const

この関数は、Qt 6.5 で導入されました。render() が触れている領域の外接矩形をアイテム座標で返します。この値は、flags() がBoundedRectRendering を含む場合にのみ使用され、それ以外の場合は無視されます。

BoundedRectRendering と組み合わせて矩形を報告することは、software バックエンドで特に重要です。そうしないと、シーンにレンダーノードがある場合、フルスクリーン更新がトリガされ、すべての部分更新の最適化がスキップされるからです。

対応するQQuickItem の全領域をカバーするレンダーノードの場合、戻り値は (0, 0, item->width(), item->height()) になります。

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

[virtual] void QSGRenderNode::releaseResources()

この関数は、このノードによって割り当てられたすべてのカスタム・グラフィックス・リソースを直ちに解放する必要があるときに呼び出されます。ノードが使用中のグラフィックスAPIを通じて直接グラフィックスリソース（バッファ、テクスチャ、レンダーターゲット、フェンスなど）を割り当てていない場合、ここで行うことはありません。

すべてのカスタムリソースの解放に失敗すると、システムによっては、グラフィックスデバイスの損失シナリオで、その後のグラフィックスシステムの再初期化に失敗する可能性があるため、正しくない動作につながる可能性があります。

デストラクタとは異なり、releaseResources()を呼び出した後にrender() を呼び出すと、必要なすべてのリソースを再初期化できることが期待されます。

OpenGLの場合、シーングラフのOpenGLコンテキストは、デストラクタとこの関数を呼び出すときの両方が最新になります。

[pure virtual] void QSGRenderNode::render(const QSGRenderNode::RenderState *state)

この関数はレンダラーによって呼び出され、現在使用されているグラフィックスAPI（OpenGL、Direct3Dなど）のコマンドを直接呼び出して、このノードをペイントする必要があります。

有効不透明度はinheritedOpacity() で取得できます。

投影行列はstate で取得でき，モデルビュー行列はmatrix() で取得できます．結合行列は，射影行列にモデルビュー行列を掛けたものになります．シーン内のアイテムの正しいスタッキングは、投影行列によって保証されます。

提供された行列を使用する場合、頂点データの座標系は通常のQQuickItem の規約に従います：左上は (0, 0)、右下は対応するQQuickItem の width() と height() から 1 を引いた値です。例えば、1頂点あたり2浮動小数点（x-y）の座標レイアウトを仮定すると、アイテムの半分をカバーする三角形は、反時計回りで（幅 - 1、高さ - 1）、（0、0）、（0、高さ - 1）と指定できます。

クリップ情報は、関数が呼び出される前に計算されます。クリッピングを考慮したい実装は、state の情報に基づいて、シザリングまたはステンシルを設定できます。ステンシルバッファは必要なクリップ形状で満たされますが、ステンシルテストを有効にするかどうかは実装次第です。

いくつかのシーングラフバックエンド（特にソフトウェア）は、シザーやステンシルを使用しません。そこでは、クリップ領域は通常のQRegion として提供されます。

レンダリングにQRhi を使用するQSGRenderNode を実装する場合、QQuickWindow::rhi() を介してQQuickWindow からQRhi オブジェクトをクエリします。作業提出用のQRhiCommandBuffer を取得するには、commandBuffer() を呼び出します。アクティブなレンダーターゲットに関する情報を照会するには、renderTarget （）を呼び出します。詳しくは{Scene Graph - Custom QSGRenderNode}の例を参照してください。

Qt 6とそのQRhi-ベースのシーングラフ・レンダラでは、OpenGLが使用中であっても、この関数が呼び出されたときにアクティブ（OpenGL）状態について仮定すべきではありません。この関数が呼び出されたときに、コマンドリスト/バッファにバインドされているパイプラインと動的な状態については、何も仮定しないでください。

いくつかのグラフィックスAPIでは、QRhi を直接使用する場合も含めて、prepare() を再実装するか、QQuickWindow::beforeRendering() シグナルに接続する必要があります。これらは、コマンドバッファにレンダーパスの開始を記録する（Vulkanの場合はvkCmdBeginRenderPass、Metalの場合はMTLRenderCommandEncoderを介してエンコードを開始する）前に呼び出され、発信されます。このようなAPIでは、render()内でコピー操作を記録することはできません。そのような操作は、prepare （）か、（DirectConnectionで）beforeRenderingに接続されたスロットで行ってください。

QSGRendererInterface およびQQuickWindow::rendererInterface()も参照 。

[since 6.6] QRhiRenderTarget *QSGRenderNode::renderTarget() const

現在のレンダーターゲットを返します。

これは主に、QRhiRenderTarget のrenderPassDescriptor またはpixel size にアクセスするQRhi を使用するprepare() およびrender() の実装を有効にするために提供される。

QRhiGraphicsPipeline を構築するには、QRhiRenderPassDescriptor を提供する必要があり、レンダーターゲットから renderPassDescriptor を問い合わせる必要がある。QSGRenderNode しかし、レンダーターゲットは、カスタムQQuickItem とQSGRenderNode のライフタイムの間に変更される可能性があることに注意してください。たとえば、アイテムまたはその祖先にlayer.enabled: true を動的に設定するときに何が起こるかを考えてみましょう。これは、ウィンドウに直接レンダリングするのではなく、テクスチャにレンダリングすることをトリガーします。新しいレンダーターゲットは異なるピクセルフォーマットを持つ可能性があり、すでに構築されたグラフィックスパイプラインに互換性がなくなる可能性があります。これは、次のようなロジックで処理できます：

if (m_pipeline && renderTarget()->renderPassDescriptor()->serializedFormat() != m_renderPassFormat) {
    delete m_pipeline;
    m_pipeline = nullptr;
}
if (!m_pipeline) {
    // Build a new QRhiGraphicsPipeline.
    // ...
    // Store the serialized format for fast and simple comparisons later on.
    m_renderPassFormat = renderTarget()->renderPassDescriptor()->serializedFormat();
}

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

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