class QOpenGLWindow#

The QOpenGLWindow class is a convenience subclass of QWindow to perform OpenGL painting. More…

Synopsis#

Methods#

def __init__()
def context()
def defaultFramebufferObject()
def doneCurrent()
def grabFramebuffer()
def isValid()
def makeCurrent()
def shareContext()
def updateBehavior()

Signals#

def frameSwapped()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description#

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:

initializeGL() to perform OpenGL resource initialization

resizeGL() to set up the transformation matrices and other window size dependent resources

paintGL() to issue OpenGL commands or draw using QPainter

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 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 setSwapInterval() on a description of the swap interval. With a swap interval of 1, which is the case on most systems by default, the 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.

Note

It is up to the application to ensure depth and stencil buffers are requested from the underlying windowing system interface. Without requesting a non-zero depth buffer size there is no guarantee that a depth buffer will be available, and as a result depth testing related OpenGL operations may fail to function as expected.

Commonly used depth and stencil buffer size requests are 24 and 8, respectively. For example, a QOpenGLWindow subclass could do this in its constructor:

QSurfaceFormat format;
format.setDepthBufferSize(24);
format.setStencilBufferSize(8);
setFormat(format);

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 Graphics.

class UpdateBehavior#

This enum describes the update strategy of the QOpenGLWindow .

Constant

Description

QOpenGLWindow.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.

QOpenGLWindow.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.

QOpenGLWindow.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.

Constant	Description
QOpenGLWindow.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.
QOpenGLWindow.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.
QOpenGLWindow.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.

__init__(shareContext[, updateBehavior=QOpenGLWindow.UpdateBehavior.NoPartialUpdate[, parent=None]])#

Parameters:

shareContext – QOpenGLContext
updateBehavior – UpdateBehavior
parent – QWindow

Constructs a new QOpenGLWindow with the given parent and updateBehavior. The QOpenGLWindow ‘s context will share with shareContext.

See also

UpdateBehavior shareContext

__init__([updateBehavior=QOpenGLWindow.UpdateBehavior.NoPartialUpdate[, parent=None]])

Parameters:

updateBehavior – UpdateBehavior
parent – QWindow

Constructs a new QOpenGLWindow with the given parent and updateBehavior.

See also

UpdateBehavior

context()#

Return type:: QOpenGLContext

Returns The QOpenGLContext used by this window or 0 if not yet initialized.

defaultFramebufferObject()#

Return type:: int

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.

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()

frameSwapped()#

This signal is emitted after the potentially blocking 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()#

Return type:: QImage

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.

Note

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() .

initializeGL()#

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()

isValid()#

Return type:: bool

Returns true if the window’s OpenGL resources, like the context, have been successfully initialized. Note that the return value is always false until the window becomes exposed (shown).

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.

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

context() paintGL() doneCurrent()

paintGL()#

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 performed in the current invocation of the function, the content is blitted or blended over the content drawn directly to the window in paintUnderGL() .