com.trolltech.qt.opengl
Class QGLPixelBuffer

java.lang.Object
  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:
Example

Nested Class Summary
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.Signal0, QSignalEmitter.Signal1<A>, QSignalEmitter.Signal2<A,B>, QSignalEmitter.Signal3<A,B,C>, QSignalEmitter.Signal4<A,B,C,D>, QSignalEmitter.Signal5<A,B,C,D,E>, QSignalEmitter.Signal6<A,B,C,D,E,F>, QSignalEmitter.Signal7<A,B,C,D,E,F,G>, QSignalEmitter.Signal8<A,B,C,D,E,F,G,H>, QSignalEmitter.Signal9<A,B,C,D,E,F,G,H,I>
 
Constructor Summary
QGLPixelBuffer(int width, int height)
          Equivalent to QGLPixelBuffer(width, height, QGLFormat::defaultFormat(), 0).
QGLPixelBuffer(int width, int height, QGLFormat format)
          Equivalent to QGLPixelBuffer(width, height, format, 0).
QGLPixelBuffer(int width, int height, QGLFormat format, QGLWidget shareWidget)
          Constructs an OpenGL pbuffer with the width and height.
QGLPixelBuffer(QSize size)
          Equivalent to QGLPixelBuffer(size, QGLFormat::defaultFormat(), 0).
QGLPixelBuffer(QSize size, QGLFormat format)
          Equivalent to QGLPixelBuffer(size, format, 0).
QGLPixelBuffer(QSize size, QGLFormat format, QGLWidget shareWidget)
          Constructs an OpenGL pbuffer of the given size.
 
Method Summary
 int bindTexture(QImage image)
          Equivalent to bindTexture(image, GL_TEXTURE_2D).
 int bindTexture(QImage image, int target)
          Generates and binds a 2D GL texture to the current context, based on image.
 int bindTexture(QPixmap pixmap)
          Equivalent to bindTexture(pixmap, GL_TEXTURE_2D).
 int bindTexture(QPixmap pixmap, int target)
          Generates and binds a 2D GL texture based on pixmap.
 int bindTexture(java.lang.String fileName)
          Reads the DirectDrawSurface (DDS) compressed file fileName and generates a 2D GL texture from it.
 boolean bindToDynamicTexture(int texture)
          Binds the texture specified by texture 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.
 int devType()
          This function is reimplemented for internal reasons.
 boolean doneCurrent()
          Makes no context the current OpenGL context.
 QGLFormat format()
          Returns the format of the pbuffer.
static QGLPixelBuffer fromNativePointer(QNativePointer nativePointer)
          This function returns the QGLPixelBuffer instance pointed to by nativePointer
 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.g. pixels for QPixmap and QWidget).
 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()
          This function is reimplemented for internal reasons.
 boolean paintingActive()
          Returns true if the device is currently being painted on, i.e. someone has called QPainter::begin() but not yet called QPainter::end() for this device; otherwise returns false.
 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.g. pixels for QPixmap and QWidget).
 int widthMM()
          Returns the width of the paint device in millimeters.
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread
 
Methods inherited from class java.lang.Object
clone, equals, 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)

Equivalent to QGLPixelBuffer(size, format, 0).


QGLPixelBuffer

public QGLPixelBuffer(QSize size)

Equivalent to QGLPixelBuffer(size, QGLFormat::defaultFormat(), 0).


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, format

QGLPixelBuffer

public QGLPixelBuffer(int width,
                      int height,
                      QGLFormat format)

Equivalent to QGLPixelBuffer(width, height, format, 0).


QGLPixelBuffer

public QGLPixelBuffer(int width,
                      int height)

Equivalent to QGLPixelBuffer(width, height, QGLFormat::defaultFormat(), 0).


QGLPixelBuffer

public QGLPixelBuffer(int width,
                      int height,
                      QGLFormat format,
                      QGLWidget shareWidget)

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
Method Detail

bindTexture

public final int bindTexture(java.lang.String fileName)

Reads the DirectDrawSurface (DDS) compressed file fileName and generates a 2D GL texture from it.

Equivalent to calling QGLContext::bindTexture().

See Also:
deleteTexture

bindTexture

public final int bindTexture(QImage image)

Equivalent to bindTexture(image, GL_TEXTURE_2D).


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)

Equivalent to bindTexture(pixmap, GL_TEXTURE_2D).


bindTexture

public final int bindTexture(QPixmap pixmap,
                             int target)

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

Equivalent to calling QGLContext::bindTexture().

See Also:
deleteTexture

bindToDynamicTexture

public final boolean bindToDynamicTexture(int texture)

Binds the texture specified by texture 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, 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.


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.g. pixels for QPixmap and QWidget).

Specified by:
height in interface QPaintDeviceInterface
See Also:
heightMM

heightMM

public final int heightMM()

Returns the height of the paint device in millimeters.

Specified by:
heightMM in interface QPaintDeviceInterface
See Also:
height

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, but it varies on Windows.

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

Specified by:
logicalDpiX in interface QPaintDeviceInterface
See Also:
logicalDpiY, physicalDpiX

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, but it varies on Windows.

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

Specified by:
logicalDpiY in interface QPaintDeviceInterface
See Also:
logicalDpiX, physicalDpiY

makeCurrent

public final boolean makeCurrent()

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

See Also:
QGLContext::makeCurrent, 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.e. someone has called QPainter::begin() but not yet called QPainter::end() for this device; otherwise returns false.

Specified by:
paintingActive in interface QPaintDeviceInterface
See Also:
QPainter::isActive

physicalDpiX

public final int physicalDpiX()

Returns the horizontal resolution of the device in dots per inch.

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

Specified by:
physicalDpiX in interface QPaintDeviceInterface
See Also:
physicalDpiY, logicalDpiX

physicalDpiY

public final int physicalDpiY()

Returns the horizontal resolution of the device in dots per inch.

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

Specified by:
physicalDpiY in interface QPaintDeviceInterface
See Also:
physicalDpiX, logicalDpiY

releaseFromDynamicTexture

public final void releaseFromDynamicTexture()

Releases the pbuffer from any previously bound texture. Returns true on success; otherwise returns false.

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

width

public final int width()

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

Specified by:
width in interface QPaintDeviceInterface
See Also:
widthMM

widthMM

public final int widthMM()

Returns the width of the paint device in millimeters.

Specified by:
widthMM in interface QPaintDeviceInterface
See Also:
width

devType

public int devType()

This function is reimplemented for internal reasons.

Specified by:
devType in interface QPaintDeviceInterface

metric

public int metric(QPaintDevice.PaintDeviceMetric metric)

Returns the metric information for the given paint device metric.

Specified by:
metric in interface QPaintDeviceInterface
See Also:
PaintDeviceMetric

paintEngine

public QPaintEngine paintEngine()

This function is reimplemented for internal reasons.

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.


fromNativePointer

public static QGLPixelBuffer fromNativePointer(QNativePointer nativePointer)
This function returns the QGLPixelBuffer instance pointed to by nativePointer

Parameters:
nativePointer - the QNativePointer of which object should be returned.