QQuickRhiItemRenderer Class

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

QQuickRhiItemRenderer::QQuickRhiItemRenderer()

新しいレンダラーを構築します。

この関数は、GUIスレッドがブロックされている間に、シーングラフの同期フェーズ中にレンダリングスレッドから呼び出されます。

QQuickRhiItem::createRenderer()も参照してください 。

[virtual noexcept] QQuickRhiItemRenderer::~QQuickRhiItemRenderer()

QQuickRhiItem 項目のシーングラフリソースがクリーンアップされると、レンダラーは自動的に削除されます。

この関数はレンダリングスレッド上で呼び出されます。

特定の条件下では、レンダラーオブジェクトが破棄された後に再作成されることが正常であり、想定される動作です。これは、レンダラーのライフサイクルが、実質的に基になるシーングラフノードに従うためです。たとえば、QQuickRhiItem オブジェクトの親を変更して、別のQQuickWindow に属するようにした場合、ウィンドウの変更に伴い、シーングラフノードはすべて破棄され、再作成されます。 これに伴い、QQuickRhiItemRenderer も破棄され、新しいものが作成されます。

QRhiWidget とは異なり、QQuickRhiItemRenderer は、QRhi を介して作成されたグラフィックスリソースを解放（または早期解放）するための追加のコードパスを実装する必要はありません。デストラクタ内ですべてを解放するか、スマートポインタに依存するだけで十分です。

[protected] QRhiTexture *QQuickRhiItemRenderer::colorTexture() const

そのアイテムの色バッファとして機能するテクスチャを返します。

initialize() およびrender() からのみ呼び出す必要があります。

深度・ステンシルバッファやQRhiRenderTarget とは異なり、このテクスチャは常に利用可能であり、isAutoRenderTargetEnabled の値に関係なく、QQuickRhiItem によって管理されます。

msaaColorBuffer()、depthStencilBuffer()、renderTarget()、およびresolveTexture()も参照してください 。

[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::depthStencilBuffer() const

そのアイテムのレンダリングで使用される深度・ステンシルバッファを返します。

initialize() およびrender() からのみ呼び出す必要があります。

isAutoRenderTargetEnabled がtrue である場合にのみ利用可能です。それ以外の場合は、戻り値はnullptr となり、深度・ステンシルバッファおよびQRhiTextureRenderTarget の作成と管理は、initialize()の再実装に委ねられます。

colorTexture() およびrenderTarget()も参照してください 。

[pure virtual protected] void QQuickRhiItemRenderer::initialize(QRhiCommandBuffer *cb)

この関数は、アイテムが初めて初期化されたとき、関連付けられたテクスチャのサイズ、フォーマット、またはサンプル数が変更されたとき、あるいは何らかの理由でQRhi やテクスチャが変更されたときに呼び出されます。この関数は、render()内のレンダリングコードで使用されるグラフィックスリソースを維持すること（まだ作成されていない場合は作成し、サイズが変更された場合は調整および再構築すること）が求められます。

QRhi 、QRhiTexture 、およびその他の関連オブジェクトを照会するには、rhi()、colorTexture()、depthStencilBuffer()、およびrenderTarget()を呼び出します。

項目のサイズが変更された場合、QRhi オブジェクト、カラーバッファテクスチャ、および深度・ステンシルバッファオブジェクトはすべて以前と同じインスタンス（したがって、ゲッターは同じポインタを返す）ですが、カラーバッファおよび深度・ステンシルバッファは再構築されている可能性が高く、つまりsize および基盤となるネイティブテクスチャリソースは、前回の呼び出し時とは異なる場合があります。

また、この関数の呼び出し間で `QRhi ` オブジェクトやカラーバッファテクスチャが変更される可能性があることも想定して、再実装を行う必要があります。 例えば、アイテムが新しいQQuickWindow に属するように再親付けされた場合、この関数のその後の呼び出しにおいて、QRhi およびQQuickRhiItem によって管理されるすべての関連リソースは、以前とは異なるインスタンスになります。その場合、サブクラスによって以前に作成された既存のQRhi リソースは、もはや使用すべきではない以前のQRhi に属しているため、それらをすべて破棄することが重要です。

isAutoRenderTargetEnabled がtrue （デフォルト値）に設定されている場合、colorTexture()（またはmsaaColorBuffer()）および深度・ステンシルバッファに関連付けられた深度・ステンシルQRhiRenderBuffer とQRhiTextureRenderTarget が自動的に作成・管理されます。initialize()およびrender()の再実装では、depthStencilBuffer()およびrenderTarget()を介してこれらのオブジェクトを照会できます。isAutoRenderTargetEnabled がfalse に設定されている場合、これらのオブジェクトは自動的に作成・管理されなくなります。その代わりに、initialize()の実装側で、適宜バッファを作成し、レンダリングターゲットを設定することになります。 レンダリングターゲットの追加の色または深度・ステンシルアタッチメントを手動で管理する場合、それらのサイズとサンプル数は常にcolorTexture()（またはmsaaColorBuffer()）のサイズとサンプル数に従わなければなりません。そうしないと、レンダリングエラーや 3D API 検証エラーが発生する可能性があります。

サブクラスによって作成されたグラフィックスリソースは、サブクラスのデストラクタの実装内で解放されることが想定されています。

cb は、現在のフレームのQRhiCommandBuffer です。この関数は、フレームが記録されているが、アクティブなレンダリングパスがない状態で呼び出されます。コマンドバッファは、主にrender() に委譲することなく、resource updates をキューに入れるために提供されます。

この関数は、レンダースレッドが存在する場合、そのスレッド上で呼び出されます。

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

[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::msaaColorBuffer() const

そのアイテムのマルチサンプルカラーバッファとして機能するレンダリングバッファを返します。

initialize() およびrender() からのみ呼び出さなければなりません。

sampleCount が1より大きく、マルチサンプルアンチエイリアシングが有効になっている場合、返されるQRhiRenderBuffer はそれに対応するサンプル数を持ち、カラーバッファとして機能します。このバッファにレンダリングするために使用されるグラフィックスパイプラインは、同じサンプル数で作成されている必要があり、深度・ステンシルバッファのサンプル数も一致している必要があります。 マルチサンプルコンテンツは、resolveTexture() から返されるテクスチャに解決されることが想定されています。isAutoRenderTargetEnabled がtrue の場合、renderTarget()は自動的にこの処理を行うように設定され、msaaColorBuffer()がカラーアタッチメント0のrenderbuffer として、resolveTexture()がそのresolveTexture として設定されます。

MSAAが使用されていない場合、戻り値はnullptr となります。その場合は、代わりにcolorTexture()を使用してください。

基盤となる 3D グラフィックス API によっては、マルチサンプルテクスチャとサンプル数が 1 より大きいカラーレンダーバッファとの間に実質的な違いがない場合があります（QRhi は、両方を同じネイティブリソース型にマッピングするだけの場合があります）。 ただし、一部の古いAPIでは、テクスチャとレンダリングバッファを区別している場合があります。マルチサンプルレンダリングバッファは利用可能ですが、マルチサンプルテクスチャは利用できないOpenGL ES 3.0に対応するため、QQuickRhiItem は常に、カラーアタッチメントとしてマルチサンプルQRhiRenderBuffer を使用し（マルチサンプルQRhiTexture は決して使用しません）、MSAAを実行します。

colorTexture()、depthStencilBuffer()、renderTarget()、およびresolveTexture()も参照してください 。

[pure virtual protected] void QQuickRhiItemRenderer::render(QRhiCommandBuffer *cb)

背景色バッファの内容を更新する必要があるときに呼び出されます。

この関数が呼び出される前には、必ず少なくとも1回はinitialize()が呼び出されます。

更新を要求するには、QML またはメイン/GUI スレッド上の C++ コードから呼び出す場合（プロパティのセッター内など）、QQuickItem::update() を呼び出し、QQuickRhiItemRenderer コールバック内から呼び出す場合はupdate() を呼び出します。render() 内からQQuickRhiItemRenderer のupdate() を呼び出すと、更新が継続的にトリガーされます。

cb は、現在のフレームのQRhiCommandBuffer です。この関数は、フレームの記録中であるが、アクティブなレンダリングパスがない状態で呼び出されます。

この関数は、レンダリングスレッドが存在する場合、そのスレッド上で呼び出されます。

initialize() およびsynchronize()も参照してください 。

[protected] QRhiRenderTarget *QQuickRhiItemRenderer::renderTarget() const

render() の再実装において、QRhiCommandBuffer::beginPass() と組み合わせて使用する必要があるレンダリングターゲットオブジェクトを返します。

initialize() およびrender() からのみ呼び出される必要があります。

isAutoRenderTargetEnabled がtrue である場合にのみ利用可能です。それ以外の場合、戻り値はnullptr となり、深度・ステンシルバッファおよびQRhiTextureRenderTarget の作成と管理は、initialize() の再実装に委ねられます。

graphics pipelines renderPassDescriptor を作成する際には、 が必要です。これは、 を呼び出すことで、返された から取得できます。QRhiRenderPassDescriptor QRhiTextureRenderTarget

colorTexture()、depthStencilBuffer()、およびQQuickWindow::effectiveDevicePixelRatio()も参照してください 。

[protected] QRhiTexture *QQuickRhiItemRenderer::resolveTexture() const

マルチサンプルコンテンツが解像された、マルチサンプルではないテクスチャを返します。

マルチサンプルアンチエイリアシングが有効になっていない場合、結果はnullptr となります。

initialize() およびrender() からのみ呼び出す必要があります。

MSAA が有効になっている場合、これは、Qt Quick のメインレンダリングパスでクワッドにテクスチャを適用する際に、アイテムの基になるシーングラフノードによって使用されるテクスチャです。ただし、QQuickRhiItemRenderer のレンダリングは、msaaColorBuffer() から返される (マルチサンプル)QRhiRenderBuffer をターゲットにする必要があります。isAutoRenderTargetEnabled がtrue の場合、これはrenderTarget() から返されるQRhiRenderTarget によって処理されます。 それ以外の場合は、カラーバッファとリゾルブテクスチャの両方を含むレンダリングターゲットオブジェクトを正しく設定するのは、サブクラスのコードに委ねられます。

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

[protected] QRhi *QQuickRhiItemRenderer::rhi() const

現在のQRhi オブジェクトを返します。

initialize() およびrender() からのみ呼び出す必要があります。

[pure virtual protected] void QQuickRhiItemRenderer::synchronize(QQuickRhiItem *item)

この関数は、レンダースレッドが存在する場合、メイン／GUIスレッドがブロックされている間に、そのスレッド上で呼び出されます。これは the item's synchronize stepから呼び出され、メインスレッドおよびレンダリングスレッドに属するデータの読み書きを可能にします。通常、QQuickRhiItem に格納されたプロパティ値はQQuickRhiItemRenderer にコピーされるため、レンダリングスレッドとメインスレッドが並列に動作し続ける際、render()内で安全に読み取ることができます。

initialize() およびrender()も参照してください 。

[protected] void QQuickRhiItemRenderer::update()

オフスクリーンのカラーバッファの内容を更新する必要がある場合は、この関数を呼び出してください（つまり、render() の再呼び出しを要求するためです。この呼び出しは後ほど実行されますが、更新は通常、表示レートに合わせて調整される点に注意してください）。

この関数は、render() から呼び出して更新をスケジュールすることができます。