The QOpenGLWindow class is a convenience subclass of QWindow to perform OpenGL painting. More...
#include <qopenglwindow.h>
Public Types | |
| enum | UpdateBehavior { NoPartialUpdate , PartialUpdateBlit , PartialUpdateBlend } |
 Public Types inherited from QSurface | |
| enum | SurfaceClass { Window , Offscreen } |
| enum | SurfaceType { RasterSurface , OpenGLSurface , RasterGLSurface , OpenVGSurface , VulkanSurface , MetalSurface , Direct3DSurface } |
| Public Types inherited from QPaintDevice | |
| enum | PaintDeviceMetric { PdmWidth = 1 , PdmHeight , PdmWidthMM , PdmHeightMM , PdmNumColors , PdmDepth , PdmDpiX , PdmDpiY , PdmPhysicalDpiX , PdmPhysicalDpiY , PdmDevicePixelRatio , PdmDevicePixelRatioScaled } |
Signals | |
| void | frameSwapped () |
| Signals inherited from QWindow | |
| void | screenChanged (QScreen *screen) |
| void | modalityChanged (Qt::WindowModality modality) |
| void | windowStateChanged (Qt::WindowState windowState) |
| Q_REVISION (2, 2) void windowTitleChanged(const QString &title) | |
| void | xChanged (int arg) |
| void | yChanged (int arg) |
| void | widthChanged (int arg) |
| void | heightChanged (int arg) |
| void | minimumWidthChanged (int arg) |
| void | minimumHeightChanged (int arg) |
| void | maximumWidthChanged (int arg) |
| void | maximumHeightChanged (int arg) |
| void | visibleChanged (bool arg) |
| Q_REVISION(2, 1) void visibilityChanged(QWindow | Q_REVISION (2, 1) void activeChanged() |
| void | contentOrientationChanged (Qt::ScreenOrientation orientation) |
| void | focusObjectChanged (QObject *object) |
| Q_REVISION (2, 1) void opacityChanged(qreal opacity) | |
| Q_REVISION (2, 13) void transientParentChanged(QWindow *transientParent) | |
| Signals inherited from QObject | |
| void | destroyed (QObject *=nullptr) |
| void | objectNameChanged (const QString &objectName, QPrivateSignal) |
Additional Inherited Members | |
| Public Slots inherited from QPaintDeviceWindow | |
| void | update () |
| Public Slots inherited from QWindow | |
| Q_REVISION (2, 1) void requestActivate() | |
| void | setVisible (bool visible) |
| void | show () |
| void | hide () |
| void | showMinimized () |
| void | showMaximized () |
| void | showFullScreen () |
| void | showNormal () |
| bool | close () |
| void | raise () |
| void | lower () |
| bool | startSystemResize (Qt::Edges edges) |
| Start a system-specific resize operation. More... | |
| bool | startSystemMove () |
| Start a system-specific move operation. More... | |
| void | setTitle (const QString &) |
| void | setX (int arg) |
| void | setY (int arg) |
| void | setWidth (int arg) |
| void | setHeight (int arg) |
| void | setGeometry (int posx, int posy, int w, int h) |
| void | setGeometry (const QRect &rect) |
| Sets the geometry of the window, excluding its window frame, to rect. More... | |
| void | setMinimumWidth (int w) |
| void | setMinimumHeight (int h) |
| void | setMaximumWidth (int w) |
| void | setMaximumHeight (int h) |
| Q_REVISION (2, 1) void alert(int msec) | |
| Q_REVISION (2, 3) void requestUpdate() | |
| Public Slots inherited from QObject | |
| void | deleteLater () |
| 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) |
| 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::FunctionPointer< Func2 >::Object *receiver, Func2 slot, Qt::ConnectionType type=Qt::AutoConnection) |
| static QMetaObject::Connection ::type | connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 slot) |
| static QMetaObject::Connection ::type | connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const QObject *context, Func2 slot, Qt::ConnectionType type=Qt::AutoConnection) |
| template<typename Func1 , typename Func2 > | |
| static std::enable_if< QtPrivate::FunctionPointer< Func2 >::ArgumentCount==-1 &&!std::is_convertible_v< Func2, const char * >, QMetaObject::Connection >::type | connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 slot) |
| template<typename Func1 , typename Func2 > | |
| static std::enable_if< QtPrivate::FunctionPointer< Func2 >::ArgumentCount==-1 &&!std::is_convertible_v< Func2, const char * >, QMetaObject::Connection >::type | connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const QObject *context, Func2 slot, Qt::ConnectionType type=Qt::AutoConnection) |
| static bool | disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member) |
| static bool | disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member) |
| static bool | disconnect (const QMetaObject::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) |
| Static Public Member Functions inherited from QPaintDevice | |
| static qreal | devicePixelRatioFScale () |
| Protected Attributes inherited from QObject | |
| QScopedPointer< QObjectData > | d_ptr |
| Protected Attributes inherited from QSurface | |
| SurfaceClass | m_type |
| QSurfacePrivate * | m_reserved |
| Protected Attributes inherited from QPaintDevice | |
| ushort | painters |
| Properties inherited from QPaintDeviceWindow | |
| int | width |
| the width of the window's geometry More... | |
| int | height |
| the height of the window's geometry More... | |
| Properties inherited from QWindow | |
| QString | title |
| the window's title in the windowing system More... | |
| Qt::WindowModality | modality |
| the modality of the window More... | |
| Qt::WindowFlags | flags |
| the window flags of the window More... | |
| int | x |
| the x position of the window's geometry More... | |
| int | y |
| the y position of the window's geometry More... | |
| int | width |
| the width of the window's geometry More... | |
| int | height |
| the height of the window's geometry More... | |
| int | minimumWidth |
| the minimum width of the window's geometry More... | |
| int | minimumHeight |
| the minimum height of the window's geometry More... | |
| int | maximumWidth |
| the maximum width of the window's geometry More... | |
| int | maximumHeight |
| the maximum height of the window's geometry More... | |
| bool | visible |
| whether the window is visible or not More... | |
| bool | active |
| the active status of the window More... | |
| Visibility | visibility |
| the screen-occupation state of the window More... | |
| Qt::ScreenOrientation | contentOrientation |
| the orientation of the window's contents More... | |
| qreal | opacity |
| The opacity of the window in the windowing system. More... | |
| Properties inherited from QObject | |
| QString | objectName |
| the name of this object More... | |
| Related Functions inherited from QObject | |
| template< class T > T | qobject_cast (const QObject *object) |
| template< typename T > T | qFindChildqFindChildren (const QObject *obj, const QString &name)() |
| template< typename T > QList< T > | qFindChildrenqFindChildren (const QObject *obj, const QString &name)() |
| QObjectList | |
Detailed Description
The QOpenGLWindow class is a convenience subclass of QWindow to perform OpenGL painting.
\inmodule QtOpenGL
- Since
- 5.4
QOpenGLWindow is an enhanced QWindow that allows easily creating windows that perform OpenGL rendering using an API that is compatible with QOpenGLWidget Unlike QOpenGLWidget, QOpenGLWindow has no dependency on the widgets module and offers better performance.
A typical application will subclass QOpenGLWindow and reimplement the following virtual functions:
\list
- initializeGL() to perform OpenGL resource initialization
- resizeGL() to set up the transformation matrices and other window size dependent resources
\endlist
To schedule a repaint, call the update() function. Note that this will not immediately result in a call to paintGL(). Calling update() multiple times in a row will not change the behavior in any way.
This is a slot so it can be connected to a \l QTimer::timeout() signal to perform animation. Note however that in the modern OpenGL world it is a much better choice to rely on synchronization to the vertical refresh rate of the display. See \l{QSurfaceFormat::setSwapInterval()}{setSwapInterval()} on a description of the swap interval. With a swap interval of 1, which is the case on most systems by default, the \l{QOpenGLContext::swapBuffers()}{swapBuffers()} call, that is executed internally by QOpenGLWindow after each repaint, will block and wait for vsync. This means that whenever the swap is done, an update can be scheduled again by calling update(), without relying on timers.
To request a specific configuration for the context, use setFormat() like for any other QWindow. This allows, among others, requesting a given OpenGL version and profile, or enabling depth and stencil buffers.
Unlike QWindow, QOpenGLWindow allows opening a painter on itself and perform QPainter-based drawing.
QOpenGLWindow supports multiple update behaviors. The default, NoPartialUpdate is equivalent to a regular, OpenGL-based QWindow. In contrast, PartialUpdateBlit and PartialUpdateBlend are more in line with QOpenGLWidget's way of working, where there is always an extra, dedicated framebuffer object present. These modes allow, by sacrificing some performance, redrawing only a smaller area on each paint and having the rest of the content preserved from of the previous frame. This is useful for applications than render incrementally using QPainter, because this way they do not have to redraw the entire window content on each paintGL() call.
Similarly to QOpenGLWidget, QOpenGLWindow supports the Qt::AA_ShareOpenGLContexts attribute. When enabled, the OpenGL contexts of all QOpenGLWindow instances will share with each other. This allows accessing each other's shareable OpenGL resources.
For more information on graphics in Qt, see \l {Graphics}.
Definition at line 55 of file qopenglwindow.h.
Member Enumeration Documentation
◆ UpdateBehavior
This enum describes the update strategy of the QOpenGLWindow.
\value NoPartialUpdate Indicates that the entire window surface will redrawn on each update and so no additional framebuffers are needed. This is the setting used in most cases and is equivalent to how drawing directly via QWindow would function.
\value PartialUpdateBlit Indicates that the drawing performed in paintGL() does not cover the entire window. In this case an extra framebuffer object is created under the hood, and rendering performed in paintGL() will target this framebuffer. This framebuffer is then blitted onto the window surface's default framebuffer after each paint. This allows having QPainter-based drawing code in paintGL() which only repaints a smaller area at a time, because, unlike NoPartialUpdate, the previous content is preserved.
\value PartialUpdateBlend Similar to PartialUpdateBlit, but instead of using framebuffer blits, the contents of the extra framebuffer is rendered by drawing a textured quad with blending enabled. This, unlike PartialUpdateBlit, allows alpha blended content and works even when the glBlitFramebuffer is not available. Performance-wise this setting is likely to be somewhat slower than PartialUpdateBlit.
| Enumerator | |
|---|---|
| NoPartialUpdate | |
| PartialUpdateBlit | |
| PartialUpdateBlend | |
Definition at line 61 of file qopenglwindow.h.
Constructor & Destructor Documentation
◆ QOpenGLWindow() [1/2]
|
explicit |
Constructs a new QOpenGLWindow with the given parent and updateBehavior.
- See also
- QOpenGLWindow::UpdateBehavior
Definition at line 351 of file qopenglwindow.cpp.
◆ QOpenGLWindow() [2/2]
|
explicit |
Constructs a new QOpenGLWindow with the given parent and updateBehavior. The QOpenGLWindow's context will share with shareContext.
Definition at line 362 of file qopenglwindow.cpp.
◆ ~QOpenGLWindow()
| QOpenGLWindow::~QOpenGLWindow | ( | ) |
Destroys the QOpenGLWindow instance, freeing its resources.
The OpenGLWindow's context is made current in the destructor, allowing for safe destruction of any child object that may need to release OpenGL resources belonging to the context provided by this window.
- Warning
- if you have objects wrapping OpenGL resources (such as QOpenGLBuffer, QOpenGLShaderProgram, etc.) as members of a QOpenGLWindow subclass, you may need to add a call to makeCurrent() in that subclass' destructor as well. Due to the rules of C++ object destruction, those objects will be destroyed {before} calling this function (but after that the destructor of the subclass has run), therefore making the OpenGL context current in this function happens too late for their safe disposal.
- See also
- makeCurrent
- Since
- 5.5
Definition at line 387 of file qopenglwindow.cpp.
Member Function Documentation
◆ context()
| QOpenGLContext * QOpenGLWindow::context | ( | ) | const |
- Returns
- The QOpenGLContext used by this window or
0if not yet initialized.
Definition at line 477 of file qopenglwindow.cpp.
◆ defaultFramebufferObject()
| GLuint QOpenGLWindow::defaultFramebufferObject | ( | ) | const |
The framebuffer object handle used by this window.
When the update behavior is set to NoPartialUpdate, there is no separate framebuffer object. In this case the returned value is the ID of the default framebuffer.
Otherwise the value of the ID of the framebuffer object or 0 if not yet initialized.
Definition at line 502 of file qopenglwindow.cpp.
◆ doneCurrent()
| void QOpenGLWindow::doneCurrent | ( | ) |
Releases the context.
It is not necessary to call this function in most cases, since the widget will make sure the context is bound and released properly when invoking paintGL().
- See also
- makeCurrent()
Definition at line 464 of file qopenglwindow.cpp.
◆ frameSwapped
|
signal |
This signal is emitted after the potentially blocking \l{QOpenGLContext::swapBuffers()}{buffer swap} has been done. Applications that wish to continuously repaint synchronized to the vertical refresh, should issue an update() upon this signal. This allows for a much smoother experience compared to the traditional usage of timers.
◆ grabFramebuffer()
| QImage QOpenGLWindow::grabFramebuffer | ( | ) |
Returns a copy of the framebuffer.
- Note
- This is a potentially expensive operation because it relies on glReadPixels() to read back the pixels. This may be slow and can stall the GPU pipeline.
-
When used together with update behavior
NoPartialUpdate, the returned image may not contain the desired content when called after the front and back buffers have been swapped (unless preserved swap is enabled in the underlying windowing system interface). In this mode the function reads from the back buffer and the contents of that may not match the content on the screen (the front buffer). In this case the only place where this function can safely be used is paintGL() or paintOverGL().
Definition at line 528 of file qopenglwindow.cpp.
◆ initializeGL()
|
protectedvirtual |
This virtual function is called once before the first call to paintGL() or resizeGL(). Reimplement it in a subclass.
This function should set up any required OpenGL resources and state.
There is no need to call makeCurrent() because this has already been done when this function is called. Note however that the framebuffer, in case partial update mode is used, is not yet available at this stage, so avoid issuing draw calls from here. Defer such calls to paintGL() instead.
- See also
- paintGL(), resizeGL()
Reimplemented in Window, GLWindow, and GLWindow.
Definition at line 554 of file qopenglwindow.cpp.
◆ isValid()
| bool QOpenGLWindow::isValid | ( | ) | const |
- Returns
trueif the window's OpenGL resources, like the context, have been successfully initialized. Note that the return value is alwaysfalseuntil the window becomes exposed (shown).
Definition at line 406 of file qopenglwindow.cpp.
◆ makeCurrent()
| void QOpenGLWindow::makeCurrent | ( | ) |
Prepares for rendering OpenGL content for this window by making the corresponding context current and binding the framebuffer object, if there is one, in that context context.
It is not necessary to call this function in most cases, because it is called automatically before invoking paintGL(). It is provided nonetheless to support advanced, multi-threaded scenarios where a thread different than the GUI or main thread may want to update the surface or framebuffer contents. See QOpenGLContext for more information on threading related issues.
This function is suitable for calling also when the underlying platform window is already destroyed. This means that it is safe to call this function from a QOpenGLWindow subclass' destructor. If there is no native window anymore, an offscreen surface is used instead. This ensures that OpenGL resource cleanup operations in the destructor will always work, as long as this function is called first.
- See also
- QOpenGLContext, context(), paintGL(), doneCurrent()
Definition at line 432 of file qopenglwindow.cpp.
◆ metric()
|
overrideprotectedvirtual |
Reimplemented from QPaintDeviceWindow.
Definition at line 672 of file qopenglwindow.cpp.
◆ paintEvent()
|
overrideprotectedvirtual |
Paint event handler. Calls paintGL().
- See also
- paintGL()
Reimplemented from QPaintDeviceWindow.
Reimplemented in Window, PaintWindow, PainterWindow, and Window.
Definition at line 650 of file qopenglwindow.cpp.
◆ paintGL()
|
protectedvirtual |
This virtual function is called whenever the window contents needs to be painted. Reimplement it in a subclass.
There is no need to call makeCurrent() because this has already been done when this function is called.
Before invoking this function, the context and the framebuffer, if there is one, are bound, and the viewport is set up by a call to glViewport(). No other state is set and no clearing or drawing is performed by the framework.
- Note
- When using a partial update behavior, like
PartialUpdateBlend, the output of the previous paintGL() call is preserved and, after the additional drawing perfomed in the current invocation of the function, the content is blitted or blended over the content drawn directly to the window in paintUnderGL().
Reimplemented in PaintUnderOverWindow, PartialPainterWindow, PainterWindow, Window, OpenGLWindow, GLWindow, Window, and GLWindow.
Definition at line 599 of file qopenglwindow.cpp.
◆ paintOverGL()
|
protectedvirtual |
This virtual function is called after each invocation of paintGL().
When the update mode is set to NoPartialUpdate, there is no difference between this function and paintGL(), performing rendering in either of them leads to the same result.
Like paintUnderGL(), rendering in this function targets the default framebuffer of the window, regardless of the update behavior. It gets called after paintGL() has returned and the blit (PartialUpdateBlit) or quad drawing (PartialUpdateBlend) has been done.
- See also
- paintGL(), paintUnderGL(), UpdateBehavior
Reimplemented in PaintUnderOverWindow.
Definition at line 641 of file qopenglwindow.cpp.
◆ paintUnderGL()
|
protectedvirtual |
The virtual function is called before each invocation of paintGL().
When the update mode is set to NoPartialUpdate, there is no difference between this function and paintGL(), performing rendering in either of them leads to the same result.
The difference becomes significant when using PartialUpdateBlend, where an extra framebuffer object is used. There, paintGL() targets this additional framebuffer object, which preserves its contents, while paintUnderGL() and paintOverGL() target the default framebuffer, i.e. directly the window surface, the contents of which is lost after each displayed frame.
- Note
- Avoid relying on this function when the update behavior is
PartialUpdateBlit. This mode involves blitting the extra framebuffer used by paintGL() onto the default framebuffer after each invocation of paintGL(), thus overwriting all drawing generated in this function.
- See also
- paintGL(), paintOverGL(), UpdateBehavior
Reimplemented in PaintUnderOverWindow.
Definition at line 623 of file qopenglwindow.cpp.
◆ redirected()
|
overrideprotectedvirtual |
Reimplemented from QPaintDevice.
Definition at line 690 of file qopenglwindow.cpp.
◆ resizeEvent()
|
overrideprotectedvirtual |
Resize event handler. Calls resizeGL().
- See also
- resizeGL()
Reimplemented from QWindow.
Reimplemented in Window, and Window.
Definition at line 661 of file qopenglwindow.cpp.
◆ resizeGL()
|
protectedvirtual |
This virtual function is called whenever the widget has been resized. Reimplement it in a subclass. The new size is passed in w and h.
- Note
- This is merely a convenience function in order to provide an API that is compatible with QOpenGLWidget. Unlike with QOpenGLWidget, derived classes are free to choose to override resizeEvent() instead of this function.
- Avoid issuing OpenGL commands from this function as there may not be a context current when it is invoked. If it cannot be avoided, call makeCurrent().
- Scheduling updates from here is not necessary. The windowing systems will send expose events that trigger an update automatically.
- See also
- initializeGL(), paintGL()
Reimplemented in Window, OpenGLWindow, GLWindow, and GLWindow.
Definition at line 574 of file qopenglwindow.cpp.
◆ shareContext()
| QOpenGLContext * QOpenGLWindow::shareContext | ( | ) | const |
- Returns
- The QOpenGLContext requested to be shared with this window's QOpenGLContext.
Definition at line 486 of file qopenglwindow.cpp.
◆ updateBehavior()
| QOpenGLWindow::UpdateBehavior QOpenGLWindow::updateBehavior | ( | ) | const |
- Returns
- the update behavior for this QOpenGLWindow.
Definition at line 395 of file qopenglwindow.cpp.
The documentation for this class was generated from the following files:
- src/opengl/qopenglwindow.h
- src/opengl/qopenglwindow.cpp
