The QOpenGLWidget class is a widget for rendering OpenGL graphics.

QOpenGLWidget provides functionality for displaying OpenGL graphics integrated in a CopperSpice application. It is very simple to use: Make your class inherit from it and use the subclass like any other QWidget, except that you have the choice between using QPainter and standard OpenGL rendering commands.

QOpenGLWidget provides three convenient virtual functions you can reimplement in your subclass to perform the typical OpenGL tasks.

paintGL()

Renders the OpenGL scene. Gets called whenever the widget needs to be updated.

resizeGL()

Sets up the OpenGL viewport, projection, etc. Gets called whenever the widget has been resized (and also when it is shown for the first time because all newly created widgets get a resize event automatically).

initializeGL()

Sets up the OpenGL resources and state. Gets called once before the first time resizeGL() or paintGL() is called.

If you need to trigger a repaint from places other than paintGL() (a typical example is when using timers to animate scenes), you should call the widget's update() function to schedule an update.

Your widget's OpenGL rendering context is made current when paintGL(), resizeGL(), or initializeGL() is called. If you need to call the standard OpenGL API functions from other places (e.g. in your widget's constructor or in your own paint functions), you must call makeCurrent() first.

All rendering happens into an OpenGL framebuffer object. makeCurrent() ensure that it is bound in the context. Keep this in mind when creating and binding additional framebuffer objects in the rendering code in paintGL(). Never re-bind the framebuffer with ID 0. Instead, call defaultFramebufferObject() to get the ID that should be bound.

QOpenGLWidget allows using different OpenGL versions and profiles when the platform supports it. Just set the requested format via setFormat(). Keep in mind however that having multiple QOpenGLWidget instances in the same window requires that they all use the same format, or at least formats that do not make the contexts non-sharable. To overcome this issue, prefer using QSurfaceFormat::setDefaultFormat() instead of setFormat().

Note: Calling QSurfaceFormat::setDefaultFormat() before constructing the QApplication instance is mandatory on some platforms (for example, macOS) when an OpenGL core profile context is requested. This is to ensure that resource sharing between contexts stays functional as all internal contexts are created using the correct version and profile.

Painting Techniques

As described above, subclass QOpenGLWidget to render pure 3D content in the following way.

• Reimplement the initializeGL() and resizeGL() functions to set up the OpenGL state and provide a perspective transformation.
• Reimplement paintGL() to paint the 3D scene, calling only OpenGL functions.

It is also possible to draw 2D graphics onto a QOpenGLWidget subclass using QPainter.

• In paintGL(), instead of issuing OpenGL commands, construct a QPainter object for use on the widget.
• Draw primitives using QPainter's member functions.
• Direct OpenGL commands can still be issued. However, you must make sure these are enclosed by a call to the painter's beginNativePainting() and endNativePainting().

When performing drawing using QPainter only, it is also possible to perform the painting like it is done for ordinary widgets by reimplementing paintEvent().

• Reimplement the paintEvent() function.
• Construct a QPainter object targeting the widget. Either pass the widget to the constructor or the QPainter::begin() method.
• Draw primitives using QPainter's member functions.
• Painting finishes then the QPainter instance is destroyed. Alternatively, call QPainter::end() explicitly.

OpenGL Function Calls

When making OpenGL function calls, it is strongly recommended to avoid calling the functions directly. Instead, prefer using QOpenGLFunctions (when making portable applications) or the versioned variants (for example, QOpenGLFunctions_3_2_Core and similar, when targeting modern, desktop-only OpenGL). This way the application will work correctly in all build configurations, including the ones that perform dynamic OpenGL implementation loading which means applications are not directly linking to an GL implementation and thus direct function calls are not feasible.

In paintGL() the current context is always accessible by calling QOpenGLContext::currentContext(). From this context an already initialized, ready-to-be-used QOpenGLFunctions instance is retrievable by calling QOpenGLContext::functions(). An alternative to prefixing every GL call is to inherit from QOpenGLFunctions and call QOpenGLFunctions::initializeOpenGLFunctions() in initializeGL().

As for the OpenGL headers, note that in most cases there will be no need to directly include any headers like GL.h. The OpenGL-related CopperSpice headers will include qopengl.h which will in turn include an appropriate header for the system. This might be an OpenGL ES 3.x or 2.0 header, the highest version that is available, or a system-provided gl.h. In addition, a copy of the extension headers (called glext.h on some systems) is provided as part of CopperSpice both for OpenGL and OpenGL ES. These will get included automatically on platforms where feasible. This means that constants and function pointer typedefs from ARB, EXT, OES extensions are automatically available.

Note

Additional documentation pending.