Holds a set of G3D::Textures for use as draw targets. More...

Inherits G3D::ReferenceCountedObject.

Classes
class	Attachment

Public Types
enum	AttachmentPoint { COLOR0 = GL_COLOR_ATTACHMENT0, COLOR1 = GL_COLOR_ATTACHMENT1, COLOR2 = GL_COLOR_ATTACHMENT2, COLOR3 = GL_COLOR_ATTACHMENT3, COLOR4 = GL_COLOR_ATTACHMENT4, COLOR5 = GL_COLOR_ATTACHMENT5, COLOR6 = GL_COLOR_ATTACHMENT6, COLOR7 = GL_COLOR_ATTACHMENT7, COLOR8 = GL_COLOR_ATTACHMENT8, COLOR9 = GL_COLOR_ATTACHMENT9, COLOR10 = GL_COLOR_ATTACHMENT10, COLOR11 = GL_COLOR_ATTACHMENT11, COLOR12 = GL_COLOR_ATTACHMENT12, COLOR13 = GL_COLOR_ATTACHMENT13, COLOR14 = GL_COLOR_ATTACHMENT14, COLOR15 = GL_COLOR_ATTACHMENT15, DEPTH = GL_DEPTH_ATTACHMENT, STENCIL = GL_STENCIL_ATTACHMENT, DEPTH_AND_STENCIL = GL_DEPTH_STENCIL_ATTACHMENT, NO_ATTACHMENT }
	Specifies which channels of the framebuffer the texture will define. More...

enum	Mode { MODE_READ = GL_READ_FRAMEBUFFER, MODE_DRAW = GL_DRAW_FRAMEBUFFER, MODE_READ_DRAW = GL_FRAMEBUFFER }

Public Member Functions
	~Framebuffer ()
	Reclaims OpenGL ID. More...

bool	bind (bool alreadyBound=false, Mode m=MODE_READ_DRAW)
	Bind this framebuffer and force all of its attachments to actually be attached at the OpenGL level. More...

void	blitTo (RenderDevice *rd, const shared_ptr< Framebuffer > &dst=nullptr, bool invertY=false, bool linearInterpolation=false, bool blitDepth=true, bool blitStencil=true, bool blitColor=true) const
	Blits the contents of this framebuffer to. More...

void	clear ()
	Detach all attachments. More...

shared_ptr< Attachment >	get (AttachmentPoint ap) const
	Returns the attachment currently at ap, or nullptr if there is not one. More...

const Color4	getClearValue (const AttachmentPoint x) const

bool	has (AttachmentPoint ap) const
	Returns true if this attachment is currently non-nullptr. More...

int	height () const
	Read from the first attachment every time called. More...

bool	invertY () const
	If true, Film (and other resolve calls) should invert the Y axis when resolving to this Framebuffer, as if it was a hardware framebuffer with (0, 0) in the lower-left instead of G3D's default of upper-left. More...

bool	isHardwareFramebuffer () const

const String &	name () const

int	numAttachments () const
	Number of currently bound attachments. More...

const Array< GLenum > &	openGLDrawArray () const
	The draw array for use with glDrawBuffers. More...

unsigned int	openGLID () const
	The OpenGL ID of the underlying framebuffer object. More...

Rect2D	rect2DBounds () const

void	resize (AttachmentPoint ap, int w, int h)
	Resize this one attachment. More...

void	resize (int w, int h)
	Resize all attachments. More...

void	resize (const shared_ptr< Framebuffer > &fb)

void	resize (const Rect2D &rect)

void	resize (Vector2int32 size)

void	set (AttachmentPoint ap, const void *n)
	Overload used when setting attachment points to nullptr. More...

void	set (AttachmentPoint ap, const shared_ptr< Texture > &texture)
	Sets the texture to be the output render target with location = ap. More...

void	set (AttachmentPoint ap, const shared_ptr< Attachment > &attachment)
	Used for copying Attachments from another Framebuffer. More...

void	set (AttachmentPoint ap, const shared_ptr< Texture > &texture, CubeFace face, int mipLevel=0, int layer=-1)
	Set one of the attachment points to reference a Texture. More...

void	setClearValue (AttachmentPoint x, const Color4 &clearValue)
	For STENCIL, the integer in the r channel is used. More...

void	setInvertY (bool i)

int	stencilBits () const
	Returns the number of stencil bits for currently attached STENCIL and DEPTH_AND_STENCIL attachments. More...

const shared_ptr< Texture > &	texture (AttachmentPoint x)
	Shorthand for getting the texture for attachment point x. More...

const shared_ptr< Texture > &	texture (const uint8 x)
	Shorthand for getting the texture for color attachment point x. More...

Vector2	vector2Bounds () const

int	width () const
	Read from the first attachment every time called. More...

Static Public Member Functions
static void	bindWindowBuffer (Mode m=MODE_READ_DRAW)
	Bind the current context's default Framebuffer, instead of an application-created one. More...

static shared_ptr< Framebuffer >	create (const String &name)
	Creates a Framebuffer object. More...

static shared_ptr< Framebuffer >	create (const shared_ptr< Texture > &tex0, const shared_ptr< Texture > &tex1=nullptr, const shared_ptr< Texture > &tex2=nullptr, const shared_ptr< Texture > &tex3=nullptr)
	Creates a Framebuffer object and binds the argument to Framebuffer::DEPTH_AND_STENCIL if it has depth bits or Framebuffer::COLOR0 otherwise. More...

static shared_ptr< Framebuffer >	createWithoutAttachments (const String &_name, Vector2 res, int numLayers, int numSamples=1, bool fixedSamplesLocation=true)
	Creates a Framebuffer object with no attachments. More...

Public Attributes
UniformTable	uniformTable
	Arguments that RenderDevice will appended to the Shader G3D::Args before invoking any draw call that targets this frame buffer. More...

Protected Member Functions
	Framebuffer (const String &name, GLuint framebufferID)

void	attach (const shared_ptr< Attachment > &a)
	Called from sync() to actually force a to be attached at the OpenGL level. More...

void	detach (shared_ptr< Attachment > a)
	Called from sync() to actually force a to be detached at the OpenGL level. More...

int	find (AttachmentPoint ap, bool &found) const
	Returns the index in m_desired where ap is, or where it should be inserted if it is not present. More...

int	findCurrent (AttachmentPoint ap) const

void	set (const shared_ptr< Attachment > &a)
	Adds a to m_desired. More...

void	sync ()
	Executes the synchronization portion of bind() More...

Static Protected Member Functions
template<class T , class ... ArgTypes>
static shared_ptr< T >	createShared (ArgTypes &&... args)
	Like std::make_shared, but works for protected constructors. More...

Protected Attributes
Array< GLenum >	m_colorDrawBufferArray
	The GL buffer names of the m_currentAttachment. More...

Array< shared_ptr< Attachment > >	m_current
	What is actually attached on this framebuffer as far as OpenGL is concerned. More...

bool	m_currentOutOfSync
	True when desiredAttachment != m_currentAttachment. More...

Array< shared_ptr< Attachment > >	m_desired
	What should be attached on this framebuffer, according to set() calls that have been made. More...

GLuint	m_framebufferID
	OpenGL Object ID. More...

bool	m_invertY

String	m_name
	Framebuffer name. More...

bool	m_noAttachment
	This a a special framebuffer with no attachment. More...

class OSWindow *	m_window
	If this is the hardware framebuffer for a window. More...

Friends
class	OSWindow

Detailed Description

Holds a set of G3D::Textures for use as draw targets.

Abstraction of OpenGL's Framebuffer Object. This is an efficient way of rendering to Textures.

RenderDevice::setFramebuffer automatically configures the appropriate OpenGL draw buffers. These are maintained even if the frame buffer is changed while set on the RenderDevice. Inside a pixel shader gl_FragData[i] is the ith attached buffer, in number order. For example, if there are attachments to buffer0 and buffer2, then gl_FragData[0] maps to buffer0 and gl_FragData[1] maps to buffer2.

Basic Framebuffer Theory: Every OpenGL program has at least one Framebuffer. This framebuffer is setup by the windowing system and its image format is that specified by the OS. With the Framebuffer Object extension, OpenGL gives the developer the ability to create offscreen framebuffers that can be used to render to textures of any specified format.

The Framebuffer class is used in conjunction with the RenderDevice to set a render target. The RenderDevice method setFramebuffer performs this action. If a nullptr argument is passed to setFramebuffer, the render target defaults to the window display framebuffer.

Note: Not any combination of images may be attached to a Framebuffer. OpenGL lays out some restrictions that must be considered:

In order to render to a Framebuffer, there must be at least one image (Texture) attached to an attachment point.
All images attached to a COLOR_ATTACHMENT[n] point must have the same internal format (RGBA8, RGBA16...etc)
If RenderDevice->setDrawBuffer is used then the specified attachment point must have a bound image.
The combination of internal formats of attached images does not violate some implementation-dependent set of restrictions (i.e., Your graphics card must completely implement all combinations that you plan to use!)

Member Enumeration Documentation

◆ AttachmentPoint

enum G3D::Framebuffer::AttachmentPoint

Specifies which channels of the framebuffer the texture will define.

These mirror the OpenGL definition as do their values.

A DEPTH_STENCIL format texture can be attached to either the DEPTH_ATTACHMENT or the STENCIL_ATTACHMENT, or both simultaneously; Framebuffer will understand the format and use the appropriate channels.

Enumerator
COLOR0
COLOR1
COLOR2
COLOR3
COLOR4
COLOR5
COLOR6
COLOR7
COLOR8
COLOR9
COLOR10
COLOR11
COLOR12
COLOR13
COLOR14
COLOR15
DEPTH
STENCIL
DEPTH_AND_STENCIL
NO_ATTACHMENT

◆ Mode

enum G3D::Framebuffer::Mode

See also: bind()

Enumerator
MODE_READ
MODE_DRAW
MODE_READ_DRAW

Constructor & Destructor Documentation

◆ Framebuffer()

G3D::Framebuffer::Framebuffer	(	const String &	name,
		GLuint	framebufferID
	)

protected

◆ ~Framebuffer()

G3D::Framebuffer::~Framebuffer ( )

Reclaims OpenGL ID.

All buffers/textures are automatically detatched on destruction.

Member Function Documentation

◆ attach()

void G3D::Framebuffer::attach ( const shared_ptr< Attachment > & a )

protected

Called from sync() to actually force a to be attached at the OpenGL level.

Assumes the framebuffer is already bound.

◆ bind()

bool G3D::Framebuffer::bind	(	bool	alreadyBound = `false`,
		Mode	m = `MODE_READ_DRAW`
	)

Bind this framebuffer and force all of its attachments to actually be attached at the OpenGL level.

The latter step is needed because set() is lazy.

Primarily used by RenderDevice. Developers should not need to explicitly call this method or glDrawBuffers.

After binding, you also have to set the glDrawBuffers to match the capabilities of the Framebuffer that is currently bound.

Parameters

alreadyBound If true, do not bother binding the FBO itself, just sync any out of date attachments.

Returns: True if openGLDrawArray() was changed by this call

◆ bindWindowBuffer()

static void G3D::Framebuffer::bindWindowBuffer ( Mode m = MODE_READ_DRAW )

static

Bind the current context's default Framebuffer, instead of an application-created one.

Primarily used by RenderDevice. Developers should not need to explicitly call this method or glDrawBuffers.

◆ blitTo()

void G3D::Framebuffer::blitTo	(	RenderDevice *	rd,
		const shared_ptr< Framebuffer > &	dst = `nullptr`,
		bool	invertY = `false`,
		bool	linearInterpolation = `false`,
		bool	blitDepth = `true`,
		bool	blitStencil = `true`,
		bool	blitColor = `true`
	)		const

Blits the contents of this framebuffer to.

Parameters

dst,or the back buffer if dst is null. If invertY is true, flip the image vertically while blitting, useful for blitting to the back buffer.

◆ clear()

void G3D::Framebuffer::clear ( )

Detach all attachments.

This is lazy; see set() for discussion.

◆ create() [1/2]

static shared_ptr<Framebuffer> G3D::Framebuffer::create ( const String & name )

static

Creates a Framebuffer object.

Parameters

name	Name of framebuffer, for debugging purposes.

◆ create() [2/2]

static shared_ptr<Framebuffer> G3D::Framebuffer::create	(	const shared_ptr< Texture > &	tex0,
		const shared_ptr< Texture > &	tex1 = `nullptr`,
		const shared_ptr< Texture > &	tex2 = `nullptr`,
		const shared_ptr< Texture > &	tex3 = `nullptr`
	)

static

Creates a Framebuffer object and binds the argument to Framebuffer::DEPTH_AND_STENCIL if it has depth bits or Framebuffer::COLOR0 otherwise.

◆ createShared()

template<class T , class ... ArgTypes>

static shared_ptr<T> G3D::ReferenceCountedObject::createShared ( ArgTypes &&... args )

inlinestaticprotectedinherited

Like std::make_shared, but works for protected constructors.

Call as createShared<myclass>.

◆ createWithoutAttachments()

static shared_ptr<Framebuffer> G3D::Framebuffer::createWithoutAttachments	(	const String &	_name,
		Vector2	res,
		int	numLayers,
		int	numSamples = `1`,
		bool	fixedSamplesLocation = `true`
	)

static

Creates a Framebuffer object with no attachments.

Requires ARB_framebuffer_no_attachments.

◆ detach()

void G3D::Framebuffer::detach ( shared_ptr< Attachment > a )

protected

Called from sync() to actually force a to be detached at the OpenGL level.

Assumes the framebuffer is already bound.

Argument can't be a & reference because it is being removed from the only place holding it.

◆ find()

int G3D::Framebuffer::find	(	AttachmentPoint	ap,
		bool &	found
	)		const

protected

Returns the index in m_desired where ap is, or where it should be inserted if it is not present.

◆ findCurrent()

int G3D::Framebuffer::findCurrent ( AttachmentPoint ap ) const

protected

◆ get()

shared_ptr<Attachment> G3D::Framebuffer::get ( AttachmentPoint ap ) const

Returns the attachment currently at ap, or nullptr if there is not one.

See also: has()

◆ getClearValue()

const Color4 G3D::Framebuffer::getClearValue ( const AttachmentPoint x ) const

inline

◆ has()

bool G3D::Framebuffer::has ( AttachmentPoint ap ) const

Returns true if this attachment is currently non-nullptr.

Referenced by getClearValue(), and setClearValue().

◆ height()

int G3D::Framebuffer::height ( ) const

Read from the first attachment every time called.

◆ invertY()

bool G3D::Framebuffer::invertY ( ) const

inline

If true, Film (and other resolve calls) should invert the Y axis when resolving to this Framebuffer, as if it was a hardware framebuffer with (0, 0) in the lower-left instead of G3D's default of upper-left.

Defaults to false

◆ isHardwareFramebuffer()

bool G3D::Framebuffer::isHardwareFramebuffer ( ) const

inline

◆ name()

const String& G3D::Framebuffer::name ( ) const

inline

◆ numAttachments()

int G3D::Framebuffer::numAttachments ( ) const

inline

Number of currently bound attachments.

When this hits zero we can add attachments with new sizes.

◆ openGLDrawArray()

const Array<GLenum>& G3D::Framebuffer::openGLDrawArray ( ) const

inline

The draw array for use with glDrawBuffers.

This is not up to date until bind() is invoked.

Note that DEPTH, STENCIL, and DEPTH_AND_STENCIL are never included in this list.

RenderDevice automatically uses this.

◆ openGLID()

unsigned int G3D::Framebuffer::openGLID ( ) const

inline

The OpenGL ID of the underlying framebuffer object.

◆ rect2DBounds()

Rect2D G3D::Framebuffer::rect2DBounds ( ) const

◆ resize() [1/5]

void G3D::Framebuffer::resize	(	AttachmentPoint	ap,
		int	w,
		int	h
	)

Resize this one attachment.

Referenced by resize().

◆ resize() [2/5]

void G3D::Framebuffer::resize	(	int	w,
		int	h
	)

Resize all attachments.

◆ resize() [3/5]

void G3D::Framebuffer::resize ( const shared_ptr< Framebuffer > & fb )

inline

◆ resize() [4/5]

void G3D::Framebuffer::resize ( const Rect2D & rect )

inline

◆ resize() [5/5]

void G3D::Framebuffer::resize ( Vector2int32 size )

inline

◆ set() [1/5]

void G3D::Framebuffer::set ( const shared_ptr< Attachment > & a )

protected

Adds a to m_desired.

◆ set() [2/5]

void G3D::Framebuffer::set	(	AttachmentPoint	ap,
		const void *	n
	)

Overload used when setting attachment points to nullptr.

◆ set() [3/5]

void G3D::Framebuffer::set	(	AttachmentPoint	ap,
		const shared_ptr< Texture > &	texture
	)

Sets the texture to be the output render target with location = ap.

◆ set() [4/5]

void G3D::Framebuffer::set	(	AttachmentPoint	ap,
		const shared_ptr< Attachment > &	attachment
	)

Used for copying Attachments from another Framebuffer.

Ignores the attachment.point.

◆ set() [5/5]

void G3D::Framebuffer::set	(	AttachmentPoint	ap,
		const shared_ptr< Texture > &	texture,
		CubeFace	face,
		int	mipLevel = `0`,
		int	layer = `-1`
	)

Set one of the attachment points to reference a Texture.

Set to nullptr or call clear() to unset. Auto-mipmap will automatically be disabled on set.

Results are undefined if a texture that is bound to the current Framebuffer as a source texture while it is being read from. In general, create one Framebuffer per set of textures you wish to render to and just leave them bound at all times.

All set() calls are lazy because OpenGL provides no mechanism for efficiently pushing and popping the Framebuffer. Thus all calls to actually set attachments must be delayed until the bind() call, when this Framebuffer is guaranteed to be bound.

Parameters

texture	Texture to bind to the Framebuffer.
ap	Attachment point to bind texture to.
mipLevel	Target MIP-map level to render to.
layer	Target layer render to. If -1, all layers are bound.

◆ setClearValue()

void G3D::Framebuffer::setClearValue	(	AttachmentPoint	x,
		const Color4 &	clearValue
	)

inline

For STENCIL, the integer in the r channel is used.

For DEPTH, the float in the r channel is used. For DEPTH_AND_STENCIL, the float in r clears depth and the int in g clears stencil.

◆ setInvertY()

void G3D::Framebuffer::setInvertY ( bool i )

inline

◆ stencilBits()

int G3D::Framebuffer::stencilBits ( ) const

Returns the number of stencil bits for currently attached STENCIL and DEPTH_AND_STENCIL attachments.

◆ sync()

void G3D::Framebuffer::sync ( )

protected

Executes the synchronization portion of bind()

◆ texture() [1/2]

const shared_ptr<Texture>& G3D::Framebuffer::texture ( AttachmentPoint x )

inline

Shorthand for getting the texture for attachment point x.

Referenced by texture().

◆ texture() [2/2]

const shared_ptr<Texture>& G3D::Framebuffer::texture ( const uint8 x )

inline

Shorthand for getting the texture for color attachment point x.

◆ vector2Bounds()

Vector2 G3D::Framebuffer::vector2Bounds ( ) const

◆ width()

int G3D::Framebuffer::width ( ) const

Read from the first attachment every time called.

Friends And Related Function Documentation

◆ OSWindow

friend class OSWindow

friend

Member Data Documentation

◆ m_colorDrawBufferArray

Array<GLenum> G3D::Framebuffer::m_colorDrawBufferArray

protected

The GL buffer names of the m_currentAttachment.

Referenced by openGLDrawArray().

◆ m_current

Array< shared_ptr<Attachment> > G3D::Framebuffer::m_current

protected

What is actually attached on this framebuffer as far as OpenGL is concerned.

◆ m_currentOutOfSync

bool G3D::Framebuffer::m_currentOutOfSync

protected

True when desiredAttachment != m_currentAttachment.

Set to true by set(). Set to false by sync(), which is called by RenderDevice::sync().

◆ m_desired

Array< shared_ptr<Attachment> > G3D::Framebuffer::m_desired

protected

What should be attached on this framebuffer, according to set() calls that have been made.

Referenced by numAttachments().

◆ m_framebufferID

GLuint G3D::Framebuffer::m_framebufferID

protected

OpenGL Object ID.

Referenced by isHardwareFramebuffer(), and openGLID().

◆ m_invertY

bool G3D::Framebuffer::m_invertY

protected

Referenced by invertY(), and setInvertY().

◆ m_name

String G3D::Framebuffer::m_name

protected

Framebuffer name.

Referenced by name().

◆ m_noAttachment

bool G3D::Framebuffer::m_noAttachment

protected

This a a special framebuffer with no attachment.

◆ m_window

class OSWindow* G3D::Framebuffer::m_window

protected

If this is the hardware framebuffer for a window.

◆ uniformTable

UniformTable G3D::Framebuffer::uniformTable

Arguments that RenderDevice will appended to the Shader G3D::Args before invoking any draw call that targets this frame buffer.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ AttachmentPoint

◆ Mode

Constructor & Destructor Documentation

◆ Framebuffer()

◆ ~Framebuffer()

Member Function Documentation

◆ attach()

◆ bind()

◆ bindWindowBuffer()

◆ blitTo()

◆ clear()

◆ create() [1/2]

◆ create() [2/2]

◆ createShared()

◆ createWithoutAttachments()

◆ detach()

◆ find()

◆ findCurrent()

◆ get()

◆ getClearValue()

◆ has()

◆ height()

◆ invertY()

◆ isHardwareFramebuffer()

◆ name()

◆ numAttachments()

◆ openGLDrawArray()

◆ openGLID()

◆ rect2DBounds()

◆ resize() [1/5]

◆ resize() [2/5]

◆ resize() [3/5]

◆ resize() [4/5]

◆ resize() [5/5]

◆ set() [1/5]

◆ set() [2/5]

◆ set() [3/5]

◆ set() [4/5]

◆ set() [5/5]

◆ setClearValue()

◆ setInvertY()

◆ stencilBits()

◆ sync()

◆ texture() [1/2]

◆ texture() [2/2]

◆ vector2Bounds()

◆ width()

Friends And Related Function Documentation

◆ OSWindow

Member Data Documentation

◆ m_colorDrawBufferArray

◆ m_current

◆ m_currentOutOfSync

◆ m_desired

◆ m_framebufferID

◆ m_invertY

◆ m_name

◆ m_noAttachment

◆ m_window

◆ uniformTable