QOpenGLTimeMonitor Class
QOpenGLTimeMonitor 类封装了一系列 OpenGL 定时器查询对象。更多内容...
| 头文件： | #include <QOpenGLTimeMonitor> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS OpenGL) target_link_libraries(mytarget PRIVATE Qt6::OpenGL) |
| qmake： | QT += opengl |
| 继承自： | QObject |
- 所有成员列表，包括继承的成员
- QOpenGLTimeMonitor 属于“3D 渲染”类别。
公共函数
| QOpenGLTimeMonitor(QObject *parent = nullptr) | |
| virtual | ~QOpenGLTimeMonitor() |
| bool | create() |
| void | destroy() |
| bool | isCreated() const |
| bool | isResultAvailable() const |
| QList<GLuint> | objectIds() const |
| int | recordSample() |
| void | reset() |
| int | sampleCount() const |
| void | setSampleCount(int sampleCount) |
| QList<GLuint64> | waitForIntervals() const |
| QList<GLuint64> | waitForSamples() const |
详细描述
QOpenGLTimeMonitor 类是一个便捷的封装类，它围绕一组 OpenGL 定时器查询对象构建，用于以渲染应用程序所需的时间粒度级别，测量 GPU 上的时间间隔。
OpenGL 计时器查询对象将按顺序进行查询，以记录渲染代码中感兴趣位置的 GPU 时间戳。一旦所有计时器查询的结果都准备就绪，即可获取这些结果，QOpenGLTimeMonitor 将为您计算记录的时间间隔。
该类的典型用例是分析应用程序的渲染算法，或者实时调整这些算法以实现动态的性能与质量平衡。
在渲染函数中使用 QOpenGLTimeMonitor 之前，您应通过调用 setSamples() 方法设置需要记录的采样点数量。请注意，测量 N 个采样点将产生 N-1 个时间间隔。 设置好采样点数量后，请使用有效的当前 OpenGL 上下文调用 `create()` 函数，以创建必要的查询计时器对象。这些步骤通常只需在初始化函数中执行一次。
使用recordSample()函数来限定包含需要计时OpenGL命令的代码块。您可以通过isResultAvailable()函数检查生成的时间采样值和时间间隔是否可用。计算出的时间间隔和原始时间戳采样值可分别通过阻塞函数waitForIntervals()和waitForSamples()获取。
在获取结果后、开始新一轮采样（例如在下一帧）之前，请务必调用reset() 函数，该函数将清除缓存的结果并将计时器索引重置为第一个计时器对象。
另请参阅 QOpenGLTimerQuery 。
成员函数文档
[explicit] QOpenGLTimeMonitor::QOpenGLTimeMonitor(QObject *parent = nullptr)
使用给定的parent 创建一个QOpenGLTimeMonitor实例。使用前，必须先调用create()并传入一个有效的OpenGL上下文。
另请参见 setSampleCount() 和create()。
[virtual noexcept] QOpenGLTimeMonitor::~QOpenGLTimeMonitor()
销毁QOpenGLTimeMonitor 及其底层的任何OpenGL资源。
bool QOpenGLTimeMonitor::create()
实例化sampleCount()，该函数用于创建OpenGL计时器查询对象，这些对象将用于跟踪在两次连续调用recordSample()之间执行OpenGL命令所花费的时间。
如果能够成功创建 OpenGL 定时器查询对象，则返回true 。
另请参阅 destroy()、setSampleCount() 和recordSample()。
void QOpenGLTimeMonitor::destroy()
销毁该实例中使用的所有 OpenGL 定时器查询对象。
另请参阅 create()。
bool QOpenGLTimeMonitor::isCreated() const
如果底层的 OpenGL 查询对象已创建，则返回 `true `。如果返回 `true ` 且关联的 OpenGL 上下文为当前上下文，则可以使用该对象记录时间采样点。
bool QOpenGLTimeMonitor::isResultAvailable() const
如果 OpenGL 计时器查询结果已可用，则返回true 。
另请参阅 waitForSamples() 和waitForIntervals()。
QList<GLuint> QOpenGLTimeMonitor::objectIds() const
返回一个QList ，其中包含 OpenGL 定时器查询对象的对象 ID。
int QOpenGLTimeMonitor::recordSample()
在此处向 OpenGL 命令队列发出 OpenGL 计时器查询。在应用程序的渲染函数中按顺序调用此函数，将累积记录两次连续调用该函数之间，GPU 执行 OpenGL 命令所耗费的时间详情。
另请参阅 setSampleCount()、isResultAvailable()、waitForSamples() 以及waitForIntervals()。
void QOpenGLTimeMonitor::reset()
重置时间监视器，使其准备好在下一帧渲染中使用。在获取上一次结果后，且在下一帧首次调用recordSample()之前，请调用此函数。
另请参阅 recordSample()。
int QOpenGLTimeMonitor::sampleCount() const
返回通过setSampleCount()请求的采样点数量。如果在调用setSampleCount()后成功调用了create()，则返回的值即为实际可用的采样点数量。
采样计数的默认值为 2，这将导致测量单个间隔。
另请参阅 setSampleCount()。
void QOpenGLTimeMonitor::setSampleCount(int sampleCount)
将采样点数设置为sampleCount 。使用此函数设置采样点数后，必须调用create() 来实例化底层的 OpenGL 定时器查询对象。
新的sampleCount 值必须不小于2。
另请参阅 sampleCount()、create() 和recordSample()。
QList<GLuint64> QOpenGLTimeMonitor::waitForIntervals() const
返回一个QList ，其中包含由recordSample()调用所划分的时段。由于该向量表示的是时间间隔而非实际的时间戳样本，因此其元素数量将比原始数据少一个。
该函数将阻塞，直到 OpenGL 指示结果可用为止。建议在调用该函数时，先通过isResultAvailable() 检查结果是否可用。
另请参阅 waitForSamples() 和isResultAvailable()。
QList<GLuint64> QOpenGLTimeMonitor::waitForSamples() const
返回一个QList ，其中包含使用recordSample()获取的GPU时间戳。
该函数将阻塞，直到 OpenGL 指示结果已可用。建议在调用isResultAvailable() 之前，先检查结果是否可用。
注意：此 函数仅在具有 OpenGL >=3.3 或 ARB_timer_query 扩展的系统上有效。更多详细信息请参阅QOpenGLTimerQuery 。
另请参阅 waitForIntervals() 和isResultAvailable()。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
