com.trolltech.qt.opengl
Class QGLPixelBuffer

java.lang.Object
  extended by com.trolltech.qt.internal.QSignalEmitterInternal
      extended by com.trolltech.qt.QSignalEmitter
          extended by com.trolltech.qt.QtJambiObject
              extended by com.trolltech.qt.opengl.QGLPixelBuffer
All Implemented Interfaces:
QPaintDeviceInterface, QtJambiInterface

public class QGLPixelBuffer
extends QtJambiObject
implements QPaintDeviceInterface

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.


Nested Class Summary
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.AbstractSignal, QSignalEmitter.PrivateSignal0, QSignalEmitter.PrivateSignal1, QSignalEmitter.PrivateSignal2, QSignalEmitter.PrivateSignal3, QSignalEmitter.PrivateSignal4, QSignalEmitter.PrivateSignal5, QSignalEmitter.PrivateSignal6, QSignalEmitter.PrivateSignal7, QSignalEmitter.PrivateSignal8, QSignalEmitter.PrivateSignal9, QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9
 
Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal
 
Field Summary
 
Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
currentSender
 
Constructor Summary
QGLPixelBuffer(int width, int height)
          This is an overloaded member function, provided for convenience.
QGLPixelBuffer(int width, int height, QGLFormat format)
          This is an overloaded member function, provided for convenience.
QGLPixelBuffer(int width, int height, QGLFormat format, QGLWidget shareWidget)
          This is an overloaded member function, provided for convenience.
QGLPixelBuffer(QSize size)
          Constructs an OpenGL pbuffer of the given size.
QGLPixelBuffer(QSize size, QGLFormat format)
          Constructs an OpenGL pbuffer of the given size.
QGLPixelBuffer(QSize size, QGLFormat format, QGLWidget shareWidget)
          Constructs an OpenGL pbuffer of the given size.
 
Method Summary
 int bindTexture(QImage image)
          Generates and binds a 2D GL texture to the current context, based on image.
 int bindTexture(QImage image, int target)
          Generates and binds a 2D GL texture to the current context, based on image.
 int bindTexture(QPixmap pixmap)
          This is an overloaded member function, provided for convenience.
 int bindTexture(QPixmap pixmap, int target)
          This is an overloaded member function, provided for convenience.
 int bindTexture(java.lang.String fileName)
          This is an overloaded member function, provided for convenience.
 boolean bindToDynamicTexture(int texture)
          Binds the texture specified by texture_id to this pbuffer.
 void deleteTexture(int texture_id)
          Removes the texture identified by texture_id from the texture cache.
 int depth()
          Returns the bit depth (number of bit planes) of the paint device.
 boolean doneCurrent()
          Makes no context the current OpenGL context.
 void drawTexture(QPointF point, int textureId)
          Draws the given texture, textureId, at the given point in OpenGL model space.
 void drawTexture(QPointF point, int textureId, int textureTarget)
          Draws the given texture, textureId, at the given point in OpenGL model space.
 void drawTexture(QRectF target, int textureId)
          Draws the given texture, textureId, to the given target rectangle, target, in OpenGL model space.
 void drawTexture(QRectF target, int textureId, int textureTarget)
          Draws the given texture, textureId, to the given target rectangle, target, in OpenGL model space.
 QGLFormat format()
          Returns the format of the pbuffer.
 int generateDynamicTexture()
          Generates and binds a 2D GL texture that is the same size as the pbuffer, and returns the texture's ID.
 long handle()
          Returns the native pbuffer handle.
static boolean hasOpenGLPbuffers()
          Returns true if the OpenGL pbuffer extension is present on this system; otherwise returns false.
 int height()
          Returns the height of the paint device in default coordinate system units (e.
 int heightMM()
          Returns the height of the paint device in millimeters.
 boolean isValid()
          Returns true if this pbuffer is valid; otherwise returns false.
 int logicalDpiX()
          Returns the horizontal resolution of the device in dots per inch, which is used when computing font sizes.
 int logicalDpiY()
          Returns the vertical resolution of the device in dots per inch, which is used when computing font sizes.
 boolean makeCurrent()
          Makes this pbuffer the current OpenGL rendering context.
 int metric(QPaintDevice.PaintDeviceMetric metric)
          Returns the metric information for the given paint device metric.
 int numColors()
          Returns the number of different colors available for the paint device.
 QPaintEngine paintEngine()
          Returns a pointer to the paint engine used for drawing on the device.
 boolean paintingActive()
          Returns true if the device is currently being painted on, i.
 int physicalDpiX()
          Returns the horizontal resolution of the device in dots per inch.
 int physicalDpiY()
          Returns the horizontal resolution of the device in dots per inch.
 void releaseFromDynamicTexture()
          Releases the pbuffer from any previously bound texture.
 QSize size()
          Returns the size of the pbuffer.
 QImage toImage()
          Returns the contents of the pbuffer as a QImage.
 void updateDynamicTexture(int texture_id)
          Copies the pbuffer contents into the texture specified with texture_id.
 int width()
          Returns the width of the paint device in default coordinate system units (e.
 int widthMM()
          Returns the width of the paint device in millimeters.
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread
 
Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
__qt_signalInitialization
 
Methods inherited from class java.lang.Object
clone, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Constructor Detail

QGLPixelBuffer

public QGLPixelBuffer(QSize size,
                      QGLFormat format)
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

public QGLPixelBuffer(QSize size)
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

public QGLPixelBuffer(QSize size,
                      QGLFormat format,
                      QGLWidget shareWidget)
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

public QGLPixelBuffer(int width,
                      int height,
                      QGLFormat format)
This is an overloaded member function, provided for convenience.

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


QGLPixelBuffer

public QGLPixelBuffer(int width,
                      int height)
This is an overloaded member function, provided for convenience.

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


QGLPixelBuffer

public QGLPixelBuffer(int width,
                      int height,
                      QGLFormat format,
                      QGLWidget shareWidget)
This is an overloaded member function, provided for convenience.

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

Method Detail

bindTexture

public final int bindTexture(QImage image)
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().


bindTexture

public final int bindTexture(QImage image,
                             int target)
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().


bindTexture

public final int bindTexture(QPixmap pixmap)
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().


bindTexture

public final int bindTexture(QPixmap pixmap,
                             int target)
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().


bindTexture

public final int bindTexture(java.lang.String 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().


bindToDynamicTexture

public final boolean bindToDynamicTexture(int 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 = new QGLPixelBuffer(256, 256);
        //...
        pbuffer.makeCurrent();
        int 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().


deleteTexture

public final void deleteTexture(int texture_id)
Removes the texture identified by texture_id from the texture cache.

Equivalent to calling QGLContext::deleteTexture().


depth

public final int depth()
Returns the bit depth (number of bit planes) of the paint device.

Specified by:
depth in interface QPaintDeviceInterface

doneCurrent

public final boolean doneCurrent()
Makes no context the current OpenGL context. Returns true on success; otherwise returns false.


drawTexture

public final void drawTexture(QPointF point,
                              int textureId)
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().


drawTexture

public final void drawTexture(QPointF point,
                              int textureId,
                              int textureTarget)
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().


drawTexture

public final void drawTexture(QRectF target,
                              int textureId)
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().


drawTexture

public final void drawTexture(QRectF target,
                              int textureId,
                              int textureTarget)
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().


format

public final QGLFormat format()
Returns the format of the pbuffer. The format may be different from the one that was requested.


generateDynamicTexture

public final int generateDynamicTexture()
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().


handle

public final long handle()
Returns the native pbuffer handle.


height

public final int height()
Returns the height of the paint device in default coordinate system units (e. . pixels for QPixmap and QWidget).

See also:
heightMM().

Specified by:
height in interface QPaintDeviceInterface

heightMM

public final int heightMM()
Returns the height of the paint device in millimeters. Due to platform limitations it may not be possible to use this function to determine the actual physical size of a widget on the screen.

See also:
height().

Specified by:
heightMM in interface QPaintDeviceInterface

isValid

public final boolean isValid()
Returns true if this pbuffer is valid; otherwise returns false.


logicalDpiX

public final int logicalDpiX()
Returns the horizontal resolution of the device in dots per inch, which is used when computing font sizes. For X11, this is usually the same as could be computed from widthMM().

Note that if the logicalDpiX() doesn't equal the physicalDpiX(), the corresponding QPaintEngine must handle the resolution mapping.

See also:
logicalDpiY(), and physicalDpiX().

Specified by:
logicalDpiX in interface QPaintDeviceInterface

logicalDpiY

public final int logicalDpiY()
Returns the vertical resolution of the device in dots per inch, which is used when computing font sizes. For X11, this is usually the same as could be computed from heightMM().

Note that if the logicalDpiY() doesn't equal the physicalDpiY(), the corresponding QPaintEngine must handle the resolution mapping.

See also:
logicalDpiX(), and physicalDpiY().

Specified by:
logicalDpiY in interface QPaintDeviceInterface

makeCurrent

public final boolean makeCurrent()
Makes this pbuffer the current OpenGL rendering context. Returns true on success; otherwise returns false.

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


numColors

public final int numColors()
Returns the number of different colors available for the paint device. Since this value is an int, it will not be sufficient to represent the number of colors on 32 bit displays, in this case INT_MAX is returned instead.

Specified by:
numColors in interface QPaintDeviceInterface

paintingActive

public final boolean paintingActive()
Returns true if the device is currently being painted on, i. . someone has called QPainter::begin() but not yet called QPainter::end() for this device; otherwise returns false.

See also:
QPainter::isActive().

Specified by:
paintingActive in interface QPaintDeviceInterface

physicalDpiX

public final int physicalDpiX()
Returns the horizontal resolution of the device in dots per inch. For example, when printing, this resolution refers to the physical printer's resolution. The logical DPI on the other hand, refers to the resolution used by the actual paint engine.

Note that if the physicalDpiX() doesn't equal the logicalDpiX(), the corresponding QPaintEngine must handle the resolution mapping.

See also:
physicalDpiY(), and logicalDpiX().

Specified by:
physicalDpiX in interface QPaintDeviceInterface

physicalDpiY

public final int physicalDpiY()
Returns the horizontal resolution of the device in dots per inch. For example, when printing, this resolution refers to the physical printer's resolution. The logical DPI on the other hand, refers to the resolution used by the actual paint engine.

Note that if the physicalDpiY() doesn't equal the logicalDpiY(), the corresponding QPaintEngine must handle the resolution mapping.

See also:
physicalDpiX(), and logicalDpiY().

Specified by:
physicalDpiY in interface QPaintDeviceInterface

releaseFromDynamicTexture

public final void releaseFromDynamicTexture()
Releases the pbuffer from any previously bound texture.

See also:
bindToDynamicTexture().


size

public final QSize size()
Returns the size of the pbuffer.


toImage

public final QImage toImage()
Returns the contents of the pbuffer as a QImage.


updateDynamicTexture

public final void updateDynamicTexture(int 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 = new QGLPixelBuffer(256, 256);
        // ...
        pbuffer.makeCurrent();
        int 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().


width

public final int width()
Returns the width of the paint device in default coordinate system units (e. . pixels for QPixmap and QWidget).

See also:
widthMM().

Specified by:
width in interface QPaintDeviceInterface

widthMM

public final int widthMM()
Returns the width of the paint device in millimeters. Due to platform limitations it may not be possible to use this function to determine the actual physical size of a widget on the screen.

See also:
width().

Specified by:
widthMM in interface QPaintDeviceInterface

metric

public int metric(QPaintDevice.PaintDeviceMetric metric)
Returns the metric information for the given paint device metric.

See also:
PaintDeviceMetric .

Specified by:
metric in interface QPaintDeviceInterface

paintEngine

public QPaintEngine paintEngine()
Returns a pointer to the paint engine used for drawing on the device.

Specified by:
paintEngine in interface QPaintDeviceInterface

hasOpenGLPbuffers

public static boolean hasOpenGLPbuffers()
Returns true if the OpenGL pbuffer extension is present on this system; otherwise returns false.