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。

默认值为 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 实现的调试或验证层（如有）。

实际上，Vulkan 和 Direct 3D 11 均支持此功能，前提是运行时已安装并可使用必要的支持组件（验证层、Windows SDK）。当enable 为 true 时，Qt 将尝试在 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 等工具生成的帧捕获中显示出来。

预计支持此功能的图形 API 包括 Vulkan（如果可用 VK_EXT_debug_utils）、Direct 3D 11 和 Metal。

将enable 设为true后调用此函数，等同于将环境变量QSG_RHI_PROFILE 设置为非零值。

默认值为 false。

该函数在 Qt 6.5 中引入。

另请参阅 isDebugMarkersEnabled()。

void QQuickGraphicsConfiguration::setDepthBufferFor2D(bool enable)

将 2D 内容对深度缓冲区的使用设置为“enable ”。禁用后，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 和图形操作。 实际操作将在稍后进行，可能在另一个线程上执行。

当使用不支持或无法获取和重新加载管道缓存（或着色器/程序二进制文件）的图形 API 时，调用此函数将没有任何效果。

调用此函数基本上等同于将环境变量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 和图形操作。

当使用不支持或无法检索管道缓存（或着色器/程序二进制文件）的图形 API 时，调用此函数将无效果。

调用此函数基本上等同于将环境变量QSG_RHI_PIPELINE_CACHE_SAVE 设置为filename ，但有一个重要区别：此函数仅控制与之关联的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 设置为非零值。

默认值为 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 环境变量设置为非零值。

预计支持此功能的图形 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()。