CopperSpice API  1.7.2
QGLPixelBuffer Class Reference

The QGLPixelBuffer class encapsulates an OpenGL pbuffer. More...

Inheritance diagram for QGLPixelBuffer:
QPaintDevice

Public Methods

 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)
 
void deleteTexture (GLuint texture_id)
 
bool doneCurrent ()
 
void drawTexture (const QPointF &point, GLuint textureId, GLenum textureTarget=GL_TEXTURE_2D)
 
void drawTexture (const QRectF &target, GLuint textureId, GLenum textureTarget=GL_TEXTURE_2D)
 
QGLFormat format () const
 
GLuint generateDynamicTexture () const
 
Qt::HANDLE handle () const
 
bool isValid () const
 
bool makeCurrent ()
 
QPaintEnginepaintEngine () const override
 
void releaseFromDynamicTexture ()
 
QSize size () const
 
QImage toImage () const
 
void updateDynamicTexture (GLuint texture_id) const
 
- Public Methods inherited from QPaintDevice
virtual ~QPaintDevice ()
 
int colorCount () const
 
int depth () const
 
int devicePixelRatio () const
 
qreal devicePixelRatioF () const
 
int height () const
 
int heightMM () const
 
int logicalDpiX () const
 
int logicalDpiY () const
 
bool paintingActive () const
 
int physicalDpiX () const
 
int physicalDpiY () const
 
int width () const
 
int widthMM () const
 

Static Public Methods

static bool hasOpenGLPbuffers ()
 

Protected Methods

int metric (PaintDeviceMetric metric) const override
 
- Protected Methods inherited from QPaintDevice
 QPaintDevice ()
 

Additional Inherited Members

- Public Types inherited from QPaintDevice
enum  PaintDeviceMetric
 

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:

  1. We can draw into the pbuffer and convert it to a QImage using toImage(). This is normally much faster than calling QGLWidget::renderPixmap().
  2. 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.
  3. 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 Mac OS X systems that provide the render_texture extension. Under Windows a multi-sampled pbuffer can not be used in conjunction with the render_texture extension. If a multi-sampled pbuffer is requested under Windows, the render_texture extension is turned off for that pbuffer.

Threading

It is 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. Under X11, it's necessary to set the Qt::AA_X11InitThreads application attribute.

Pbuffers are provided by the OpenGL pbuffer extension; call hasOpenGLPbuffer() to find out if the system provides pbuffers.

See also
size(), format()

Constructor & Destructor 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).

See also
size(), format()
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).

See also
size(), format()
QGLPixelBuffer::~QGLPixelBuffer ( )
virtual

Destroys the pbuffer and frees any allocated resources.

Method Documentation

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

Binds the texture specified by texture_id to this pbuffer. Returns true on success, otherwise returns false.

The texture must be of the same size and format as the pbuffer.

To unbind the texture, call releaseFromDynamicTexture(). While the texture is bound, it is updated automatically when the pbuffer contents change, eliminating the need for additional copy operations.

Example:

QGLPixelBuffer pbuffer(...);
...
pbuffer.makeCurrent();
GLuint dynamicTexture = pbuffer.generateDynamicTexture();
pbuffer.bindToDynamicTexture(dynamicTexture);
...
pbuffer.releaseFromDynamicTexture();
Warning
This function uses the render_texture extension, which is currently not supported under X11. An alternative that works on all systems (including X11) is to manually copy the pbuffer contents to a texture using updateDynamicTexture().
For the bindToDynamicTexture() call to succeed on the Mac OS X, the pbuffer needs a shared context, i.e. the QGLPixelBuffer must be created with a share widget.
See also
generateDynamicTexture(), releaseFromDynamicTexture()
void QGLPixelBuffer::deleteTexture ( GLuint  texture_id)

Removes the texture identified by texture_id from the texture cache.

Equivalent to calling QGLContext::deleteTexture().

bool QGLPixelBuffer::doneCurrent ( )

Makes no context the current OpenGL context. Returns true on success, otherwise returns false.

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

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

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

Generates and binds a 2D GL texture that is the same size as the pbuffer, and returns the texture's ID. This can be used in conjunction with bindToDynamicTexture() and updateDynamicTexture().

See also
size()
Qt::HANDLE QGLPixelBuffer::handle ( ) const

Returns the native pbuffer handle.

bool QGLPixelBuffer::hasOpenGLPbuffers ( )
static

Returns true if the OpenGL pbuffer extension is present on this system, otherwise returns false.

bool QGLPixelBuffer::isValid ( ) const

Returns true if this pbuffer is valid, otherwise returns false.

bool QGLPixelBuffer::makeCurrent ( )

Makes this pbuffer the current OpenGL rendering context. Returns true on success, otherwise returns false.

See also
QGLContext::makeCurrent(), doneCurrent()
int QGLPixelBuffer::metric ( PaintDeviceMetric  metric) const
overrideprotectedvirtual

Reimplemented from QPaintDevice::metric().

Reimplemented from QPaintDevice.

QPaintEngine * QGLPixelBuffer::paintEngine ( ) const
overridevirtual

Reimplemented from QPaintDevice::paintEngine().

Implements QPaintDevice.

void QGLPixelBuffer::releaseFromDynamicTexture ( )

Releases the pbuffer from any previously bound texture.

See also
bindToDynamicTexture()
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 Mac OS X systems that support the render_texture extension is to use bindToDynamicTexture() to get dynamic updates of the texture.

See also
generateDynamicTexture(), bindToDynamicTexture()