Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
Public Member Functions | List of all members
QOpenGLTimerQuery Class Reference

The QOpenGLTimerQuery class wraps an OpenGL timer query object. More...

#include <qopengltimerquery.h>

+ Inheritance diagram for QOpenGLTimerQuery:
+ Collaboration diagram for QOpenGLTimerQuery:

Public Member Functions

 QOpenGLTimerQuery (QObject *parent=nullptr)
 Creates a QOpenGLTimerQuery instance with the given parent.
 
 ~QOpenGLTimerQuery ()
 Destroys the QOpenGLTimerQuery and the underlying OpenGL resource.
 
bool create ()
 Creates the underlying OpenGL timer query object.
 
void destroy ()
 Destroys the underlying OpenGL timer query object.
 
bool isCreated () const
 Returns true if the underlying OpenGL query object has been created.
 
GLuint objectId () const
 Returns the id of the underlying OpenGL query object.
 
void begin ()
 Marks the start point in the OpenGL command queue for a sequence of commands to be timed by this query object.
 
void end ()
 Marks the end point in the OpenGL command queue for a sequence of commands to be timed by this query object.
 
GLuint64 waitForTimestamp () const
 Returns the current timestamp of the GPU when all previously issued OpenGL commands have been received but not necessarily executed by the GPU.
 
void recordTimestamp ()
 Places a marker in the OpenGL command queue for the GPU to record the timestamp when this marker is reached by the GPU.
 
bool isResultAvailable () const
 Returns true if the OpenGL timer query result is available.
 
GLuint64 waitForResult () const
 Returns the result of the OpenGL timer query.
 
- Public Member Functions inherited from QObject
Q_INVOKABLE QObject (QObject *parent=nullptr)
 Constructs an object with parent object parent.
 
virtual ~QObject ()
 Destroys the object, deleting all its child objects.
 
virtual bool event (QEvent *event)
 This virtual function receives events to an object and should return true if the event e was recognized and processed.
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 Filters events if this object has been installed as an event filter for the watched object.
 
QString objectName () const
 
Q_WEAK_OVERLOAD void setObjectName (const QString &name)
 Sets the object's name to name.
 
void setObjectName (QAnyStringView name)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
QBindable< QString > bindableObjectName ()
 
bool isWidgetType () const
 Returns true if the object is a widget; otherwise returns false.
 
bool isWindowType () const
 Returns true if the object is a window; otherwise returns false.
 
bool isQuickItemType () const
 Returns true if the object is a QQuickItem; otherwise returns false.
 
bool signalsBlocked () const noexcept
 Returns true if signals are blocked; otherwise returns false.
 
bool blockSignals (bool b) noexcept
 If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).
 
QThread * thread () const
 Returns the thread in which the object lives.
 
bool moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
 Changes the thread affinity for this object and its children and returns true on success.
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.
 
int startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)
 
void killTimer (int id)
 Kills the timer with timer identifier, id.
 
void killTimer (Qt::TimerId id)
 
template<typename T >
T findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.
 
template<typename T >
QList< T > findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.
 
template<typename T >
T findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
template<typename T >
QList< T > findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
const QObjectList & children () const
 Returns a list of child objects.
 
void setParent (QObject *parent)
 Makes the object a child of parent.
 
void installEventFilter (QObject *filterObj)
 Installs an event filter filterObj on this object.
 
void removeEventFilter (QObject *obj)
 Removes an event filter object obj from this object.
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
 
bool disconnect (const char *signal=nullptr, const QObject *receiver=nullptr, const char *member=nullptr) const
 
bool disconnect (const QObject *receiver, const char *member=nullptr) const
 
void dumpObjectTree () const
 Dumps a tree of children to the debug output.
 
void dumpObjectInfo () const
 Dumps information about signal connections, etc.
 
bool setProperty (const char *name, const QVariant &value)
 Sets the value of the object's name property to value.
 
bool setProperty (const char *name, QVariant &&value)
 
QVariant property (const char *name) const
 Returns the value of the object's name property.
 
QList< QByteArray > dynamicPropertyNames () const
 
QBindingStorage * bindingStorage ()
 
const QBindingStorage * bindingStorage () const
 
QObject * parent () const
 Returns a pointer to the parent object.
 
bool inherits (const char *classname) const
 Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false.
 

Additional Inherited Members

- Public Slots inherited from QObject
void deleteLater ()
 \threadsafe
 
- Signals inherited from QObject
void destroyed (QObject *=nullptr)
 This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.
 
void objectNameChanged (const QString &objectName, QPrivateSignal)
 This signal is emitted after the object's name has been changed.
 
- Static Public Member Functions inherited from QObject
static QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
 \threadsafe
 
static QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
 
template<typename Func1 , typename Func2 >
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType *context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)
 
template<typename Func1 , typename Func2 >
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)
 
static bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
 \threadsafe
 
static bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
 
static bool disconnect (const QMetaObject::Connection &)
 Disconnect a connection.
 
template<typename Func1 , typename Func2 >
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object *receiver, Func2 slot)
 
template<typename Func1 >
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const QObject *receiver, void **zero)
 
- Protected Member Functions inherited from QObject
QObject * sender () const
 Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.
 
int senderSignalIndex () const
 
int receivers (const char *signal) const
 Returns the number of receivers connected to the signal.
 
bool isSignalConnected (const QMetaMethod &signal) const
 
virtual void timerEvent (QTimerEvent *event)
 This event handler can be reimplemented in a subclass to receive timer events for the object.
 
virtual void childEvent (QChildEvent *event)
 This event handler can be reimplemented in a subclass to receive child events.
 
virtual void customEvent (QEvent *event)
 This event handler can be reimplemented in a subclass to receive custom events.
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
 QObject (QObjectPrivate &dd, QObject *parent=nullptr)
 
- Protected Attributes inherited from QObject
QScopedPointer< QObjectData > d_ptr
 
- Properties inherited from QObject
QString objectName
 the name of this object
 
- Related Symbols inherited from QObject
 Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr.
 
 
 
 \macro Q_CLASSINFO(Name, Value)
 

Detailed Description

The QOpenGLTimerQuery class wraps an OpenGL timer query object.

\inmodule QtOpenGL

Since
5.1

OpenGL timer query objects are OpenGL managed resources to measure the execution times of sequences of OpenGL commands on the GPU.

OpenGL offers various levels of support for timer queries, depending on the version of OpenGL you have and the presence of the ARB_timer_query or EXT_timer_query extensions. The support can be summarized as:

\list

  • OpenGL >=3.3 offers full support for all timer query functionality.
  • OpenGL 3.2 with the ARB_timer_query extension offers full support for all timer query functionality.
  • OpenGL <=3.2 with the EXT_timer_query extension offers limited support in that the timestamp of the GPU cannot be queried. Places where this impacts functions provided by Qt classes will be highlighted in the function documentation.
  • OpenGL ES 2 (and OpenGL ES 3) do not provide any support for OpenGL timer queries. \endlist

OpenGL represents time with a granularity of 1 nanosecond (1e-9 seconds). As a consequence of this, 32-bit integers would only give a total possible duration of approximately 4 seconds, which would not be difficult to exceed in poorly performing or lengthy operations. OpenGL therefore uses 64 bit integer types to represent times. A GLuint64 variable has enough width to contain a duration of hundreds of years, which is plenty for real-time rendering needs.

As with the other Qt OpenGL classes, QOpenGLTimerQuery has a create() function to create the underlying OpenGL object. This is to allow the developer to ensure that there is a valid current OpenGL context at the time.

Once created, timer queries can be issued in one of several ways. The simplest method is to delimit a block of commands with calls to begin() and end(). This instructs OpenGL to measure the time taken from completing all commands issued prior to begin() until the completion of all commands issued prior to end().

At the end of a frame we can retrieve the results by calling waitForResult(). As this function's name implies, it blocks CPU execution until OpenGL notifies that the timer query result is available. To avoid blocking, you can check if the query result is available by calling isResultAvailable(). Note that modern GPUs are deeply pipelined and query results may not become available for between 1-5 frames after they were issued.

Note that OpenGL does not permit nesting or interleaving of multiple timer queries using begin() and end(). Using multiple timer queries and recordTimestamp() avoids this limitation. When using recordTimestamp() the result can be obtained at some later time using isResultAvailable() and waitForResult(). Qt provides the convenience class QOpenGLTimeMonitor that helps with using multiple query objects.

See also
QOpenGLTimeMonitor

Definition at line 18 of file qopengltimerquery.h.

Constructor & Destructor Documentation

◆ QOpenGLTimerQuery()

QOpenGLTimerQuery::QOpenGLTimerQuery ( QObject * parent = nullptr)
explicit

Creates a QOpenGLTimerQuery instance with the given parent.

You must call create() with a valid OpenGL context before using.

Definition at line 264 of file qopengltimerquery.cpp.

◆ ~QOpenGLTimerQuery()

QOpenGLTimerQuery::~QOpenGLTimerQuery ( )

Destroys the QOpenGLTimerQuery and the underlying OpenGL resource.

Definition at line 272 of file qopengltimerquery.cpp.

Member Function Documentation

◆ begin()

void QOpenGLTimerQuery::begin ( )

Marks the start point in the OpenGL command queue for a sequence of commands to be timed by this query object.

This is useful for simple use-cases. Usually it is better to use recordTimestamp().

See also
end(), isResultAvailable(), waitForResult(), recordTimestamp()

Definition at line 347 of file qopengltimerquery.cpp.

◆ create()

bool QOpenGLTimerQuery::create ( )

Creates the underlying OpenGL timer query object.

There must be a valid OpenGL context that supports query objects current for this function to succeed.

Returns true if the OpenGL timer query object was successfully created.

Definition at line 303 of file qopengltimerquery.cpp.

◆ destroy()

void QOpenGLTimerQuery::destroy ( )

Destroys the underlying OpenGL timer query object.

The context that was current when create() was called must be current when calling this function.

Definition at line 313 of file qopengltimerquery.cpp.

◆ end()

void QOpenGLTimerQuery::end ( )

Marks the end point in the OpenGL command queue for a sequence of commands to be timed by this query object.

This is useful for simple use-cases. Usually it is better to use recordTimestamp().

See also
begin(), isResultAvailable(), waitForResult(), recordTimestamp()

Definition at line 361 of file qopengltimerquery.cpp.

◆ isCreated()

bool QOpenGLTimerQuery::isCreated ( ) const

Returns true if the underlying OpenGL query object has been created.

If this returns true and the associated OpenGL context is current, then you are able to issue queries with this object.

Definition at line 324 of file qopengltimerquery.cpp.

◆ isResultAvailable()

bool QOpenGLTimerQuery::isResultAvailable ( ) const

Returns true if the OpenGL timer query result is available.

This function is non-blocking and ideally should be used to check for the availability of the query result before calling waitForResult().

See also
waitForResult()

Definition at line 406 of file qopengltimerquery.cpp.

◆ objectId()

GLuint QOpenGLTimerQuery::objectId ( ) const

Returns the id of the underlying OpenGL query object.

Definition at line 333 of file qopengltimerquery.cpp.

◆ recordTimestamp()

void QOpenGLTimerQuery::recordTimestamp ( )

Places a marker in the OpenGL command queue for the GPU to record the timestamp when this marker is reached by the GPU.

This function is non-blocking and the result will become available at some later time.

The availability of the result can be checked with isResultAvailable(). The result can be fetched with waitForResult() which will block if the result is not yet available.

See also
waitForResult(), isResultAvailable(), begin(), end()

Definition at line 378 of file qopengltimerquery.cpp.

◆ waitForResult()

GLuint64 QOpenGLTimerQuery::waitForResult ( ) const

Returns the result of the OpenGL timer query.

This function will block until the result is made available by OpenGL. It is recommended to call isResultAvailable() to ensure that the result is available to avoid unnecessary blocking and stalling.

See also
isResultAvailable()

Definition at line 421 of file qopengltimerquery.cpp.

◆ waitForTimestamp()

GLuint64 QOpenGLTimerQuery::waitForTimestamp ( ) const

Returns the current timestamp of the GPU when all previously issued OpenGL commands have been received but not necessarily executed by the GPU.

This function blocks until the result is returned.

See also
recordTimestamp()

Definition at line 392 of file qopengltimerquery.cpp.

The documentation for this class was generated from the following files: