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() 関数によって変更されたグラフィック状態を各ビットが表すマスクを返す必要があります。

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

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() とは異なり、この関数は、シーングラフが基になるコマンドバッファ上で現在のフレームのレンダリングパスの記録を開始する前に呼び出されます。これは、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を通じてグラフィックスリソース（バッファ、テクスチャ、レンダリングターゲット、フェンスなど）を直接割り当てていない場合、ここでは何も行う必要はありません。

すべてのカスタムリソースを解放しなかった場合、一部のシステムではグラフィックスデバイスが失われた際に、その後のグラフィックスシステムの再初期化が失敗し、不正な動作を引き起こす可能性があります。

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

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を引いた値となります。 例えば、頂点ごとに2つのfloat型(x-y)座標で構成されるレイアウトを想定した場合、アイテムの半分を覆う三角形は、反時計回りの方向で(width - 1, height - 1)、(0, 0)、(0, height - 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

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

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

QRhiGraphicsPipeline を構築するには（これにはQRhiRenderPassDescriptor の指定が必要となります）、レンダリングターゲットからrenderPassDescriptorを取得してください。 ただし、カスタムQQuickItem やQSGRenderNode の存続期間中に、レンダリングターゲットが変更される可能性があることに注意してください。例えば、アイテムまたはその祖先に対してlayer.enabled: true を動的に設定した場合を考えてみてください。これにより、ウィンドウへの直接レンダリングではなく、テクスチャへのレンダリングがトリガーされます。つまり、それ以降、QSGRenderNode は異なるレンダリングターゲットで動作することになります。 新しいレンダリングターゲットではピクセルフォーマットが異なる場合があり、その結果、すでに構築済みのグラフィックスパイプラインとの互換性が失われる可能性があります。この問題には、次のようなロジックで対処できます。

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()も参照してください 。