The QOpenGLFramebufferObject class encapsulates an OpenGL framebuffer object. More...

Public Types
enum	Attachment

Public Methods
	QOpenGLFramebufferObject (const QSize &size, Attachment attachment, GLenum target=GL_TEXTURE_2D, GLenum internalFormat=0)

	QOpenGLFramebufferObject (const QSize &size, const QOpenGLFramebufferObjectFormat &format)

	QOpenGLFramebufferObject (const QSize &size, GLenum target=GL_TEXTURE_2D)

	QOpenGLFramebufferObject (int width, int height, Attachment attachment, GLenum target=GL_TEXTURE_2D, GLenum internalFormat=0)

	QOpenGLFramebufferObject (int width, int height, const QOpenGLFramebufferObjectFormat &format)

	QOpenGLFramebufferObject (int width, int height, GLenum target=GL_TEXTURE_2D)

virtual	~QOpenGLFramebufferObject ()

void	addColorAttachment (const QSize &size, GLenum internalFormat=0)

void	addColorAttachment (int width, int height, GLenum internalFormat=0)

Attachment	attachment () const

bool	bind ()

QOpenGLFramebufferObjectFormat	format () const

GLuint	handle () const

int	height () const

bool	isBound () const

bool	isValid () const

bool	release ()

void	setAttachment (Attachment attachment)

QSize	size () const

QVector< QSize >	sizes () const

GLuint	takeTexture ()

GLuint	takeTexture (int colorAttachmentIndex)

GLuint	texture () const

QVector< GLuint >	textures () const

QImage	toImage () const

QImage	toImage (bool flipped) const

QImage	toImage (bool flipped, int colorAttachmentIndex) const

int	width () const

Static Public Methods
static bool	bindDefault ()

static void	blitFramebuffer (QOpenGLFramebufferObject target, const QRect &targetRect, QOpenGLFramebufferObject source, const QRect &sourceRect, GLbitfield buffers, GLenum filter, int readColorAttachmentIndex, int drawColorAttachmentIndex)

static void	blitFramebuffer (QOpenGLFramebufferObject target, const QRect &targetRect, QOpenGLFramebufferObject source, const QRect &sourceRect, GLbitfield buffers=GL_COLOR_BUFFER_BIT, GLenum filter=GL_NEAREST)

static void	blitFramebuffer (QOpenGLFramebufferObject target, QOpenGLFramebufferObject source, GLbitfield buffers=GL_COLOR_BUFFER_BIT, GLenum filter=GL_NEAREST)

static bool	hasOpenGLFramebufferBlit ()

static bool	hasOpenGLFramebufferObjects ()

Friends
class	QOpenGLPaintDevice

Detailed Description

The QOpenGLFramebufferObject class encapsulates an OpenGL framebuffer object defined by the GL_EXT_framebuffer_object extension. It provides a rendering surface which can be painted on with a QPainter with the help of QOpenGLPaintDevice, or rendered to using native OpenGL calls. This surface can be bound and used as a regular texture in your own OpenGL drawing code. By default, the QOpenGLFramebufferObject class generates a 2D OpenGL texture (using the GL_TEXTURE_2D target), which is used as the internal rendering target.

It is important to have a current OpenGL context when creating a QOpenGLFramebufferObject, otherwise initialization will fail.

Create a new QOpenGLFrameBufferObject with the Attachment::CombinedDepthStencil if you want QPainter to render correctly. You will need to create the QOpenGLFramebufferObject with more than one sample per pixel for primitives to be antialiased when drawing using a QPainter. To create a multisample framebuffer object you should use one of the constructors which use a QOpenGLFramebufferObjectFormat parameter and then set the QOpenGLFramebufferObjectFormat::samples property to a non-zero value.

Multisample

For multisample framebuffer objects a color render buffer is created, otherwise a texture with the specified texture target is created. The color render buffer or texture will have the specified internal format, and will be bound to the GL_COLOR_ATTACHMENT0 attachment in the framebuffer object.

Multiple render targets are also supported, in case the OpenGL implementation supports this. Here there will be multiple textures (or, in case of multisampling, renderbuffers) present and each of them will get attached to GL_COLOR_ATTACHMENT0, 1, 2, etc.

If you want to use a framebuffer object with multisampling enabled as a texture, you first need to copy from it to a regular framebuffer object using QOpenGLContext::blitFramebuffer().

Multithreading

It is possible to draw into a QOpenGLFramebufferObject using QPainter and QOpenGLPaintDevice in a separate thread.

Member Enumeration Documentation

enum QOpenGLFramebufferObject::Attachment

This enum is used to control whether or not transient parents should be considered ancestors.

Constant	Value	Description
`QOpenGLFramebufferObject::NoAttachment`	`0`	No attachment is added to the framebuffer object. The OpenGL depth and stencil tests will not work when rendering to a framebuffer object without any depth or stencil buffers. This is the default value.
`QOpenGLFramebufferObject::CombinedDepthStencil`	`1`	If the GL_EXT_packed_depth_stencil extension is present, a combined depth and stencil buffer is attached. If the extension is not present, only a depth buffer is attached.
`QOpenGLFramebufferObject::Depth`	`2`	A depth buffer is attached to the framebuffer object.

Constructor & Destructor Documentation

QOpenGLFramebufferObject::QOpenGLFramebufferObject	(	const QSize &	size,
		GLenum	target = `GL_TEXTURE_2D`
	)

explicit

Constructs an QOpenGLFramebufferObject and binds a 2D OpenGL texture to the buffer using the size. The texture is bound to the GL_COLOR_ATTACHMENT0 target in the framebuffer object.

The target is used to specify the OpenGL texture target. The GL_TEXTURE_2D textures must have a power of 2 width and height like 256 x 512, unless you are using OpenGL 2.0 or higher.

By default no depth or stencil buffers are attached. This behavior can be toggled using one of the overloaded constructors. The default texture format is GL_RGBA8 for desktop OpenGL, and GL_RGBA for OpenGL/ES.

See also: attachment(), size(), texture()

QOpenGLFramebufferObject::QOpenGLFramebufferObject	(	int	width,
		int	height,
		GLenum	target = `GL_TEXTURE_2D`
	)

Constructs an QOpenGLFramebufferObject and binds a 2D OpenGL texture to the buffer using the given width and height.

See also: size(), texture()

QOpenGLFramebufferObject::QOpenGLFramebufferObject	(	const QSize &	size,
		QOpenGLFramebufferObject::Attachment	attachment,
		GLenum	target = `GL_TEXTURE_2D`,
		GLenum	internalFormat = `0`
	)

Constructs an QOpenGLFramebufferObject and binds a texture to the buffer using the given size. The attachment describes the depth/stencil buffer configuration, target the texture target and internalFormat the texture format.

The default texture target is GL_TEXTURE_2D, while the default format is GL_RGBA8 for desktop OpenGL and GL_RGBA for OpenGL/ES.

See also: attachment(), size(), texture()

QOpenGLFramebufferObject::QOpenGLFramebufferObject	(	int	width,
		int	height,
		QOpenGLFramebufferObject::Attachment	attachment,
		GLenum	target = `GL_TEXTURE_2D`,
		GLenum	internalFormat = `0`
	)

Constructs an QOpenGLFramebufferObject and binds a texture to the buffer using the given width and height. The attachment describes the depth/stencil buffer configuration, target is the texture target, and internalFormat is the texture format.

The default texture target is GL_TEXTURE_2D while the default format is GL_RGBA8 for desktop OpenGL and GL_RGBA for OpenGL/ES.

See also: attachment(), size(), texture()

QOpenGLFramebufferObject::QOpenGLFramebufferObject	(	const QSize &	size,
		const QOpenGLFramebufferObjectFormat &	format
	)

Constructs an QOpenGLFramebufferObject using the given size based on the supplied format.

QOpenGLFramebufferObject::QOpenGLFramebufferObject	(	int	width,
		int	height,
		const QOpenGLFramebufferObjectFormat &	format
	)

Constructs an QOpenGLFramebufferObject using the given width and height based on the supplied format.

QOpenGLFramebufferObject::~QOpenGLFramebufferObject ( )

virtual

Destroys the QOpenGLFramebufferObject and frees any allocated resources.

Method Documentation

void QOpenGLFramebufferObject::addColorAttachment	(	const QSize &	size,
		GLenum	internalFormat = `0`
	)

Creates and attaches an additional texture or renderbuffer of the given size. The internalFormat specifies the format of the texture or renderbuffer. If the internalFormat is 0 the default of GL_RGBA or GL_RGBA8 will be used.

There is always an attachment at GL_COLOR_ATTACHMENT0. Call this method to set up additional attachments at GL_COLOR_ATTACHMENT1, GL_COLOR_ATTACHMENT2, etc.

This method only has an effect if multiple render targets are supported by the OpenGL implementation. Call QOpenGLFunctions::hasOpenGLFeature() with QOpenGLFunctions::MultipleRenderTargets at runtime to check if MRT is supported.

void QOpenGLFramebufferObject::addColorAttachment	(	int	width,
		int	height,
		GLenum	internalFormat = `0`
	)

Creates and attaches an additional texture or renderbuffer of size width and height. The internalFormat specifies the format of the texture or renderbuffer. If the internalFormat is 0 the default of GL_RGBA or GL_RGBA8 will be used.

QOpenGLFramebufferObject::Attachment QOpenGLFramebufferObject::attachment ( ) const

Returns the status of the depth and stencil buffers attached to this QOpenGLFramebufferObject.

See also: setAttachment()

bool QOpenGLFramebufferObject::bind ( )

Switches rendering from the default frame buffer to this QOpenGLFramebufferObject. Returns true if successful, otherwise false is returned.

If takeTexture() was called a new texture is created and associated with the QOpenGLFramebufferObject. This is potentially expensive and changes the current context state.

See also: release()

bool QOpenGLFramebufferObject::bindDefault ( )

static

Switches rendering from this QOpenGLFramebufferObject back to the default frame buffer. Returns true if successful, otherwise false is returned.

See also: bind(), release()

void QOpenGLFramebufferObject::blitFramebuffer	(	QOpenGLFramebufferObject *	target,
		const QRect &	targetRect,
		QOpenGLFramebufferObject *	source,
		const QRect &	sourceRect,
		GLbitfield	buffers,
		GLenum	filter,
		int	readColorAttachmentIndex,
		int	drawColorAttachmentIndex
	)

static

This method copies pixel data between two framebuffer objects and then restores the previous framebuffer binding.

void QOpenGLFramebufferObject::blitFramebuffer	(	QOpenGLFramebufferObject *	target,
		const QRect &	targetRect,
		QOpenGLFramebufferObject *	source,
		const QRect &	sourceRect,
		GLbitfield	buffers = `GL_COLOR_BUFFER_BIT`,
		GLenum	filter = `GL_NEAREST`
	)

static

This method copies pixel data between two framebuffer objects and then restores the previous framebuffer binding.

void QOpenGLFramebufferObject::blitFramebuffer	(	QOpenGLFramebufferObject *	target,
		QOpenGLFramebufferObject *	source,
		GLbitfield	buffers = `GL_COLOR_BUFFER_BIT`,
		GLenum	filter = `GL_NEAREST`
	)

static

This method copies pixel data between two framebuffer objects and then restores the previous framebuffer binding.

QOpenGLFramebufferObjectFormat QOpenGLFramebufferObject::format ( ) const

Returns the format of this QOpenGLFramebufferObject.

GLuint QOpenGLFramebufferObject::handle ( ) const

Returns the handle for this QOpenGLFramebufferObject returned by the glGenFrameBuffersEXT() function. The handle can be used to attach new images or buffers to the framebuffer. The user is responsible for cleaning up and destroying these objects.

bool QOpenGLFramebufferObject::hasOpenGLFramebufferBlit ( )

static

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

See also: blitFramebuffer()

bool QOpenGLFramebufferObject::hasOpenGLFramebufferObjects ( )

static

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

int QOpenGLFramebufferObject::height ( ) const

inline

Returns the height of the QOpenGLFramebufferObject attachments.

bool QOpenGLFramebufferObject::isBound ( ) const

Returns true if the QOpenGLFramebufferObject is currently bound to the current context, otherwise false is returned.

bool QOpenGLFramebufferObject::isValid ( ) const

Returns true if the QOpenGLFramebufferObject is valid.

The framebuffer can become invalid if the initialization process fails, the user attaches an invalid buffer to the framebuffer object, or a non-power of two width/height is specified as the texture size if the texture target is GL_TEXTURE_2D. The non-power of two limitation does not apply if the OpenGL version is 2.0 or higher, or if the GL_ARB_texture_non_power_of_two extension is present.

The framebuffer can also become invalid if the QOpenGLContext that the framebuffer was created within is destroyed and there are no other shared contexts that can take over ownership of the framebuffer.

bool QOpenGLFramebufferObject::release ( )

Switches rendering from this QOpenGLFramebufferObject back to the default frame buffer. Returns true if successful, otherwise false is returned.

See also: bind()

void QOpenGLFramebufferObject::setAttachment ( QOpenGLFramebufferObject::Attachment attachment )

Sets the attachments of the framebuffer object to attachment. This can be used to free or reattach the depth and stencil buffer attachments as needed. This method alters the current framebuffer binding.

See also: attachment()

QSize QOpenGLFramebufferObject::size ( ) const

Returns the size of the color and depth/stencil attachments attached to this QOpenGLFramebufferObject.

QVector< QSize > QOpenGLFramebufferObject::sizes ( ) const

Returns the sizes of all color attachments attached to this QOpenGLFramebufferObject.

GLuint QOpenGLFramebufferObject::takeTexture ( )

Returns the texture id for the texture attached to this QOpenGLFramebufferObject. The ownership of the texture is transferred to the caller.

If the framebuffer object is currently bound, an implicit release() will be done. During the next call to bind() a new texture will be created. If a multisample framebuffer object is used then there is no texture and the return value from this method will be invalid. Similarly, incomplete framebuffer objects will also return 0.

See also: bind(), release(), texture()

GLuint QOpenGLFramebufferObject::takeTexture ( int colorAttachmentIndex )

Returns the texture id for the texture attached to the color attachment of index colorAttachmentIndex of this QOpenGLFramebufferObject. The ownership of the texture is transferred to the caller. When colorAttachmentIndex is 0 the behavior is identical to the overload which has no parameters.

If this QOpenGLFramebufferObject is currently bound, an implicit release() will be done. During the next call to bind() a new texture will be created.

If a multisample QOpenGLFramebufferObject is used, then there is no texture and the return value from this method will be invalid. Similarly, incomplete framebuffer objects will also return 0.

GLuint QOpenGLFramebufferObject::texture ( ) const

Returns the texture id for the texture attached as the default rendering target in this QOpenGLFramebufferObject. This texture id can be bound as a normal texture in your own OpenGL code.

If a multisample framebuffer object is used then the value returned from this method will be invalid. When multiple textures are attached, the return value is the ID of the first one.

See also: takeTexture(), textures()

QVector< GLuint > QOpenGLFramebufferObject::textures ( ) const

Returns the texture id for all attached textures. If a multisample QOpenGLFramebufferObject is used, then an empty vector is returned.

See also: takeTexture(), texture()

QImage QOpenGLFramebufferObject::toImage ( ) const

Returns the contents of this QOpenGLFramebufferObject as a QImage. This method flips the image from OpenGL coordinates to raster coordinates.

QImage QOpenGLFramebufferObject::toImage ( bool flipped ) const

Returns the contents of this QOpenGLFramebufferObject as a QImage. If flipped is true the image is flipped from OpenGL coordinates to raster coordinates. If used together with QOpenGLPaintDevice, flipped should be the opposite of the value of QOpenGLPaintDevice::paintFlipped().

The returned image has a format of premultiplied ARGB32 or RGB32. The latter is used only when internalTextureFormat() is set to GL_RGB. This method will fall back to premultiplied RGBA8888 or RGBx8888 when reading to (A)RGB32 is not supported and this includes OpenGL ES. An A2BGR30 image is returned if the internal format is RGB10_A2.

If the rendering did not use premultiplied alpha, create a wrapper QImage with a non-premultiplied format. The following example show how to create such a wrapper without performing a copy of the pixel data.

QImage fboImage(fbo.toImage());

QImage image(fboImage.constBits(), fboImage.width(), fboImage.height(), QImage::Format_ARGB32);

For multisampled framebuffer objects the samples are resolved using the GL_EXT_framebuffer_blit extension. If the extension is not available the contents of the returned image is undefined.

For singlesampled framebuffers the contents is retrieved via glReadPixels. This is a potentially expensive and inefficient operation. Therefore it is recommended this method is used as seldom as possible.

See also: QOpenGLPaintDevice::paintFlipped()

QImage QOpenGLFramebufferObject::toImage	(	bool	flipped,
		int	colorAttachmentIndex
	)		const

Returns the contents of the color attachment of index colorAttachmentIndex of this QOpenGLFramebufferObject as a QImage. This method flips the image from OpenGL coordinates to raster coordinates when flipped is set to true.

This overload only has an effect when multiple render targets are supported by the OpenGL implementation. When that is not the case, only one color attachment will be set up.

int QOpenGLFramebufferObject::width ( ) const

inline

Returns the width of the QOpenGLFramebufferObject attachments.

Public Types

Public Methods

Static Public Methods

Friends

Detailed Description

Multisample

Multithreading

Member Enumeration Documentation

Constructor & Destructor Documentation

Method Documentation