QRhi Class

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

[noexcept] QRhi::~QRhi()

デストラクタ。バックエンドを破棄し、リソースを解放します。

void QRhi::addCleanupCallback(const QRhi::CleanupCallback &callback)

QRhi が破棄された際に呼び出されるcallback を登録します。

このコールバックは、グラフィックリソースがまだ利用可能な状態で実行されるため、アプリケーションはQRhi に属するQRhiResource インスタンスを適切に解放することができます。これは、cache 型のオブジェクトに格納されたリソースのライフサイクルを管理する際に特に有用です。この種のオブジェクトのキャッシュには、QRhiResourceまたはQRhiResourceを含むオブジェクトが保持されています。

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

void QRhi::addCleanupCallback(const void *key, const QRhi::CleanupCallback &callback)

QRhi が破棄される際に呼び出されるcallback を登録します。このオーバーロードは、指定されたコールバックが1回だけ登録（および呼び出し）されることを保証するために使用される不透明ポインタkey を受け取ります。

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

QRhi::Implementation QRhi::backend() const

このQRhi のバックエンド型を返します。

const char *QRhi::backendName() const

このQRhi のバックエンド型を文字列として返します。

[static] const char *QRhi::backendName(QRhi::Implementation impl)

バックエンド `impl` の識別名を返します。通常、これは使用中の 3D API の名前になります。

QRhi::FrameOpResult QRhi::beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags = {})

swapChain の次に利用可能なバッファを対象として、新しいフレームを開始します。

フレームは、リソースの更新と、1つ以上のレンダリングパスおよび演算パスで構成されます。

flags は、特定の特殊なケースを示すことがあります。

スワップチェーンを使用してQWindow にレンダリングする大まかな手順は次のとおりです。

• スワップチェーンを作成します。
• サーフェスのサイズが以前と異なる場合は、QRhiSwapChain::createOrResize() を呼び出します。
• QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed 上でQRhiSwapChain::destroy()を呼び出します。
• その後、各フレームごとに：

  beginFrame(sc);
  updates = nextResourceUpdateBatch();
  updates->...
  QRhiCommandBuffer *cb = sc->currentFrameCommandBuffer();
  cb->beginPass(sc->currentFrameRenderTarget(), colorClear, dsClear, updates);
  ...
  cb->endPass();
  ... // more passes as necessary
  endFrame(sc);

成功した場合はQRhi::FrameOpSuccess を返し、失敗した場合は別のQRhi::FrameOpResult 値を返します。これらのうちいくつかは、ソフトな「後で再試行」タイプのエラーとして扱う必要があります。QRhi::FrameOpSwapChainOutOfDate が返された場合、QRhiSwapChain::createOrResize()を呼び出してスワップチェーンのサイズ変更または更新を行う必要があります。 その後、アプリケーションは新しいフレームの生成を試みる必要があります。QRhi::FrameOpDeviceLost が返された場合は、グラフィックスデバイスが失われたことを意味しますが、QRhi 自体を含むすべてのリソースを解放し、その後すべてのリソースを再作成することで回復できる場合もあります。詳細については、isDeviceLost()を参照してください。

endFrame()、beginOffscreenFrame()、およびisDeviceLost()も参照してください 。

QRhi::FrameOpResult QRhi::beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags = {})

新しいオフスクリーンフレームを開始します。cb でレンダリングコマンドを記録するのに適したコマンドバッファを提供します。flags は、beginFrame()と同様に、特定の特殊なケースを示すために使用されます。

スワップチェーンを使用しないレンダリングも可能です。典型的な使用例は、完全にオフスクリーンのアプリケーションでの使用です。例えば、ウィンドウを表示することなく、レンダリングと読み取りを繰り返して画像シーケンスを生成する場合などです。

オンスクリーン・アプリケーションでの使用（つまり、beginFrame 、endFrame 、beginOffscreenFrame、endOffscreenFrame 、beginFrame など）も可能です。

texture やbuffer による読み戻しがスケジュールされている場合、オフスクリーンフレームでは、GPU が前のフレームを処理している間に CPU が別のフレームを生成してしまう可能性を排除します。これにより、読み戻しがスケジュールされていれば、endOffscreenFrame() が返った時点で結果が確実に利用可能になるという副次的な効果があります。 一方、スワップチェーンをターゲットとするフレームの場合はそうではありません。そこではGPUの利用効率が向上する可能性がありますが、endFrame()はendOffscreenFrame()とは異なり、その時点でリードバックの結果が利用可能であることを保証しないため、リードバック操作を扱う際にはアプリケーション側でより細心の注意が必要です。

スワップチェーンを使用せずにフレームをレンダリングし、その後フレームの内容を読み戻す処理の骨子は、次のようなものになります：

QRhiReadbackResult rbResult;
QRhiCommandBuffer *cb;
rhi->beginOffscreenFrame(&cb);
cb->beginPass(rt, colorClear, dsClear);
// ...
u = nextResourceUpdateBatch();
u->readBackTexture(rb, &rbResult);
cb->endPass(u);
rhi->endOffscreenFrame();
// image data available in rbResult

endOffscreenFrame() およびbeginFrame()も参照してください 。

QMatrix4x4 QRhi::clipSpaceCorrMatrix() const

アクティブなQRhi バックエンドに関係なく、アプリケーションがOpenGL向けの頂点データや透視投影行列（QMatrix4x4::perspective()によって生成されるものなど）を引き続き使用できるようにするための行列を返します。

一般的なレンダラーでは、単に `mvp` ではなく `this_matrix * mvp ` を使用することで、実行時にどのバックエンド（ひいてはどのグラフィックス API）が使用されるかを考慮することなく、Y 軸が上向きの頂点データや深度範囲 0 ～ 1 のビューポートを使用できるようになります。 これにより、isYUpInNDC() やisClipDepthZeroToOne() に基づく分岐を回避できます（ただし、特定の高度なグラフィックス技術を実装する際には、依然としてそのようなロジックが必要になる場合があります）。

Vulkanの観点からのこのトピックに関する議論については、こちらのページを参照してください。

[static] QRhi *QRhi::create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags, QRhiNativeHandles *importDevice, QRhiAdapter *adapter)

impl で指定されたグラフィックス API のバックエンドと、指定されたflags を持つ新しいQRhi インスタンスを返します。関数が失敗した場合は、nullptr を返します。

params は、`QRhiInitParams`のバックエンド固有のサブクラス（例：QRhiVulkanInitParams 、QRhiMetalInitParams 、QRhiD3D11InitParams 、QRhiD3D12InitParams 、QRhiGles2InitParams など）のいずれかのインスタンスを指している必要があります。`QRhi`の作成例については、これらのクラスを参照してください。

QRhi 設計上、いかなるフォールバックロジックも実装されていません。指定されたAPIを初期化できない場合、create()は失敗し、バックエンドによってデバッグ出力に警告が出力されます。ただし、QRhi のクライアント（例：Qt Quick ）は、プラットフォームに応じて、要求されたものとは異なるAPIにフォールバックすることを可能にする追加のロジックを提供する場合があります。 単に、後ほど `create()` を呼び出した際に初期化が成功するかどうかをテストしたいだけの場合、`create()` ではなく `probe()` を使用することを推奨します。これは、一部のバックエンドでは、インフラストラクチャの完全な初期化を行う `create()` と比べて、` ()` の方がプローブ処理をより軽量に実装できるためです。また、QRhi のインスタンスがすぐに破棄されてしまう場合、`create()` はリソースの無駄遣いとなります。

importDevice これにより、QRhi が独自のグラフィックスデバイスを作成することなく、既存のグラフィックスデバイスを使用できるようになります。nullでない場合、このパラメータはQRhiNativeHandles のサブクラスのいずれか（QRhiVulkanNativeHandles 、QRhiD3D11NativeHandles 、QRhiD3D12NativeHandles 、QRhiMetalNativeHandles 、QRhiGles2NativeHandles ）のインスタンスを指す必要があります。具体的な詳細や意味論は、バックエンドおよび基盤となるグラフィックスAPIによって異なります。

adapter でQRhiAdapter を指定することは、QRhiVulkanNativeHandles を介してVkPhysicalDevice を渡す方法や、QRhiD3D12NativeHandles を介してアダプタLUIDを渡す方法に代わる、透過的でAPIを横断する代替手段となります。adapter の所有権は取得されません。このアプローチの詳細については、enumerateAdapters()を参照してください。

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

[static] QRhi *QRhi::create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags = {}, QRhiNativeHandles *importDevice = nullptr)

create(impl,params,flags,importDevice,nullptr) と同等です。

int QRhi::currentFrameSlot() const

フレームの記録中に、現在のフレームスロットのインデックスを返します。アクティブなフレーム外で呼び出された場合（つまり、isRecordingFrame()がfalse の場合）、未定義となります。

VulkanやMetalなどのバックエンドでは、新しいフレームを開始する際に、CPUがGPUよりFramesInFlight - 1 フレーム先を行っていることが判明した場合（フレーム番号current ～FramesInFlight で送信されたコマンドバッファがまだ完了していないため）、QRhi バックエンドがブロックする責任を負います。

フレーム間で変化しやすいリソース（例えば、タイプQRhiBuffer::Dynamic のQRhiBuffer を裏付けするネイティブバッファオブジェクトなど）は、複数のバージョンが存在します。これにより、前のフレームがまだ処理中の間に送信される可能性のある各フレームは、独自のコピーを使用して動作するため、フレームの準備時にパイプラインを停止させる必要がなくなります。 （GPU上でまだ使用中のリソースの内容には手を加えるべきではありませんが、単に前のフレームが終了するのを常に待っているだけでは、GPUの利用率が低下し、最終的にはパフォーマンスと効率が低下してしまいます。）

概念的には、これは一部のC++コンテナやその他の型で使用される「コピー・オン・ライト（copy-on-write）」方式に多少似ています。また、OpenGLやDirect 3D 11の実装が、特定の種類のオブジェクトに対して内部的に実行している処理にも類似している可能性があります。

実際には、このような二重（または三重）バッファリングリソースは、Vulkan、Metal、および類似のQRhi バックエンドにおいて、QRhiResource の背後に固定数のネイティブリソース（VkBufferなど）slots を配置することで実現されています。 これにより、0、1、…、FramesInFlight-1と連番するフレームスロットインデックスで参照可能となり、その後インデックスはループします。

これらすべては、QRhi のユーザーに対して透過的に管理されます。ただし、グラフィックス API を使用して直接レンダリングを行うアプリケーションでは、独自のグラフィックスリソースに対して同様のダブルバッファリングやトリプルバッファリングを実行したい場合があります。 これは、処理中のフレームの最大数（resourceLimit() を通じて取得可能）と現在のフレーム（スロット）インデックス（この関数によって返される）の値を把握することで、最も簡単に実現できます。

isRecordingFrame()、beginFrame()、およびendFrame()も参照してください 。

QRhiDriverInfo QRhi::driverInfo() const

正常に初期化されたこのQRhi インスタンスで使用されているグラフィックスデバイスのメタデータを返します。

QRhi::FrameOpResult QRhi::endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags = {})

swapChain 上で、前回のbeginFrame() で開始されたフレームを終了、コミット、および提示します。

ダブル（またはトリプル）バッファリングは、QRhiSwapChain およびQRhi によって内部的に管理されます。

flags オプションで、特定の動作を変更するために使用できます。QRhi::SkipPresent を渡すと、Presentコマンドのキューへの追加やswapBuffersの呼び出しがスキップされます。

成功した場合はQRhi::FrameOpSuccess を返し、失敗した場合は別のQRhi::FrameOpResult の値を返します。これらのうちいくつかは、ソフトな「後で再試行」タイプのエラーとして扱う必要があります。QRhi::FrameOpSwapChainOutOfDate が返された場合、QRhiSwapChain::createOrResize() を呼び出してスワップチェーンのサイズ変更または更新を行う必要があります。 その後、アプリケーションは新しいフレームの生成を試みる必要があります。QRhi::FrameOpDeviceLost が返された場合は、グラフィックスデバイスが失われたことを意味しますが、QRhi 自体を含むすべてのリソースを解放し、その後すべてのリソースを再作成することで回復できる場合もあります。詳細については、isDeviceLost()を参照してください。

beginFrame() およびisDeviceLost()も参照してください 。

QRhi::FrameOpResult QRhi::endOffscreenFrame(QRhi::EndFrameFlags flags = {})

オフスクリーンフレームを終了、送信し、場合によってはその完了を待機します。

endFrame() とは異なり、この関数は、アクティブなバッファまたはテクスチャのリードバックがある場合、GPU 側の処理が完了するまでブロックして待機します。

flags は現在使用されていません。

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

[static, since 6.10] QRhi::AdapterList QRhi::enumerateAdapters(QRhi::Implementation impl, QRhiInitParams *params, QRhiNativeHandles *nativeHandles = nullptr)

存在するアダプタ（物理デバイス）のリストを返します。指定されたグラフィックスAPIでそのような制御が利用できない場合は、空のリストを返します。

このレベルの制御が利用できないバックエンドの場合、返されるリストは常に空になります。したがって、リストが空であることは、システムにグラフィックスデバイスが存在しないことを示すものではなく、どのデバイスを使用するかを選択するためのきめ細かな制御が利用できないことを意味します。

Direct 3D 11、Direct 3D 12、および Vulkan 用のバックエンドは、アダプタの列挙を完全にサポートしていると予想されます。その他のバックエンドではサポートされていない場合があります。 バックエンドは `impl` で指定されます。この関数から返される `QRhiAdapter ` は、同じ `impl` を持つ `create()` 呼び出しでのみ使用しなければなりません。一部の基盤となるAPIにはさらなる制限がある場合があり、特にVulkanでは、`QRhiAdapter ` が `QVulkanInstance ` (VkInstance) に指定されています。

呼び出し元は、リスト内のQRhiAdapter オブジェクトを破棄することが期待されます。info()のクエリを除き、これらのオブジェクトの唯一の目的は、create()、あるいはQt Quick などの上位レイヤーの対応する関数に渡されることです。

Vulkan向けに特別に作成された以下のコードスニペットは、利用可能な物理デバイスを列挙し、選択したデバイスに対してQRhi の作成を要求する方法を示しています。これは実際には、QRhiVulkanNativeHandles を経由してVkPhysicalDevice をcreate()に渡すことと同等ですが、アプリケーション側でAPI固有のコードを記述する量を減らすことができます：

QRhiVulkanInitParams initParams;
initParams.inst= &vulkanInstance;
QRhi::AdapterList adapters=QRhi::enumerateAdapters(QRhi::Vulkan, &initParams);
QRhiAdapter*chosenAdapter =nullptr;
for(QRhiAdapter*adapter: adapters) {
    if(looksGood(adapter->info())) {
        chosenAdapter=adapter;
        break;
    }
}
QRhi*rhi =QRhi::create(QRhi::Vulkan, &initParams,{},nullptr,chosenAdapter);
qDeleteAll(adapters);

params の引数指定は、基盤となるグラフィックス API の設計上の理由により必須となっています。特に Vulkan の場合、QVulkanInstance を指定する必要があります。これは、これを指定しないと列挙処理が行えないためです。バックエンド固有のparams にあるその他のフィールドは、この関数では実際には使用されません。

nativeHandles はオプションです。指定する場合、create()と同様に、有効なQRhiD3D11NativeHandles 、QRhiD3D12NativeHandles 、またはQRhiVulkanNativeHandles でなければなりません。ただし、create()とは異なり、物理デバイス（Vulkanの場合）またはアダプタLUID（D3Dの場合）のフィールドのみが使用され、その他のフィールドはすべて無視されます。これにより、結果を特定のアダプタに限定することができます。 この場合、返されるリストには1つまたは0つの要素が含まれます。

前のコードスニペットでは、looksGood() 関数の実装において、Windows のアダプタ LUID や Vulkan の VkPhysicalDevice など、実際のアダプタ／物理デバイスの識別情報に基づくプラットフォーム固有のフィルタリングを行うことができない点に注意してください。これは、QRhiDriverInfo にプラットフォーム固有のデータが含まれていないためです。 その代わりに、nativeHandles を使用して、enumerateAdapters() 内部ですでにフィルタリングされた結果を取得してください。

Direct 3D 12 を例とした以下の 2 つのコードスニペットは、実際には同等です:

// Qt 6.10 以降の enumerateAdapters ベースのアプローチ
QRhiD3D12InitParams initParams;
QRhiD3D12NativeHandles nativeHandles;
nativeHandles.adapterLuidLow=luid.LowPart;// どこからか LUID を取得し、それを Qt に渡す
nativeHandles.adapterLuidHigh=luid.HighPart;
QRhi::AdapterList adapters=QRhi::enumerateAdapters(QRhi::D3D12, &initParams, &nativeHandles);
if(adapters.isEmpty()) {qWarning("要求されたアダプタが見つかりませんでした");}
QRhi*rhi =QRhi::create(QRhi::D3D12, &initParams,{},nullptr,adapters[0]);
qDeleteAll(adapters);

// traditional approach, more lightweight
QRhiD3D12InitParams initParams;
QRhiD3D12NativeHandles nativeHandles;
nativeHandles.adapterLuidLow = luid.LowPart; // retrieved a LUID from somewhere, now pass it on to Qt
nativeHandles.adapterLuidHigh = luid.HighPart;
QRhi *rhi = QRhi::create(QRhi::D3D12, &initParams, {}, &nativeHandles, nullptr);

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

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

QRhi::FrameOpResult QRhi::finish()

グラフィックスキュー上の処理（該当する場合）が完了するのを待ち、その後、リードバックの完了やリソースの解放など、すべての遅延処理を実行します。フレームの内外で呼び出すことができますが、パスの内部では呼び出すことはできません。フレーム内での呼び出しは、コマンドバッファ上のすべての処理をサブミットすることを意味します。

bool QRhi::isClipDepthZeroToOne() const

基となるグラフィックスAPIがクリップ空間で深度範囲 [0, 1] を使用している場合、true を返します。

実際には、OpenGL のみがfalse を返します。これは、OpenGL が投影後の深度範囲 [-1, 1] を使用しているためです。（glDepthRange() によって制御される NDC からウィンドウへのマッピングと混同しないでください。glDepthRange() は、QRhiViewport によって上書きされない限り、範囲 [0, 1] を使用します。） 一部の OpenGL バージョンでは、glClipControl() を使用してこれを変更することができましたが、QRhi の OpenGL バックエンドでは、OpenGL ES や OpenGL 4.5 より前のバージョンではこの関数が利用できないため、この関数は使用されていません。

bool QRhi::isDeviceLost() const

グラフィックデバイスが失われた場合、true を返します。

デバイスの喪失は、バックエンドや基盤となるネイティブ API に応じて、通常、beginFrame()、endFrame()、またはQRhiSwapChain::createOrResize() で検出されます。最も一般的なのはendFrame() です。これは、そこでプレゼンテーションが行われるためです。一部のバックエンドでは、デバイスの喪失によりQRhiSwapChain::createOrResize() も失敗する場合があります。 したがって、この関数は、以前の操作によってデバイスの喪失が検出されたかどうかを確認するための汎用的な手段として提供されています。

デバイスが失われた場合、QRhi を介してそれ以上の操作を行ってはなりません。代わりに、すべてのQRhi リソースを解放し、続いてQRhi を破棄する必要があります。その後、新しいQRhi の作成を試みることができます。成功した場合は、すべてのグラフィックスリソースを再初期化する必要があります。失敗した場合は、後で繰り返し試みてください。

単純なアプリケーションではデバイスの喪失を無視することもあるかもしれませんが、一般的に使用されるデスクトッププラットフォームでは、グラフィックスアダプタの物理的な取り外し、デバイスやドライバの無効化、グラフィックスドライバのアンインストールやアップグレード、あるいはグラフィックスデバイスのリセットにつながるエラーなど、さまざまな理由でデバイスの喪失が発生する可能性があります。 これらのうちいくつかは、ごく通常の状況下でも発生する可能性があります。例えば、グラフィックスドライバの新しいバージョンへのアップグレードは、Qtアプリケーションの実行中にいつでも発生し得る一般的な作業です。ユーザーは、アプリケーションがOpenGLやDirect3DのようなAPIを積極的に使用している場合でも、こうした状況に耐えられることを当然期待するでしょう。

Qt Quick など、QRhi を基盤として構築されたQt独自のフレームワークは、デバイスの喪失が発生した際に適切に対処し、必要な措置を講じることが期待されます。 テクスチャやバッファなどのグラフィックスリソースに関するデータがCPU側でまだ利用可能な場合、グラフィックスリソースはシームレスに再初期化されるため、アプリケーションレベルではそのようなイベントが全く気づかれない可能性があります。ただし、QRhi を直接扱うアプリケーションやライブラリは、デバイス喪失の状況を自らチェックし、対処する準備が整っていることが求められます。

bool QRhi::isFeatureSupported(QRhi::Feature feature) const

指定されたfeature がサポートされている場合、true を返します。

bool QRhi::isRecordingFrame() const

アクティブなフレームが存在する場合、つまり、beginFrame()（またはbeginOffscreenFrame()）が実行されたものの、それに対応するendFrame()（またはendOffscreenFrame()）がまだ実行されていない場合に、trueを返します。

currentFrameSlot()、beginFrame()、およびendFrame()も参照してください 。

bool QRhi::isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags = {}) const

flags によって変更された指定されたテクスチャformat がサポートされている場合、true を返します。

このクエリは、非圧縮形式と圧縮形式の両方でサポートされています。

bool QRhi::isYUpInFramebuffer() const

基盤となるグラフィックスAPIにおいて、フレームバッファおよび画像内のY軸が上向きになっている場合、true を返します。

実際には、これは OpenGL の場合にのみ `true ` となります。

bool QRhi::isYUpInNDC() const

基盤となるグラフィックスAPIの正規化デバイス座標系において、Y軸が上向きになっている場合、true を返します。

実際には、これは Vulkan の場合のみ `false ` となります。

bool QRhi::makeThreadLocalNativeContextCurrent()

OpenGL の場合、これにより現在のスレッドで OpenGL コンテキストがアクティブになります。他のバックエンドでは、この関数は何の効果も持ちません。

この関数の呼び出しは、通常、Qtフレームワークのコードにおいて、QRhi がOpenGLバックエンドを使用している限り、アプリケーションによって提供される外部のOpenGLコードが、以前OpenGLを直接使用していたときと同様に動作し続けることを保証する必要がある場合に重要となります。

QOpenGLContext::makeCurrent()と同様に、失敗した場合はfalseを返します。操作が失敗した場合、isDeviceLost()を呼び出すことで、コンテキストが失われたかどうかを確認できます。この確認は、QOpenGLContext::isValid()による確認と同等です。

QOpenGLContext::makeCurrent() およびQOpenGLContext::isValid()も参照してください 。

[static] int QRhi::mipLevelsForSize(const QSize &size)

指定されたsize のミップレベル数を返します。

const QRhiNativeHandles *QRhi::nativeHandles()

バックエンドが使用するデバイス、コンテキスト、および類似の概念に対応する、バックエンド固有のネイティブオブジェクトのコレクションへのポインタを返します。

必要に応じて、QRhiVulkanNativeHandles 、QRhiD3D11NativeHandles 、QRhiD3D12NativeHandles 、QRhiGles2NativeHandles 、またはQRhiMetalNativeHandles にキャストしてください。

QRhiBuffer *QRhi::newBuffer(QRhiBuffer::Type type, QRhiBuffer::UsageFlags usage, quint32 size)

指定されたtype 、usage 、およびsize を持つ新しいバッファを返します。

QRhiResource::destroy()も参照してください 。

QRhiComputePipeline *QRhi::newComputePipeline()

新しいコンピュートパイプラインリソースを返します。

「QRhiResource::destroy()」も参照してください 。

QRhiGraphicsPipeline *QRhi::newGraphicsPipeline()

新しいグラフィックス・パイプライン・リソースを返します。

QRhiResource::destroy()も参照してください 。

QRhiRenderBuffer *QRhi::newRenderBuffer(QRhiRenderBuffer::Type type, const QSize &pixelSize, int sampleCount = 1, QRhiRenderBuffer::Flags flags = {}, QRhiTexture::Format backingFormatHint = QRhiTexture::UnknownFormat)

指定されたtype 、pixelSize 、sampleCount 、およびflags を持つ新しいレンダリングバッファを返します。

backingFormatHint がQRhiTexture::UnknownFormat 以外のテクスチャ形式に設定されている場合、バックエンドはこれに基づいて、レンダリングバッファのストレージバッキングに使用する形式を決定することがあります。

QRhiResource::destroy()も参照してください 。

QRhiSampler *QRhi::newSampler(QRhiSampler::Filter magFilter, QRhiSampler::Filter minFilter, QRhiSampler::Filter mipmapMode, QRhiSampler::AddressMode addressU, QRhiSampler::AddressMode addressV, QRhiSampler::AddressMode addressW = QRhiSampler::Repeat)

指定された拡大フィルタmagFilter 、縮小フィルタminFilter 、ミップマッピングモードmipmapMode 、およびアドレス指定（ラップ）モードaddressU 、addressV 、addressW を設定した新しいサンプラを返します。

QRhiResource::destroy()も参照してください 。

QRhiShaderResourceBindings *QRhi::newShaderResourceBindings()

新しいシェーダーリソースバインディングコレクションリソースを返します。

QRhiResource::destroy()も参照してください 。

[since 6.9] QRhiShadingRateMap *QRhi::newShadingRateMap()

新しいシェーディングレートマップオブジェクトを返します。

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

QRhiSwapChain *QRhi::newSwapChain()

新しいスワップチェーンを返します。

QRhiResource::destroy() およびQRhiSwapChain::createOrResize()も参照してください 。

QRhiTexture *QRhi::newTexture(QRhiTexture::Format format, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})

指定されたformat 、pixelSize 、sampleCount 、およびflags を持つ新しい1Dまたは2Dテクスチャを返します。

1次元テクスチャでは、`flags` に `QRhiTexture::OneDimensional ` が設定されている必要があります。`pixelSize ` の高さが 0 の場合、この関数は暗黙的にこのフラグを設定します。

QRhiResource::destroy()も参照してください 。

QRhiTexture *QRhi::newTexture(QRhiTexture::Format format, int width, int height, int depth, int sampleCount = 1, QRhiTexture::Flags flags = {})

指定されたformat 、width 、height 、depth 、sampleCount 、およびflags を持つ新しい1D、2D、または3Dテクスチャを返します。

このオーバーロードは、depth を指定できるため、3Dテクスチャに適しています。3Dテクスチャでは、flags でQRhiTexture::ThreeDimensional を設定する必要がありますが、このオーバーロードを使用する場合、depth が0より大きいときは常にこのフラグが暗黙的に設定されるため、省略可能です。1D、2D、およびキューブテクスチャの場合、depth は0に設定する必要があります。

1次元テクスチャの場合、flags でQRhiTexture::OneDimensional を設定する必要があります。height とdepth の両方が0の場合、このオーバーロードは暗黙的にこのフラグを設定します。

QRhiTexture *QRhi::newTextureArray(QRhiTexture::Format format, int arraySize, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})

指定されたformat 、arraySize 、pixelSize 、sampleCount 、およびflags を持つ新しい1次元または2次元のテクスチャ配列を返します。

この関数は、flags 内のQRhiTexture::TextureArray を暗黙的に設定します。

1次元テクスチャ配列では、flags でQRhiTexture::OneDimensional が設定されている必要があります。pixelSize の高さが0の場合、この関数は暗黙的にこのフラグを設定します。

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

QRhiTextureRenderTarget *QRhi::newTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc, QRhiTextureRenderTarget::Flags flags = {})

desc で指定されたカラーおよび深度／ステンシルアタッチメントを持ち、指定されたflags を持つ新しいテクスチャレンダリングターゲットを返します。

QRhiResource::destroy()も参照してください 。

QRhiResourceUpdateBatch *QRhi::nextResourceUpdateBatch()

操作のコピーを記録できる、利用可能な空のバッチを返します。

録画中のフレームに縛られないため、例えば次のようなシーケンスも有効です：

rhi->beginFrame(swapchain);
QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
u->uploadStaticBuffer(buf, data);
// ... do not commit the batch
rhi->endFrame();
// u stays valid (assuming buf stays valid as well)
rhi->beginFrame(swapchain);
swapchain->currentFrameCommandBuffer()->resourceUpdate(u);
// ... draw with buf
rhi->endFrame();

QByteArray QRhi::pipelineCacheData()

このQRhi のライフタイム中に正常に作成されたQRhiGraphicsPipeline およびQRhiComputePipeline から収集されたデータを含むバイナリデータブロブを返します。

キャッシュデータを保存し、同じアプリケーションのその後の実行でそれを再読み込みすることで、パイプラインおよびシェーダーの作成時間を短縮できる可能性があります。キャッシュおよびそのシリアライズされたバージョンに具体的に何が含まれるかは規定されておらず、常に使用されるバックエンドに依存し、場合によってはグラフィックス API の特定の実装にも依存します。

PipelineCacheDataLoadSave がサポートされていないと報告された場合、返されるQByteArray は空になります。

create() の呼び出し時にEnablePipelineCacheDataSave フラグが指定されなかった場合、PipelineCacheDataLoadSave 機能がサポートされている場合でも、返されるQByteArray は空になることがあります。

返されたデータが空でない場合、そのデータは常に Qt のバージョンおよびQRhi バックエンドに固有のものです。 さらに、場合によっては、グラフィックデバイスや使用されているドライバーの正確なバージョンに強く依存することがあります。QRhi は、適切なヘッダーの追加や、データが常にsetPipelineCacheData() に安全に渡されることを保証する安全策を講じています。そのため、別のバージョンのドライバーでの実行からデータを読み込もうとしても、安全かつ円滑に処理されます。

この機能の詳細については、EnablePipelineCacheDataSave を参照してください。

setPipelineCacheData()、create()、およびisFeatureSupported()も参照してください 。

[static] bool QRhi::probe(QRhi::Implementation impl, QRhiInitParams *params)

指定されたimpl およびparams に対してcreate()を呼び出した際に、その呼び出しが成功すると予想される場合、trueを返します。

一部のバックエンドでは、これはcreate() を呼び出し、その戻り値を確認した後、結果として生成されたQRhi を破棄することと同等です。

その他のバックエンド、特に Metal では、特定のプローブ実装が存在する場合があり、これにより、失敗時の警告でデバッグ出力を汚すことなく、より軽量な方法でテストを行うことができます。

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

void QRhi::releaseCachedResources()

バックエンドのキャッシュからリソースを解放しようとします。これには、CPUリソースとGPUリソースの両方が含まれる場合があります。 対象となるのは、自動的に再作成可能なメモリとリソースのみです。例えば、バックエンドのQRhiGraphicsPipeline 実装がシェーダーコンパイル結果のキャッシュを保持している場合、この関数を呼び出すと、そのキャッシュがクリアされ、その結果、メモリとグラフィックスリソースが解放される可能性があります。

この関数の呼び出しは、リソースが制約された環境において、ある時点でパフォーマンスを犠牲にしてでもリソース使用量を最小限に抑える必要がある場合に有効です。

void QRhi::removeCleanupCallback(const void *key)

key を使用してコールバックを登録解除します。key でクリーンアップコールバックが登録されていない場合、この関数は何も行いません。キーなしで登録されたコールバックは削除できません。

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

int QRhi::resourceLimit(QRhi::ResourceLimit limit) const

指定されたリソース `limit` の値を返します。

これらの値は初期化時にバックエンドによって取得されることが想定されているため、この関数の呼び出しは負荷の少ない操作となります。

void QRhi::setPipelineCacheData(const QByteArray &data)

該当する場合、data をパイプラインキャッシュに読み込みます。

PipelineCacheDataLoadSave がサポートされていないと報告された場合、この関数は安全に呼び出すことができますが、何の効果もありません。

pipelineCacheData() によって返される blob は、常に Qt のバージョン、QRhi バックエンド、場合によってはグラフィックデバイスやグラフィックドライバの特定のバージョンに固有のものです。QRhi は、適切なヘッダーを追加し、データが常にこの関数に安全に渡されることを保証する安全策を講じています。 ドライバーが新しいバージョンにアップグレードされた場合や、データが別のQRhi バックエンドから生成された場合など、不一致がある場合は、警告が出力され、data は安全に無視されます。

Vulkan では、これは VkPipelineCache に直接対応します。この関数を呼び出すと、data から初期データを取得した新しい Vulkan パイプラインキャッシュオブジェクトが作成されます。その後、このパイプラインキャッシュオブジェクトは、その後作成されるすべてのQRhiGraphicsPipeline およびQRhiComputePipeline オブジェクトで使用されるため、パイプラインの作成が高速化される可能性があります。

他のAPIには、厳密な意味でのパイプラインキャッシュは存在しませんが、シェーダーコンパイルによるバイトコード（D3D）やプログラムバイナリ（OpenGL）を格納するキャッシュが提供される場合があります。 実行時にソースからのシェーダーコンパイルを頻繁に行うアプリケーションでは、この関数を使用して以前の実行から「パイプラインキャッシュ」を事前に初期化しておけば、その後の実行において大幅なパフォーマンス向上が期待できます。

この機能の詳細については、EnablePipelineCacheDataSave を参照してください。

関連項目： pipelineCacheData() およびisFeatureSupported()。

[since 6.9] void QRhi::setQueueSubmitParams(QRhiNativeHandles *params)

バックエンドやグラフィックスAPI（該当する場合）において、この関数を使用することで、グラフィックスコマンドキューへの次回のコマンド送信時に追加の引数を指定することができます。

特に、Vulkan では、これにより `vkQueueSubmit() ` がシグナルを送信したり待機したりするための Vulkan セマフォオブジェクトのリストを渡すことが可能になります。この場合、params は `QRhiVulkanQueueSubmitParams` でなければなりません。これは、アプリケーションのカスタム Vulkan レンダリングやコンピュートコードが管理する `VkSemaphore` に対して待機やシグナル送信を行う必要があるネイティブ Vulkan 呼び出しを実行する場合など、特定の高度なユースケースにおいて不可欠となります。 さらに、これにより、次のvkQueuePresentKHR() で待機対象とする追加のセマフォを指定することも可能になります。

他の多くのバックエンドでは、この関数の実装はノーオペレーション（何もしない）です。

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

[static] QSize QRhi::sizeForMipLevel(int mipLevel, const QSize &baseLevelSize)

指定されたmipLevel のテクスチャ画像サイズを返します。このサイズは、baseLevelSize で指定されたレベル0のサイズに基づいて計算されます。

QRhiStats QRhi::statistics() const

グラフィックスリソースのタイミングや割り当てに関する統計情報を収集し、返します。

メモリ割り当てに関するデータは、そのような操作がQtの管理下にある一部のバックエンドでのみ利用可能です。リソースのメモリ割り当てに対して低レベルでの制御がないグラフィックスAPIでは、これは決してサポートされず、結果内の関連するすべてのフィールドは0となります。

特にVulkanの場合、値は常に有効であり、基盤となるメモリアロケータライブラリから取得されます。これにより、アクティブなバッファやテクスチャのメモリ要件を把握することができます。

Direct 3D 12についても同様です。メモリアロケータライブラリの統計情報に加え、ここでは結果に「totalUsageBytes 」フィールドも含まれます。このフィールドは、DXGIによって報告される、メモリアロケータライブラリの管理下にはない追加リソース（スワップチェーンバッファ、ディスクリプタヒープなど）を含めた合計サイズを示します。

これらの値は、使用されているすべての種類のメモリを合計したものです（つまり、ディスクリートGPUの場合はビデオメモリ＋システムメモリ）。

グラフィックスおよびコンピュートパイプラインの生成に費やされた合計時間（ミリ秒単位）など、追加データはほとんどのバックエンドで利用可能です（これには通常、シェーダーのコンパイルやキャッシュのルックアップ、および潜在的に負荷の高い処理が含まれます）。

QList<int> QRhi::supportedSampleCounts() const

サポートされているサンプル数のリストを返します。

典型的な例としては (1, 2, 4, 8) が挙げられます。

バックエンドによっては、サポートされている値のリストが事前に固定されているものもあれば、実行時に（物理）デバイスのプロパティによってサポートされているものが決定されるものもあります。

QRhiRenderBuffer::setSampleCount()、QRhiTexture::setSampleCount()、QRhiGraphicsPipeline::setSampleCount()、およびQRhiSwapChain::setSampleCount()も参照してください 。

[since 6.9] QList<QSize> QRhi::supportedShadingRates(int sampleCount) const

指定されたsampleCount に対してサポートされている可変シェーディング率のリストを返します。

1x1は常にサポートされています。

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

QThread *QRhi::thread() const

QRhi がinitialized されたスレッドを返します。

int QRhi::ubufAligned(int v) const

ubufAlignment() で指定された均一バッファのアラインメントに合わせて整列された値（通常はオフセット）v を返します。

int QRhi::ubufAlignment() const

バイト単位でのユニフォームバッファのオフセットアライメントの最小値を返します。通常、これは 256 です。

この値にアラインされていないオフセットでユニフォームバッファ領域をバインドしようとすると、バックエンドや基盤となるグラフィックスAPIによっては失敗する可能性があります。

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

[static] QRhiSwapChainProxyData QRhi::updateSwapChainProxyData(QRhi::Implementation impl, QWindow *window)

impl で指定されたバックエンドおよびグラフィックス API に固有の不透明なデータを含む `QRhiSwapChainProxyData ` 構造体を生成して返します。window は、スワップチェーンがターゲットとする `QWindow ` です。

返された構造体は、QRhiSwapChain::setProxyData() に渡すことができます。これはスレッド化されたレンダリングシステムにおいて意味を持ちます。この静的関数は、QRhi のすべての操作とは異なり、メイン（GUI）スレッド上で呼び出され、その後、QRhi およびQRhiSwapChain を扱うスレッドに転送され、スワップチェーンに渡されることが想定されています。 これにより、メインスレッドでのみ安全に呼び出せるネイティブプラットフォームのクエリ（例えば、NSView から CAMetalLayer を取得するクエリなど）を実行し、そのデータをレンダリングスレッド上のQRhiSwapChain に渡すことが可能になります。 Metalの例では、専用のレンダリングスレッド上で`view.layer`にアクセスすると、Xcodeのスレッドチェッカーで警告が発生します。データプロキシの仕組みを用いれば、これを回避できます。

スレッドが関与しない場合、QRhiSwapChainProxyData の生成や引き渡しは不要です。バックエンドは必要な情報を独自に取得できることが保証されており、すべてがメイン（GUI）スレッド上にあるのであれば、それで十分です。