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。

默认值为 true，除非设置了QSG_NO_DEPTH_BUFFER 环境变量。

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。

默认值为假。

另请参见 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 实现的调试层或验证层（如果可用）。

实际上，Vulkan 和 Direct 3D 11 都支持此功能，前提是运行时已安装并提供必要的支持（验证层、Windows SDK）。当enable 为 true 时，Qt XML 会尝试在 VkInstance 上启用标准验证层，或在图形设备上设置D3D11_CREATE_DEVICE_DEBUG 。

对于 macOS 上的 Metal，请在启动应用程序前设置环境变量METAL_DEVICE_WRAPPER_TYPE=1 。

在enable 设置为 true 时调用此函数，相当于将环境变量QSG_RHI_DEBUG_LAYER 设置为非零值。

默认值为 false。

该函数在 Qt 6.5 中引入。

另请参见 isDebugLayerEnabled()。

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

在适用情况下，enable 可控制在图形命令流中插入调试标记和对象名称。

一些框架（如Qt Quick 3D）能够为其创建的图形对象（缓冲区、纹理）注释名称，并在命令缓冲区中标明渲染过程的开始和结束。在使用RenderDoc或 XCode 等工具制作的帧捕获中，这些注释都是可见的。

Vulkan（如果 VK_EXT_debug_utils 可用）、Direct 3D 11 和 Metal 等图形应用程序接口有望支持此功能。

在enable 设置为 true 时调用此函数，相当于将环境变量QSG_RHI_PROFILE 设置为非零值。

默认值为 false。

此函数在 Qt 6.5 中引入。

另请参阅 isDebugMarkersEnabled()。

void QQuickGraphicsConfiguration::setDepthBufferFor2D(bool enable)

将enable 设置为 2D 内容使用深度缓冲区。禁用时，Qt Quick 场景图将永远不会写入深度缓冲区。

默认值为 true，除非设置了QSG_NO_DEPTH_BUFFER 环境变量。

默认值为 true 是绝大多数场景的最佳设置。禁用深度缓冲区会降低场景图的批处理效率。

但在某些情况下，允许 2D 内容写入深度缓冲区并不理想。将 3D 场景作为 2D 场景的 "叠加"，通过Qt Quick 3D 渲染，View3D ，renderMode ，设置为Overlay 。在这种情况下，深度缓冲区被 2D 内容填满可能会导致意想不到的结果。这是因为 2D 场景图渲染器生成和处理深度值的方式不一定与 3D 场景的工作方式兼容。这可能会导致深度值冲突、碰撞和意外的深度测试失败。因此，稳健的方法是在调用enable 时将其设置为 false，并禁用QQuickWindow 中 2D 内容的深度缓冲区写入。

void QQuickGraphicsConfiguration::setDeviceExtensions(const QByteArrayList &extensions)

设置要在图形设备上启用的附加extensions 列表（如VkDevice ）。

当使用不适用该概念的图形 API 进行渲染时，extensions 将被忽略。

另请参阅 deviceExtensions( )。

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

设置filename ，预计QQuickWindow 将从此处加载图形/计算管道缓存的初始内容。默认值为空，表示禁用管道缓存加载。

有关管道缓存的讨论，请参阅Pipeline Cache Save and Load 。

持续存储管道缓存可以提高应用程序在未来运行中的性能，因为可以避免昂贵的着色器编译和管道构建步骤。

加载文件内容的时间和地点未作规定，但它会在初始化QQuickWindow 的场景图时发生。因此，在调用该函数后，文件必须继续存在。QQuickGraphicsConfiguration 只存储文件名，自身不能执行任何实际的 I/O 和图形操作。真正的工作将在稍后进行，可能是在另一个线程上。

当运行的图形应用程序接口不适用或不支持检索和重新加载管道缓存（或着色器/程序二进制文件）时，调用此函数没有任何作用。

调用此函数在很大程度上等同于将环境变量QSG_RHI_PIPELINE_CACHE_LOAD 设置为filename ，但有一个重要区别：此函数仅控制相关QQuickWindow 的管道缓存存储。因此，具有多个QQuickWindow 或QQuickView 实例的应用程序可以通过每个窗口专用的文件来存储和重新加载缓存内容。环境变量不允许这样做。

此函数在 Qt 6.5 中引入。

另请参阅 pipelineCacheLoadFile() 和setPipelineCacheSaveFile()。

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

设置filename ，预计QQuickWindow 将在此处存储图形/计算管道缓存内容。默认值为空，表示禁用管道缓存加载。

有关管道缓存的讨论，请参阅Pipeline Cache Save and Load 。

持续存储管道缓存可提高应用程序未来运行的性能，因为这样可以避免昂贵的着色器编译和管道构建步骤。

至于何时写入文件，目前尚未确定。可能会在关闭窗口而拆卸场景图时发生。因此，在QQuickWindow 完全销毁之前，应用程序不应假定文件的可用性。QQuickGraphicsConfiguration 只存储文件名，自身不执行任何实际的 I/O 和图形操作。

当运行的图形应用程序接口不适用或不支持检索管道缓存（或着色器/程序二进制文件）时，调用此函数没有任何作用。

调用此函数在很大程度上等同于将环境变量QSG_RHI_PIPELINE_CACHE_SAVE 设置为filename ，但有一个重要区别：此函数仅控制相关QQuickWindow 的管道缓存存储。因此，具有多个QQuickWindow 或QQuickView 实例的应用程序可以通过每个窗口专用的文件来存储和重新加载缓存内容。环境变量不允许这样做。

此功能在 Qt 6.5 中引入。

另请参阅 pipelineCacheSaveFile(),pipelineCacheLoadFile() 和 setPipelineCacheSaveFile()。

[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 设置为非零值。

默认值为 false。

此函数在 Qt 6.5 中引入。

另请参阅 prefersSoftwareDevice()。

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

启用后，GPU 时序数据将从支持此功能的平台和 3D API 的命令缓冲区中收集。这些数据会打印在渲染器日志中，可通过QSG_RENDER_TIMING 环境变量或日志类别（如qt.scenegraph.time.renderloop ）启用，其他模块（如Qt Quick 3D 的DebugView 项目）也可看到这些数据。

默认情况下禁用此功能，因为收集数据可能涉及额外工作，例如在命令流中插入时间戳查询，这取决于底层图形 API。要启用此功能，要么调用enable 并将其设置为 true，要么将QSG_RHI_PROFILE 环境变量设置为非零值。

预计支持时间戳查询的图形应用程序接口包括 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()。