|  | Home · All Classes · Modules

# QGLPixelBuffer Class Reference
[QtOpenGL module]

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

Inherits QPaintDevice.

### Methods

- __init__ (self, QSize size, QGLFormat format = QGLFormat::defaultFormat(), QGLWidget shareWidget = None)
- __init__ (self, int width, int height, QGLFormat format = QGLFormat::defaultFormat(), QGLWidget shareWidget = None)
- unsigned long bindTexture (self, QImage image, unsigned long target = GL_TEXTURE_2D)
- unsigned long bindTexture (self, QPixmap pixmap, unsigned long target = GL_TEXTURE_2D)
- unsigned long bindTexture (self, QString fileName)
- bool bindToDynamicTexture (self, unsigned long texture)
- deleteTexture (self, unsigned long texture_id)
- int devType (self)
- bool doneCurrent (self)
- drawTexture (self, QRectF target, unsigned long textureId, unsigned long textureTarget = GL_TEXTURE_2D)
- drawTexture (self, QPointF point, unsigned long textureId, unsigned long textureTarget = GL_TEXTURE_2D)
- QGLFormat format (self)
- unsigned long generateDynamicTexture (self)
- unsigned long handle (self)
- bool isValid (self)
- bool makeCurrent (self)
- int metric (self, QPaintDevice.PaintDeviceMetric metric)
- QPaintEngine paintEngine (self)
- releaseFromDynamicTexture (self)
- QSize size (self)
- QImage toImage (self)
- updateDynamicTexture (self, unsigned long texture_id)

### Static Methods

- bool hasOpenGLPbuffers ()

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

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

See also Pbuffers Example.

## Method Documentation

### QGLPixelBuffer.__init__ (self, QSize size, QGLFormat format = QGLFormat::defaultFormat(), QGLWidget shareWidget = None)

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

### QGLPixelBuffer.__init__ (self, int width, int height, QGLFormat format = QGLFormat::defaultFormat(), QGLWidget shareWidget = None)

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

### unsigned long QGLPixelBuffer.bindTexture (self, QImage image, unsigned long 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().

### unsigned long QGLPixelBuffer.bindTexture (self, QPixmap pixmap, unsigned long target = GL_TEXTURE_2D)

This is an overloaded member function, provided for convenience.

Generates and binds a 2D GL texture based on pixmap.

Equivalent to calling QGLContext.bindTexture().

See also deleteTexture().

### unsigned long QGLPixelBuffer.bindTexture (self, QString fileName)

This is an overloaded member function, provided for convenience.

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 (self, unsigned long texture)

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

Warning: 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() and releaseFromDynamicTexture().

### QGLPixelBuffer.deleteTexture (self, unsigned long texture_id)

Removes the texture identified by texture_id from the texture cache.

Equivalent to calling QGLContext.deleteTexture().

### int QGLPixelBuffer.devType (self)

### bool QGLPixelBuffer.doneCurrent (self)

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

### QGLPixelBuffer.drawTexture (self, QRectF target, unsigned long textureId, unsigned long 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.

### QGLPixelBuffer.drawTexture (self, QPointF point, unsigned long textureId, unsigned long textureTarget = GL_TEXTURE_2D)

This is an overloaded member function, provided for convenience.

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

Returns the format of the pbuffer. The format may be different from the one that was requested.

### unsigned long QGLPixelBuffer.generateDynamicTexture (self)

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

### unsigned long QGLPixelBuffer.handle (self)

Returns the native pbuffer handle.

### bool QGLPixelBuffer.hasOpenGLPbuffers ()

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

### bool QGLPixelBuffer.isValid (self)

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

### bool QGLPixelBuffer.makeCurrent (self)

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

See also QGLContext.makeCurrent() and doneCurrent().

### int QGLPixelBuffer.metric (self, QPaintDevice.PaintDeviceMetric metric)

### QPaintEngine QGLPixelBuffer.paintEngine (self)

### QGLPixelBuffer.releaseFromDynamicTexture (self)

Releases the pbuffer from any previously bound texture.

See also bindToDynamicTexture().

### QSize QGLPixelBuffer.size (self)

Returns the size of the pbuffer.

### QImage QGLPixelBuffer.toImage (self)

Returns the contents of the pbuffer as a QImage.

### QGLPixelBuffer.updateDynamicTexture (self, unsigned long texture_id)

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