QGLPixelBuffer Class Reference

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

#include <qglpixelbuffer.h>

Inheritance diagram for QGLPixelBuffer:

Public Functions
GLuint	bindTexture (const QImage &image, GLenum target=GL_TEXTURE_2D)
	Generates and binds a 2D GL texture to the current context, based on image. More...
GLuint	bindTexture (const QPixmap &pixmap, GLenum target=GL_TEXTURE_2D)
	Generates and binds a 2D GL texture based on pixmap. More...
GLuint	bindTexture (const QString &fileName)
	Reads the DirectDrawSurface (DDS) compressed file fileName and generates a 2D GL texture from it. More...
bool	bindToDynamicTexture (GLuint texture)
	Generates and binds a 2D GL texture that is the same size as the pbuffer, and returns the texture's ID. More...
void	deleteTexture (GLuint texture_id)
	Removes the texture identified by texture_id from the texture cache. More...
bool	doneCurrent ()
	Makes no context the current OpenGL context. More...
void	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. More...
void	drawTexture (const QPointF &point, GLuint textureId, GLenum textureTarget=GL_TEXTURE_2D)
	Draws the given texture, textureId, at the given point in OpenGL model space. More...
QGLFormat	format () const
	Returns the format of the pbuffer. More...
GLuint	generateDynamicTexture () const
Qt::HANDLE	handle () const
	Returns the native pbuffer handle. More...
bool	isValid () const
	Returns true if this pbuffer is valid; otherwise returns false. More...
bool	makeCurrent ()
	Makes this pbuffer the current OpenGL rendering context. More...
QPaintEngine *	paintEngine () const
	Reimplemented Function More...
	QGLPixelBuffer (const QSize &size, const QGLFormat &format=QGLFormat::defaultFormat(), QGLWidget *shareWidget=0)
	Constructs an OpenGL pbuffer of the given size. More...
	QGLPixelBuffer (int width, int height, const QGLFormat &format=QGLFormat::defaultFormat(), QGLWidget *shareWidget=0)
	Constructs an OpenGL pbuffer with the width and height. More...
void	releaseFromDynamicTexture ()
	Releases the pbuffer from any previously bound texture. More...
QSize	size () const
	Returns the size of the pbuffer. More...
QImage	toImage () const
	Returns the contents of the pbuffer as a QImage. More...
void	updateDynamicTexture (GLuint texture_id) const
	Copies the pbuffer contents into the texture specified with texture_id. More...
virtual	~QGLPixelBuffer ()
	Destroys the pbuffer and frees any allocated resources. More...
Public Functions inherited from QPaintDevice
int	colorCount () const
int	depth () const
virtual HDC	getDC () const
int	height () const
int	heightMM () const
int	logicalDpiX () const
int	logicalDpiY () const
QT_DEPRECATED int	numColors () const
bool	paintingActive () const
int	physicalDpiX () const
int	physicalDpiY () const
virtual void	releaseDC (HDC hdc) const
int	width () const
int	widthMM () const
virtual	~QPaintDevice ()

Static Public Functions
static bool	hasOpenGLPbuffers ()
	Returns true if the OpenGL pbuffer extension is present on this system; otherwise returns false. More...
Static Public Functions inherited from QPaintDevice
static QWSDisplay *	qwsDisplay ()

Protected Functions
int	devType () const
int	metric (PaintDeviceMetric metric) const
	Reimplemented Function More...
Protected Functions inherited from QPaintDevice
	QPaintDevice ()

Properties
QScopedPointer< QGLPixelBufferPrivate >	d_ptr

Friends
class	QGLContextPrivate
class	QGLDrawable
class	QGLPaintDevice
class	QGLPBufferGLPaintDevice
class	QGLWindowSurface

Additional Inherited Members
Public Types inherited from QPaintDevice
enum	PaintDeviceMetric {   PdmWidth = 1, PdmHeight, PdmWidthMM, PdmHeightMM,   PdmNumColors, PdmDepth, PdmDpiX, PdmDpiY,   PdmPhysicalDpiX, PdmPhysicalDpiY }
Protected Variables inherited from QPaintDevice
ushort	painters
Related Functions inherited from QPaintDevice
const Q_GUI_EXPORT QX11Info *	qt_x11Info (const QPaintDevice *pd)
	Returns the QX11Info structure for the pd paint device. More...

Detailed Description

The QGLPixelBuffer class encapsulates an OpenGL pbuffer.

Since

4.1

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. Note that under Windows, a multi-sampled pbuffer can't 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

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. Also, 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

{opengl/pbuffers}{Pbuffers Example}

Definition at line 56 of file qglpixelbuffer.h.

Constructors and Destructors

QGLPixelBuffer() [1/2]

QGLPixelBuffer::QGLPixelBuffer	(	const QSize &	size,
		const QGLFormat &	format = QGLFormat::defaultFormat(),
		QGLWidget *	shareWidget = 0
	)

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

Definition at line 184 of file qglpixelbuffer.cpp.

    : d_ptr(new QGLPixelBufferPrivate(this))
{
    Q_D(QGLPixelBuffer);
    d->common_init(size, format, shareWidget);
}

QGLPixelBuffer() [2/2]

QGLPixelBuffer::QGLPixelBuffer	(	int	width,
		int	height,
		const QGLFormat &	format = QGLFormat::defaultFormat(),
		QGLWidget *	shareWidget = 0
	)

Constructs an OpenGL pbuffer with the width and height.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

Definition at line 209 of file qglpixelbuffer.cpp.

    : d_ptr(new QGLPixelBufferPrivate(this))
{
    Q_D(QGLPixelBuffer);
    d->common_init(QSize(width, height), format, shareWidget);
}

~QGLPixelBuffer()

QGLPixelBuffer::~QGLPixelBuffer ( )

virtual

Destroys the pbuffer and frees any allocated resources.

Definition at line 224 of file qglpixelbuffer.cpp.

{
    Q_D(QGLPixelBuffer);

    // defined in qpaintengine_opengl.cpp
    QGLContext *current = const_cast<QGLContext *>(QGLContext::currentContext());
    if (current != d->qctx)
        makeCurrent();
    qgl_cleanup_glyph_cache(d->qctx);
    d->cleanup();
    delete d->qctx;
    if (current && current != d->qctx)
        current->makeCurrent();
}

Functions

bindTexture() [1/3]

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

Definition at line 509 of file qglpixelbuffer.cpp.

Referenced by bindTexture(), and QGLPixmapFilterBase::~QGLPixmapFilterBase().

{
    Q_D(QGLPixelBuffer);
#ifndef QT_OPENGL_ES
    return d->qctx->bindTexture(image, target, GLint(GL_RGBA8));
#else
    return d->qctx->bindTexture(image, target, GL_RGBA);
#endif
}

bindTexture() [2/3]

GLuint QGLPixelBuffer::bindTexture	(	const QPixmap &	pixmap,
		GLenum	target = GL_TEXTURE_2D
	)

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Equivalent to calling QGLContext::bindTexture().

See also

deleteTexture()

Definition at line 539 of file qglpixelbuffer.cpp.

{
    Q_D(QGLPixelBuffer);
#ifndef QT_OPENGL_ES
    return d->qctx->bindTexture(pixmap, target, GLint(GL_RGBA8));
#else
    return d->qctx->bindTexture(pixmap, target, GL_RGBA);
#endif
}

bindTexture() [3/3]

GLuint QGLPixelBuffer::bindTexture

(

const QString &

fileName

)

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Equivalent to calling QGLContext::bindTexture().

See also

deleteTexture()

Definition at line 570 of file qglpixelbuffer.cpp.

{
    Q_D(QGLPixelBuffer);
    return d->qctx->bindTexture(fileName);
}

bindToDynamicTexture()

bool QGLPixelBuffer::bindToDynamicTexture

(

GLuint

texture_id

)

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

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

Definition at line 160 of file qglpixelbuffer_egl.cpp.

Referenced by nearest_gl_texture_size(), and qt_format_to_attrib_list().

{
#if QGL_RENDER_TEXTURE
    Q_D(QGLPixelBuffer);
    if (d->invalid || d->textureFormat == EGL_NONE || !d->ctx)
        return false;
    glBindTexture(GL_TEXTURE_2D, texture_id);
    return eglBindTexImage(d->ctx->display(), d->pbuf, EGL_BACK_BUFFER);
#else
    Q_UNUSED(texture_id);
    return false;
#endif
}

deleteTexture()

void QGLPixelBuffer::deleteTexture

(

GLuint

texture_id

)

Removes the texture identified by texture_id from the texture cache.

Equivalent to calling QGLContext::deleteTexture().

Definition at line 581 of file qglpixelbuffer.cpp.

{
    Q_D(QGLPixelBuffer);
    d->qctx->deleteTexture(texture_id);
}

devType()

int QGLPixelBuffer::devType ( ) const

inlineprotectedvirtual

Warning

This function is not part of the public interface.

Reimplemented from QPaintDevice.

Definition at line 106 of file qglpixelbuffer.h.

{ return QInternal::Pbuffer; }

doneCurrent()

bool QGLPixelBuffer::doneCurrent

(

)

Makes no context the current OpenGL context.

Returns true on success; otherwise returns false.

Definition at line 268 of file qglpixelbuffer.cpp.

{
    Q_D(QGLPixelBuffer);
    if (d->invalid)
        return false;
    d->qctx->doneCurrent();
    return true;
}

drawTexture() [1/2]

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.

Since

4.4

The textureTarget should be a 2D texture target.

Equivalent to the corresponding QGLContext::drawTexture().

Definition at line 608 of file qglpixelbuffer.cpp.

Referenced by drawTexture().

{
    Q_D(QGLPixelBuffer);
    d->qctx->drawTexture(target, textureId, textureTarget);
}

drawTexture() [2/2]

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.

Since

4.4

The textureTarget parameter should be a 2D texture target.

Equivalent to the corresponding QGLContext::drawTexture().

Definition at line 634 of file qglpixelbuffer.cpp.

{
    Q_D(QGLPixelBuffer);
    d->qctx->drawTexture(point, textureId, textureTarget);
}

format()

QGLFormat QGLPixelBuffer::format

(

)

const

Returns the format of the pbuffer.

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

Definition at line 653 of file qglpixelbuffer.cpp.

Referenced by QGLWindowSurface::updateGeometry().

{
    Q_D(const QGLPixelBuffer);
    return d->format;
}

generateDynamicTexture()

GLuint QGLPixelBuffer::generateDynamicTexture

(

)

const

Definition at line 185 of file qglpixelbuffer_egl.cpp.

Referenced by doneCurrent(), and nearest_gl_texture_size().

{
#if QGL_RENDER_TEXTURE
    Q_D(const QGLPixelBuffer);
    GLuint texture;
    glGenTextures(1, &texture);
    glBindTexture(GL_TEXTURE_2D, texture);
    if (d->textureFormat == EGL_TEXTURE_RGB)
        glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB, d->req_size.width(), d->req_size.height(), 0, GL_RGB, GL_UNSIGNED_BYTE, 0);
    else
        glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, d->req_size.width(), d->req_size.height(), 0, GL_RGBA, GL_UNSIGNED_BYTE, 0);
    glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
    glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
    return texture;
#else
    return 0;
#endif
}

handle()

Qt::HANDLE QGLPixelBuffer::handle

(

)

const

Returns the native pbuffer handle.

Definition at line 411 of file qglpixelbuffer.cpp.

{
    Q_D(const QGLPixelBuffer);
    if (d->invalid)
        return 0;
    return (Qt::HANDLE) d->pbuf;
}

hasOpenGLPbuffers()

bool QGLPixelBuffer::hasOpenGLPbuffers ( )

static

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

Definition at line 204 of file qglpixelbuffer_egl.cpp.

Referenced by nearest_gl_texture_size(), and qt_format_to_attrib_list().

{
    // See if we have at least 1 configuration that matches the default format.
    EGLDisplay dpy = QEgl::display();
    if (dpy == EGL_NO_DISPLAY)
        return false;
    QEglProperties configProps;
    qt_eglproperties_set_glformat(configProps, QGLFormat::defaultFormat());
    configProps.setDeviceType(QInternal::Pbuffer);
    configProps.setRenderableType(QEgl::OpenGL);
    do {
        EGLConfig cfg = 0;
        EGLint matching = 0;
        if (eglChooseConfig(dpy, configProps.properties(),
                            &cfg, 1, &matching) && matching > 0)
            return true;
    } while (configProps.reduceConfiguration());
    return false;
}

isValid()

bool QGLPixelBuffer::isValid

(

)

const

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

Definition at line 422 of file qglpixelbuffer.cpp.

Referenced by QGLWindowSurface::updateGeometry().

{
    Q_D(const QGLPixelBuffer);
    return !d->invalid;
}

makeCurrent()

bool QGLPixelBuffer::makeCurrent

(

)

Makes this pbuffer the current OpenGL rendering context.

Returns true on success; otherwise returns false.

See also

QGLContext::makeCurrent(), doneCurrent()

Definition at line 250 of file qglpixelbuffer.cpp.

Referenced by QGLWindowSurface::flush(), QGLWindowSurface::scroll(), toImage(), QGLWindowSurface::updateGeometry(), and ~QGLPixelBuffer().

{
    Q_D(QGLPixelBuffer);
    if (d->invalid)
        return false;
    d->qctx->makeCurrent();
    return true;
}

metric()

int QGLPixelBuffer::metric ( PaintDeviceMetric  metric ) const

protectedvirtual

Reimplemented Function

Reimplemented from QPaintDevice.

Definition at line 452 of file qglpixelbuffer.cpp.

{
    Q_D(const QGLPixelBuffer);

    float dpmx = qt_defaultDpiX()*100./2.54;
    float dpmy = qt_defaultDpiY()*100./2.54;
    int w = d->req_size.width();
    int h = d->req_size.height();
    switch (metric) {
    case PdmWidth:
        return w;

    case PdmHeight:
        return h;

    case PdmWidthMM:
        return qRound(w * 1000 / dpmx);

    case PdmHeightMM:
        return qRound(h * 1000 / dpmy);

    case PdmNumColors:
        return 0;

    case PdmDepth:
        return 32;//d->depth;

    case PdmDpiX:
        return qRound(dpmx * 0.0254);

    case PdmDpiY:
        return qRound(dpmy * 0.0254);

    case PdmPhysicalDpiX:
        return qRound(dpmx * 0.0254);

    case PdmPhysicalDpiY:
        return qRound(dpmy * 0.0254);

    default:
        qWarning("QGLPixelBuffer::metric(), Unhandled metric type: %d\n", metric);
        break;
    }
    return 0;
}

paintEngine()

QPaintEngine * QGLPixelBuffer::paintEngine ( ) const

virtual

Reimplemented Function

Implements QPaintDevice.

Definition at line 437 of file qglpixelbuffer.cpp.

{
#if defined(QT_OPENGL_ES_1)
    return qt_buffer_engine()->engine();
#elif defined(QT_OPENGL_ES_2)
    return qt_buffer_2_engine()->engine();
#else
    if (qt_gl_preferGL2Engine())
        return qt_buffer_2_engine()->engine();
    else
        return qt_buffer_engine()->engine();
#endif
}

releaseFromDynamicTexture()

void QGLPixelBuffer::releaseFromDynamicTexture

(

)

Releases the pbuffer from any previously bound texture.

See also

bindToDynamicTexture()

Definition at line 174 of file qglpixelbuffer_egl.cpp.

Referenced by nearest_gl_texture_size(), and qt_format_to_attrib_list().

{
#if QGL_RENDER_TEXTURE
    Q_D(QGLPixelBuffer);
    if (d->invalid || d->textureFormat == EGL_NONE || !d->ctx)
        return;
    eglReleaseTexImage(d->ctx->display(), d->pbuf, EGL_BACK_BUFFER);
#endif
}

size()

QSize QGLPixelBuffer::size

(

)

const

Returns the size of the pbuffer.

Definition at line 389 of file qglpixelbuffer.cpp.

{
    Q_D(const QGLPixelBuffer);
    return d->req_size;
}

toImage()

QImage QGLPixelBuffer::toImage

(

)

const

Returns the contents of the pbuffer as a QImage.

Definition at line 398 of file qglpixelbuffer.cpp.

Referenced by QGLWindowSurface::buffer().

{
    Q_D(const QGLPixelBuffer);
    if (d->invalid)
        return QImage();

    const_cast<QGLPixelBuffer *>(this)->makeCurrent();
    return qt_gl_read_framebuffer(d->req_size, d->format.alpha(), true);
}

updateDynamicTexture()

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

Definition at line 366 of file qglpixelbuffer.cpp.

{
    Q_D(const QGLPixelBuffer);
    if (d->invalid)
        return;
    glBindTexture(GL_TEXTURE_2D, texture_id);
#ifndef QT_OPENGL_ES
    glCopyTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA8, 0, 0, d->req_size.width(), d->req_size.height(), 0);
#else
    glCopyTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, 0, 0, d->req_size.width(), d->req_size.height(), 0);
#endif
}

Friends and Related Functions

QGLContextPrivate

friend class QGLContextPrivate

friend

Definition at line 115 of file qglpixelbuffer.h.

QGLDrawable

friend class QGLDrawable

friend

Definition at line 111 of file qglpixelbuffer.h.

QGLPaintDevice

friend class QGLPaintDevice

friend

Definition at line 113 of file qglpixelbuffer.h.

QGLPBufferGLPaintDevice

friend class QGLPBufferGLPaintDevice

friend

Definition at line 114 of file qglpixelbuffer.h.

QGLWindowSurface

friend class QGLWindowSurface

friend

Definition at line 112 of file qglpixelbuffer.h.

Properties

d_ptr

QScopedPointer<QGLPixelBufferPrivate> QGLPixelBuffer::d_ptr

private

Definition at line 110 of file qglpixelbuffer.h.

Referenced by QGLWindowSurface::updateGeometry().

---

The documentation for this class was generated from the following files:

• /src/opengl/qglpixelbuffer.h
• /src/opengl/qglpixelbuffer.cpp
• /src/opengl/qglpixelbuffer_egl.cpp
• /src/opengl/qglpixelbuffer_mac.mm
• /src/opengl/qglpixelbuffer_stub.cpp
• /src/opengl/qglpixelbuffer_win.cpp
• /src/opengl/qglpixelbuffer_x11.cpp