QSGRenderNode Class

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

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

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

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

releaseResources()も参照のこと 。

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

この関数は、各ビットが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

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)

この関数はレンダラーによって呼び出され、QRhi を介して直接コマンドを呼び出すか、基礎となるグラフィックス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()も参照してください 。