QGLPixelBuffer Class
The QGLPixelBuffer class encapsulates an OpenGL pbuffer. More...
Header: | #include <QGLPixelBuffer> |
qmake: | QT += opengl |
Since: | Qt 4.1 |
Inherits: | QPaintDevice |
This class is obsolete. It is provided to keep old source code working. We strongly advise against using it in new code.
Public Functions
QGLPixelBuffer(const QSize &size, const QGLFormat &format = QGLFormat::defaultFormat(), QGLWidget *shareWidget = nullptr) | |
QGLPixelBuffer(int width, int height, const QGLFormat &format = QGLFormat::defaultFormat(), QGLWidget *shareWidget = nullptr) | |
virtual | ~QGLPixelBuffer() |
GLuint | bindTexture(const QImage &image, GLenum target = GL_TEXTURE_2D) |
GLuint | bindTexture(const QPixmap &pixmap, GLenum target = GL_TEXTURE_2D) |
GLuint | bindTexture(const QString &fileName) |
bool | bindToDynamicTexture(GLuint texture) |
QGLContext * | context() const |
void | deleteTexture(GLuint texture_id) |
bool | doneCurrent() |
void | drawTexture(const QRectF &target, GLuint textureId, GLenum textureTarget = GL_TEXTURE_2D) |
void | drawTexture(const QPointF &point, GLuint textureId, GLenum textureTarget = GL_TEXTURE_2D) |
QGLFormat | format() const |
GLuint | generateDynamicTexture() const |
Qt::HANDLE | handle() const |
bool | isValid() const |
bool | makeCurrent() |
void | releaseFromDynamicTexture() |
QSize | size() const |
QImage | toImage() const |
void | updateDynamicTexture(GLuint texture_id) const |
Reimplemented Public Functions
virtual QPaintEngine * | paintEngine() const override |
- 14 public functions inherited from QPaintDevice
Static Public Members
bool | hasOpenGLPbuffers() |
Reimplemented Protected Functions
virtual int | devType() const override |
virtual int | metric(QPaintDevice::PaintDeviceMetric metric) const override |
- 1 protected function inherited from QPaintDevice
Additional Inherited Members
- 1 protected function inherited from QPaintDevice
- 1 protected type inherited from QPaintDevice
Detailed Description
The QGLPixelBuffer class encapsulates an OpenGL pbuffer.
Rendering into a pbuffer is normally done using full hardware acceleration. This can be significantly faster than rendering into a QPixmap.
There are three approaches to using this class:
- We can draw into the pbuffer and convert it to a QImage using toImage(). This is normally much faster than calling QGLWidget::renderPixmap().
- We can draw into the pbuffer and copy the contents into an OpenGL texture using updateDynamicTexture(). This allows us to create dynamic textures and works on all systems with pbuffer support.
- On systems that support it, we can bind the pbuffer to an OpenGL texture. The texture is then updated automatically when the pbuffer contents change, eliminating the need for additional copy operations. This is supported only on Windows and macOS systems that provide the
render_texture
extension. Note that under Windows, a multi-sampled pbuffer can't be used in conjunction with therender_texture
extension. If a multi-sampled pbuffer is requested under Windows, therender_texture
extension is turned off for that pbuffer.
Note: This class has been deprecated, use QOpenGLFramebufferObject for offscreen rendering.
Threading
As of Qt 4.8, it's possible to render into a QGLPixelBuffer using a QPainter in a separate thread. Note that OpenGL 2.0 or OpenGL ES 2.0 is required for this to work.
Pbuffers are provided by the OpenGL pbuffer
extension; call hasOpenGLPbuffer() to find out if the system provides pbuffers.
Member Function Documentation
QGLPixelBuffer::QGLPixelBuffer(const QSize &size, const QGLFormat &format = QGLFormat::defaultFormat(), QGLWidget *shareWidget = nullptr)
Constructs an OpenGL pbuffer of the given size. If no format is specified, the default format is used. If the shareWidget parameter points to a valid QGLWidget, the pbuffer will share its context with shareWidget.
If you intend to bind this pbuffer as a dynamic texture, the width and height components of size
must be powers of two (e.g., 512 x 128).
QGLPixelBuffer::QGLPixelBuffer(int width, int height, const QGLFormat &format = QGLFormat::defaultFormat(), QGLWidget *shareWidget = nullptr)
This is an overloaded function.
Constructs an OpenGL pbuffer with the width and height. If no format is specified, the default format is used. If the shareWidget parameter points to a valid QGLWidget, the pbuffer will share its context with shareWidget.
If you intend to bind this pbuffer as a dynamic texture, the width and height components of size
must be powers of two (e.g., 512 x 128).
[virtual]
QGLPixelBuffer::~QGLPixelBuffer()
Destroys the instance of QGLPixelBuffer. The destructor is virtual.
GLuint QGLPixelBuffer::bindTexture(const QImage &image, GLenum target = GL_TEXTURE_2D)
Generates and binds a 2D GL texture to the current context, based on image. The generated texture id is returned and can be used in later glBindTexture() calls.
The target parameter specifies the texture target.
Equivalent to calling QGLContext::bindTexture().
See also deleteTexture().
GLuint QGLPixelBuffer::bindTexture(const QPixmap &pixmap, GLenum target = GL_TEXTURE_2D)
This is an overloaded function.
Generates and binds a 2D GL texture based on pixmap.
Equivalent to calling QGLContext::bindTexture().
See also deleteTexture().
GLuint QGLPixelBuffer::bindTexture(const QString &fileName)
This is an overloaded function.
Reads the DirectDrawSurface (DDS) compressed file fileName and generates a 2D GL texture from it.
Equivalent to calling QGLContext::bindTexture().
See also deleteTexture().
bool QGLPixelBuffer::bindToDynamicTexture(GLuint texture)
QGLContext *QGLPixelBuffer::context() const
Returns the context of this pixelbuffer.
void QGLPixelBuffer::deleteTexture(GLuint texture_id)
Removes the texture identified by texture_id from the texture cache.
Equivalent to calling QGLContext::deleteTexture().
[override virtual protected]
int QGLPixelBuffer::devType() const
bool QGLPixelBuffer::doneCurrent()
void QGLPixelBuffer::drawTexture(const QRectF &target, GLuint textureId, GLenum textureTarget = GL_TEXTURE_2D)
Draws the given texture, textureId, to the given target rectangle, target, in OpenGL model space. The textureTarget should be a 2D texture target.
Equivalent to the corresponding QGLContext::drawTexture().
This function was introduced in Qt 4.4.
void QGLPixelBuffer::drawTexture(const QPointF &point, GLuint textureId, GLenum textureTarget = GL_TEXTURE_2D)
Draws the given texture, textureId, at the given point in OpenGL model space. The textureTarget parameter should be a 2D texture target.
Equivalent to the corresponding QGLContext::drawTexture().
This function was introduced in Qt 4.4.
QGLFormat QGLPixelBuffer::format() const
Returns the format of the pbuffer. The format may be different from the one that was requested.
GLuint QGLPixelBuffer::generateDynamicTexture() const
Qt::HANDLE QGLPixelBuffer::handle() const
Returns the native pbuffer handle.
[static]
bool QGLPixelBuffer::hasOpenGLPbuffers()
bool QGLPixelBuffer::isValid() const
Returns true
if this pbuffer is valid; otherwise returns false
.
bool QGLPixelBuffer::makeCurrent()
[override virtual protected]
int QGLPixelBuffer::metric(QPaintDevice::PaintDeviceMetric metric) const
Reimplemented from QPaintDevice::metric().
[override virtual]
QPaintEngine *QGLPixelBuffer::paintEngine() const
Reimplemented from QPaintDevice::paintEngine().
void QGLPixelBuffer::releaseFromDynamicTexture()
QSize QGLPixelBuffer::size() const
Returns the size of the pbuffer.
QImage QGLPixelBuffer::toImage() const
Returns the contents of the pbuffer as a QImage.
void QGLPixelBuffer::updateDynamicTexture(GLuint texture_id) const
Copies the pbuffer contents into the texture specified with texture_id.
The texture must be of the same size and format as the pbuffer.
Example:
QGLPixelBuffer pbuffer(...); ... pbuffer.makeCurrent(); GLuint dynamicTexture = pbuffer.generateDynamicTexture(); ... pbuffer.updateDynamicTexture(dynamicTexture);
An alternative on Windows and macOS systems that support the render_texture
extension is to use bindToDynamicTexture() to get dynamic updates of the texture.
See also generateDynamicTexture() and bindToDynamicTexture().