QQuickGraphicsConfiguration Class

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QQuickGraphicsConfiguration config;
    config.setDebugLayer(true);

    QQuickView *view = new QQuickView;
    view->setGraphicsConfiguration(config);

    view->setSource(QUrl::fromLocalFile("myqmlfile.qml"));
    view->show();
    return app.exec();
}

Total time spent on pipeline creation during the lifetime of the QRhi was 123 ms

Attempting to seed pipeline cache from 'filename'

Writing pipeline cache contents to 'filename'

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

QQuickGraphicsConfiguration::QQuickGraphicsConfiguration()

シーングラフが考慮すべき追加の設定を一切指定しない、デフォルトの QQuickGraphicsConfiguration を生成します。

[noexcept] QQuickGraphicsConfiguration::~QQuickGraphicsConfiguration()

デストラクタ。

QByteArrayList QQuickGraphicsConfiguration::deviceExtensions() const

要求された追加のデバイス拡張機能のリストを返します。

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

[since 6.5] bool QQuickGraphicsConfiguration::isAutomaticPipelineCacheEnabled() const

自動パイプラインキャッシュが有効になっている場合、true を返します。

特定のアプリケーション属性や環境変数が設定されていない限り、デフォルトでは true です。詳細については、The Automatic Pipeline Cache を参照してください。

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

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

bool QQuickGraphicsConfiguration::isDebugLayerEnabled() const

デバッグ／検証レイヤーを有効にする場合、true を返します。

デフォルトでは、この値は false です。

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

bool QQuickGraphicsConfiguration::isDebugMarkersEnabled() const

デバッグマーカーが有効な場合、true を返します。

デフォルトでは、値は false です。

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

bool QQuickGraphicsConfiguration::isDepthBufferEnabledFor2D() const

2Dコンテンツで深度バッファの使用が有効になっている場合、trueを返します。

QSG_NO_DEPTH_BUFFER 環境変数が設定されていない限り、デフォルトではこの値はtrueです。

QString QQuickGraphicsConfiguration::pipelineCacheLoadFile() const

パイプラインキャッシュを読み込むために現在設定されているファイル名を返します。

デフォルトでは、値は空の文字列です。

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

QString QQuickGraphicsConfiguration::pipelineCacheSaveFile() const

パイプラインキャッシュを保存するために現在設定されているファイル名を返します。

デフォルトでは、値は空の文字列です。

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

[static, since 6.1] QByteArrayList QQuickGraphicsConfiguration::preferredInstanceExtensions()

Qt Quick がVkInstance上で有効にすることを推奨するVulkanインスタンス拡張機能のリストを返します。

ほとんどの場合、Qt Quick はQVulkanInstance の作成を担当します。その場合、この関数は関係ありません。 一方、QQuickRenderControl をVulkanベースのレンダリングと組み合わせて使用する場合、QVulkanInstance を作成し、それを（オフスクリーン）QQuickWindow に関連付けるのはアプリケーションの責任となります。この場合、アプリケーションは有効にするインスタンス拡張機能のリストを照会し、QVulkanInstance::create()を呼び出す前に、それらをQVulkanInstance::setExtensions()に渡すことが想定されています。

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

bool QQuickGraphicsConfiguration::prefersSoftwareDevice() const

ソフトウェアラスタライザベースのグラフィックスデバイスが優先されている場合、true を返します。

デフォルトでは、この値は false です。

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

[since 6.5] void QQuickGraphicsConfiguration::setAutomaticPipelineCache(bool enable)

enable に基づいて、自動パイプラインキャッシュの使用方法を変更します。

特定のアプリケーション属性または環境変数が設定されていない限り、デフォルト値は true です。詳細については、The Automatic Pipeline Cache を参照してください。

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

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

[since 6.5] void QQuickGraphicsConfiguration::setDebugLayer(bool enable)

利用可能な場合、グラフィックス API 実装のデバッグ層または検証層を有効にします。

実際には、必要なサポート（検証レイヤー、Windows SDK）がインストールされ、実行時に利用可能な場合、VulkanおよびDirect 3D 11でこれがサポートされます。enable がtrueの場合、QtはVkInstance上で標準の検証レイヤーを有効にしようとするか、グラフィックスデバイスに対してD3D11_CREATE_DEVICE_DEBUG を設定しようとします。

macOS上のMetalについては、アプリケーションを起動する前に、代わりに環境変数METAL_DEVICE_WRAPPER_TYPE=1 を設定してください。

enable が true に設定されている状態でこの関数を呼び出すことは、環境変数QSG_RHI_DEBUG_LAYER を 0 以外の値に設定することと同等です。

デフォルト値は false です。

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

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

[since 6.5] void QQuickGraphicsConfiguration::setDebugMarkers(bool enable)

該当する場合、enable は、グラフィックスコマンドストリームへのデバッグマーカーやオブジェクト名の挿入を制御します。

Qt Quick 3D などの一部のフレームワークには、作成したグラフィックスオブジェクト（バッファ、テクスチャ）に名前を付与したり、コマンドバッファ内でレンダリングパスの開始位置と終了位置を示したりする機能があります。これらは、RenderDocや XCode などのツールで作成されたフレームキャプチャ上で確認できます。

この機能がサポートされていると予想されるグラフィックスAPIには、Vulkan（VK_EXT_debug_utilsが利用可能な場合）、Direct 3D 11、およびMetalがあります。

enable をtrueに設定してこの関数を呼び出すことは、環境変数QSG_RHI_PROFILE を0以外の値に設定することと同等です。

デフォルト値は false です。

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

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

void QQuickGraphicsConfiguration::setDepthBufferFor2D(bool enable)

2Dコンテンツにおける深度バッファの使用設定をenable に設定します。無効にすると、Qt Quick のシーングラフは深度バッファへの書き込みを一切行いません。

QSG_NO_DEPTH_BUFFER 環境変数が設定されていない限り、デフォルト値はtrueです。

デフォルト値の true は、大多数のシーンにとって最適な設定です。深度バッファの使用を無効にすると、シーングラフのバッチ処理の効率が低下します。

ただし、2D コンテンツが深度バッファに書き込まれることを許可することが理想的ではない場合もあります。2D シーンの上に「オーバーレイ」として 3D シーンがあり、renderMode がOverlay に設定されたView3D を使用してQt Quick 3D 経由でレンダリングされる場合を考えてみてください。この場合、深度バッファが 2D コンテンツで埋められると、予期しない結果が生じる可能性があります。 これは、2Dシーングラフレンダラーが深度値を生成・処理する方法が、3Dシーンの動作方法と必ずしも互換性がないためです。その結果、深度値の競合、衝突、および予期しない深度テストの失敗が発生する可能性があります。 したがって、ここでの確実な対処法は、enable をfalseに設定してこの関数を呼び出し、QQuickWindow 内で2Dコンテンツに対する深度バッファへの書き込みを無効にすることです。

void QQuickGraphicsConfiguration::setDeviceExtensions(const QByteArrayList &extensions)

グラフィックスデバイス（VkDevice など）で有効にする追加のextensions のリストを設定します。

この概念が適用されないグラフィックスAPIを使用してレンダリングする場合、extensions は無視されます。

「deviceExtensions()」も参照してください 。

[since 6.5] void QQuickGraphicsConfiguration::setPipelineCacheLoadFile(const QString &filename)

QQuickWindow がグラフィックス／演算パイプラインキャッシュの初期コンテンツを読み込む元となるfilename を設定します。デフォルト値は空であり、これはパイプラインキャッシュの読み込みが無効になっていることを意味します。

パイプラインキャッシュに関する説明については、「Pipeline Cache Save and Load 」を参照してください。

パイプラインキャッシュを永続的に保存することで、負荷の高いシェーダーのコンパイルやパイプラインの構築ステップを回避できるため、アプリケーションの今後の実行においてパフォーマンスが向上する可能性があります。

ファイルの内容の読み込みが行われるかどうか、またそのタイミングについては定義されていませんが、QQuickWindow のシーングラフの初期化中に何らかの時点で実行されることは確かです。したがって、この関数を呼び出した後も、ファイルは存在し続けていなければなりません。QQuickGraphicsConfiguration はファイル名のみを格納するものであり、それ自体では実際のI/Oやグラフィックス操作を実行することはできません。 実際の処理は、おそらく別のスレッド上で、後ほど実行されます。

パイプラインキャッシュ（またはシェーダー／プログラムバイナリ）の取得や再読み込みが適用できない、あるいはサポートされていないグラフィックス API で実行する場合、この関数を呼び出しても何の効果もありません。

この関数の呼び出しは、環境変数 `QSG_RHI_PIPELINE_CACHE_LOAD ` を `filename` に設定することとほぼ同等ですが、1 つの重要な違いがあります。それは、この関数が、関連付けられた `QQuickWindow ` のみのパイプラインキャッシュの保存を制御する点です。したがって、複数の `QQuickWindow ` または `QQuickView ` インスタンスを持つアプリケーションは、各ウィンドウ専用のファイルを介してキャッシュの内容を保存し、後で再読み込みすることができます。環境変数では、これは不可能です。

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

関連項目： pipelineCacheLoadFile() およびsetPipelineCacheSaveFile()。

[since 6.5] void QQuickGraphicsConfiguration::setPipelineCacheSaveFile(const QString &filename)

QQuickWindow がグラフィックス/演算パイプラインキャッシュの内容を格納するfilename を設定します。デフォルト値は空であり、これはパイプラインキャッシュの読み込みが無効になっていることを意味します。

パイプラインキャッシュに関する説明については、「Pipeline Cache Save and Load 」を参照してください。

パイプラインキャッシュを永続的に保存することで、負荷の高いシェーダーのコンパイルやパイプラインの構築ステップを回避できるため、アプリケーションの今後の実行においてパフォーマンスが向上する可能性があります。

ファイルへの書き込みが行われるかどうか、またそのタイミングは定義されていません。おそらく、ウィンドウの閉じによりシーングラフが破棄される際に、その過程で書き込みが行われると考えられます。したがって、アプリケーションは、QQuickWindow が完全に破棄されるまでは、ファイルが利用可能であると想定すべきではありません。QQuickGraphicsConfiguration はファイル名のみを保存し、それ自体で実際のI/Oやグラフィックス操作を行うことはありません。

パイプラインキャッシュ（またはシェーダー／プログラムバイナリ）の取得が適用できない、あるいはサポートされていないグラフィックスAPIで実行する場合、この関数を呼び出しても何の効果もありません。

この関数の呼び出しは、環境変数 `QSG_RHI_PIPELINE_CACHE_SAVE ` を `filename` に設定することとほぼ同等ですが、1 つの重要な違いがあります。この関数は、関連付けられた `QQuickWindow ` に対するパイプラインキャッシュの保存のみを制御します。したがって、複数の `QQuickWindow ` または `QQuickView ` インスタンスを持つアプリケーションでは、各ウィンドウ専用のファイルを通じてキャッシュの内容を保存し、後で再読み込みすることができます。環境変数では、これは不可能です。

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

pipelineCacheLoadFile() およびpipelineCacheSaveFile()も参照してください 。

[since 6.5] void QQuickGraphicsConfiguration::setPreferSoftwareDevice(bool enable)

ソフトウェアベースのラスタライズを使用するアダプタまたは物理デバイスを選択するリクエスト。基盤となるAPIがアダプタの列挙をサポートしている場合（例：Direct 3DやVulkan）にのみ適用され、それ以外の場合は無視されます。

グラフィックス API の実装で、そのようなグラフィックスアダプタや物理デバイスが利用できない場合、このリクエストは無視されます。Direct 3D では、WARP ベースのラスタライザが常に利用可能であると想定されます。Vulkan では、Mesa のlavapipe 、またはVK_PHYSICAL_DEVICE_TYPE_CPU を報告するその他の物理デバイスが利用可能な場合にのみ、このフラグが効果を発揮します。

enable をtrueに設定してこの関数を呼び出すことは、環境変数QSG_RHI_PREFER_SOFTWARE_RENDERER を0以外の値に設定することと同等です。

デフォルト値は false です。

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

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

[since 6.6] void QQuickGraphicsConfiguration::setTimestamps(bool enable)

有効にすると、対応しているプラットフォームおよび3D APIにおいて、コマンドバッファからGPUのタイミングデータが収集されます。このデータは、環境変数QSG_RENDER_TIMING や、qt.scenegraph.time.renderloop などのロギングカテゴリを通じて有効化できるレンダラーログに出力されます。また、Qt Quick 3DのDebugView 項目など、他のモジュールからも確認できるようになる場合があります。

デフォルトでは、この機能は無効になっています。これは、データの収集には、基盤となるグラフィックスAPIによっては、コマンドストリームへのタイムスタンプクエリの挿入など、追加の処理が必要になる場合があるためです。有効にするには、enable をtrueに設定してこの関数を呼び出すか、QSG_RHI_PROFILE 環境変数を0以外の値に設定してください。

この機能がサポートされると予想されるグラフィックスAPIは、Direct 3D 11、Direct 3D 12、Vulkan（基盤となるVulkan実装がタイムスタンプクエリをサポートしている場合に限る）、Metal、およびバージョン3.3以降のコアまたは互換性プロファイルコンテキストを持つOpenGLです。 OpenGL ES ではタイムスタンプはサポートされていません。

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

timestampsEnabled() およびsetDebugMarkers()も参照してください 。

[since 6.6] bool QQuickGraphicsConfiguration::timestampsEnabled() const

GPUのタイミング収集が有効になっている場合、trueを返します。

デフォルトでは、この値は false です。

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

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