#include <CUFrameBuffer.h>

Public Member Functions
	FrameBuffer ()

	~FrameBuffer ()

void	dispose ()

bool	init (Uint32 width, Uint32 height)

bool	init (Uint32 width, Uint32 height, size_t outputs)

bool	initWithFormats (Uint32 width, Uint32 height, std::initializer_list< TexelFormat > outputs)

bool	initWithFormats (Uint32 width, Uint32 height, std::vector< TexelFormat > outputs)

bool	initWithFormats (Uint32 width, Uint32 height, TexelFormat *outputs, size_t outsize)

bool	initWithRenderPass (Uint32 width, Uint32 height, const std::shared_ptr< RenderPass > &pass)

FrameBufferData *	getImplementation ()

void	setName (std::string name)

const std::string	getName () const

const Size	getSize () const

int	getWidth () const

int	getHeight () const

const std::shared_ptr< RenderPass > &	getRenderPass () const

bool	isImmediate () const

void	setImmediate (bool value)

size_t	getAttachments () const

const std::shared_ptr< Image >	getImage (size_t index=0) const

const std::shared_ptr< Texture >	getTexture (size_t index=0)

const std::shared_ptr< Image >	getDepthStencil () const

const Rect	getViewPort () const

void	setViewPort (const Rect &viewport)

void	setViewPort (int x, int y, int width, int height)

void	restoreViewPort ()

void	activate ()

void	clear ()

Static Public Member Functions
static std::shared_ptr< FrameBuffer >	alloc (Uint32 width, Uint32 height)

static std::shared_ptr< FrameBuffer >	alloc (Uint32 width, Uint32 height, size_t outputs)

static std::shared_ptr< FrameBuffer >	allocWithFormats (Uint32 width, Uint32 height, std::initializer_list< TexelFormat > outputs)

static std::shared_ptr< FrameBuffer >	allocWithFormats (int width, int height, std::vector< TexelFormat > outputs)

static std::shared_ptr< FrameBuffer >	allocWithFormats (int width, int height, TexelFormat *outputs, size_t outsize)

static std::shared_ptr< FrameBuffer >	allocWithRenderPass (Uint32 width, Uint32 height, const std::shared_ptr< RenderPass > &pass)

static std::shared_ptr< FrameBuffer >	getDisplay ()

Detailed Description

This is a class representing an offscreen framebuffer

A framebuffer allows the user to draw to an image before drawing to a screen. This allows for potential post-processing effects. To draw to a framebuffer, simply provide it to GraphicsShader#begin when starting a new render pass.

While framebuffers must have at least one output image, they can support multiple images as long as the active fragment shader has multiple output variables. The locations of these outputs should be set explicitly and sequentially with the layout keyword.

This class greatly simplifies offscreen framebuffers at the cost of some flexibility. The only support for depth and stencil is a combined 24/8 depth and stencil buffer. In addition, output textures must have one of the simplified formats defined by TexelFormat.

Constructor & Destructor Documentation

◆ FrameBuffer()

cugl::graphics::FrameBuffer::FrameBuffer ( )

Creates an uninitialized framebuffer with no output textures.

You must initialize the framebuffer to create an output texture.

◆ ~FrameBuffer()

cugl::graphics::FrameBuffer::~FrameBuffer ( )

inline

Deletes this framebuffer, disposing all resources.

Member Function Documentation

◆ activate()

void cugl::graphics::FrameBuffer::activate ( )

Activates the framebuffer for drawing

◆ alloc() [1/2]

static std::shared_ptr< FrameBuffer > cugl::graphics::FrameBuffer::alloc	(	Uint32	width,
		Uint32	height
	)

inlinestatic

Returns a new framebuffer with a single COLOR_RGBA output image.

The output image will have the given width and size.

Parameters

width	The drawing width of this framebuffer
height	The drawing width of this framebuffer

Returns: a new render target with a single COLOR_RGBA output image.

◆ alloc() [2/2]

static std::shared_ptr< FrameBuffer > cugl::graphics::FrameBuffer::alloc	(	Uint32	width,
		Uint32	height,
		size_t	outputs
	)

inlinestatic

Returns a new framebuffer with multiple COLOR_RGBA output images.

The output images will have the given width and size. They will be assigned locations 0..outputs-1. These locations should be bound with the layout keyword in any shader used with this framebuffer. Otherwise the results are not well-defined.

If outputs is larger than the number of possible shader outputs for this platform, this method will fail.

Parameters

width	The drawing width of this framebuffer
height	The drawing width of this framebuffer
outputs	The number of output images

Returns: a new render target with multiple COLOR_RGBA output images.

◆ allocWithFormats() [1/3]

static std::shared_ptr< FrameBuffer > cugl::graphics::FrameBuffer::allocWithFormats	(	int	width,
		int	height,
		std::vector< TexelFormat >	outputs
	)

inlinestatic

Returns a new framebuffer with multiple images of the given format.

The output images will have the given width and size. They will be assigned the appropriate format at locations 0..#outputs-1. These locations should be bound with the layout keyword in any shader used with this framebuffer. Otherwise the results are not well-defined.

If the size of the outputs parameter is larger than the number of possible shader outputs for this platform, this method will fail.

Parameters

width	The drawing width of this framebuffer
height	The drawing width of this framebuffer
outputs	The list of desired image formats

Returns: a new framebuffer with multiple images of the given format.

◆ allocWithFormats() [2/3]

static std::shared_ptr< FrameBuffer > cugl::graphics::FrameBuffer::allocWithFormats	(	int	width,
		int	height,
		TexelFormat *	outputs,
		size_t	outsize
	)

inlinestatic

Returns a new framebuffer with multiple images of the given format.

The output images will have the given width and size. They will be assigned the appropriate format at locations 0..#outputs-1. These locations should be bound with the layout keyword in any shader used with this framebuffer. Otherwise the results are not well-defined.

If the size of the outputs parameter is larger than the number of possible shader outputs for this platform, this method will fail.

Parameters

width	The drawing width of this framebuffer
height	The drawing width of this framebuffer
outputs	The list of desired image formats
outsize	The number of elements in outputs

Returns: a new framebuffer with multiple images of the given format.

◆ allocWithFormats() [3/3]

static std::shared_ptr< FrameBuffer > cugl::graphics::FrameBuffer::allocWithFormats	(	Uint32	width,
		Uint32	height,
		std::initializer_list< TexelFormat >	outputs
	)

inlinestatic

Returns a new framebuffer with multiple images of the given format.

The output images will have the given width and size. They will be assigned the appropriate format at locations 0..#outputs-1. These locations should be bound with the layout keyword in any shader used with this framebuffer. Otherwise the results are not well-defined.

If the size of the outputs parameter is larger than the number of possible shader outputs for this platform, this method will fail.

Parameters

width	The drawing width of this framebuffer
height	The drawing width of this framebuffer
outputs	The list of desired image formats

Returns: a new framebuffer with multiple images of the given format.

◆ allocWithRenderPass()

static std::shared_ptr< FrameBuffer > cugl::graphics::FrameBuffer::allocWithRenderPass	(	Uint32	width,
		Uint32	height,
		const std::shared_ptr< RenderPass > &	pass
	)

inlinestatic

Returns a newly allocated framebuffer with the given render pass

The framebuffer will use the formats of the render pass to construct its images.

Parameters

width	The drawing width of this framebuffer
height	The drawing width of this framebuffer
pass	The associated render pass

Returns: a newly allocated framebuffer with the given render pass

◆ clear()

void cugl::graphics::FrameBuffer::clear ( )

Clears the contents of this framebuffer.

The framebuffer will use the RenderPass settings to clear this framebuffer.

◆ dispose()

void cugl::graphics::FrameBuffer::dispose ( )

Deletes the framebuffer and resets all attributes.

You must reinitialize the framebuffer to use it.

◆ getAttachments()

size_t cugl::graphics::FrameBuffer::getAttachments ( ) const

inline

Returns the number of color attachments for this framebuffer

If the render target has been successfully initialized, this value is guaranteed to be at least 1.

Returns: the number of color attachments for this framebuffer

◆ getDepthStencil()

const std::shared_ptr< Image > cugl::graphics::FrameBuffer::getDepthStencil ( ) const

Returns the depth/stencil buffer for this framebuffer

The framebuffer for a render target always uses a combined depth and stencil buffer image. It uses 24 bits for the depth and 8 bits for the stencil. This should be sufficient in most applications.

Returns: the depth/stencil buffer for this framebuffer

◆ getDisplay()

static std::shared_ptr< FrameBuffer > cugl::graphics::FrameBuffer::getDisplay ( )

static

Returns the framebuffer for the window display.

This is the default framebuffer for on-screen drawing.

◆ getHeight()

int cugl::graphics::FrameBuffer::getHeight ( ) const

inline

Returns the height of this framebuffer

Returns: the height of this framebuffer

◆ getImage()

const std::shared_ptr< Image > cugl::graphics::FrameBuffer::getImage ( size_t index = 0 ) const

Returns the output image for the given index.

The index should be a value between 0..getAttachments-1. By default it is 0, the primary output image.

Parameters

index The output index

Returns: the output image for the given index.

◆ getImplementation()

FrameBufferData * cugl::graphics::FrameBuffer::getImplementation ( )

inline

Returns the platform-specific implementation for this framebuffer

The value returned is an opaque type encapsulating the information for either OpenGL or Vulkan.

Returns: the platform-specific implementation for this framebuffer

◆ getName()

const std::string cugl::graphics::FrameBuffer::getName ( ) const

inline

Returns the name of this frame buffer.

A name is a user-defined way of identifying a buffer. It is used for debugging purposes only, and has no affect on the graphics pipeline.

Returns: the name of this frame buffer.

◆ getRenderPass()

const std::shared_ptr< RenderPass > & cugl::graphics::FrameBuffer::getRenderPass ( ) const

inline

Returns the render pass for this framebuffer

Returns: the render pass for this framebuffer

◆ getSize()

const Size cugl::graphics::FrameBuffer::getSize ( ) const

inline

Returns the size of this framebuffer

Returns: the size of this framebuffer

◆ getTexture()

const std::shared_ptr< Texture > cugl::graphics::FrameBuffer::getTexture ( size_t index = 0 )

Returns the output texture for the given index.

This method is similar to getImage except that it attaches a default sampler to the frame buffer.

Parameters

index The output index

Returns: the output texture for the given index.

◆ getViewPort()

const Rect cugl::graphics::FrameBuffer::getViewPort ( ) const

inline

Returns the active viewport for this framebuffer

By default, the viewport is the entire scope of the framebuffer. Changing this value restricts the portion of the framebuffer that a GraphicsShader will draw to. The viewport origin is from the bottom left for all graphics APIs.

Returns: the active viewport for this framebuffer

◆ getWidth()

int cugl::graphics::FrameBuffer::getWidth ( ) const

inline

Returns the width of this framebuffer

Returns: the width of this framebuffer

◆ init() [1/2]

bool cugl::graphics::FrameBuffer::init	(	Uint32	width,
		Uint32	height
	)

inline

Initializes this framebuffer with a single COLOR_RGBA output image.

The output image will have the given width and size.

Parameters

width	The drawing width of this framebuffer
height	The drawing width of this framebuffer

Returns: true if initialization was successful.

◆ init() [2/2]

bool cugl::graphics::FrameBuffer::init	(	Uint32	width,
		Uint32	height,
		size_t	outputs
	)

Initializes this framebuffer with multiple COLOR_RGBA output image.

The output images will have the given width and size. They will be assigned locations 0..outputs-1. These locations should be bound with the layout keyword in any shader used with this framebuffer. Otherwise the results are not well-defined.

If outputs is larger than the number of possible shader outputs for this platform, this method will fail.

Parameters

width	The drawing width of this framebuffer
height	The drawing width of this framebuffer
outputs	The number of output images

Returns: true if initialization was successful.

◆ initWithFormats() [1/3]

bool cugl::graphics::FrameBuffer::initWithFormats	(	Uint32	width,
		Uint32	height,
		std::initializer_list< TexelFormat >	outputs
	)

Initializes this framebuffer with multiple images of the given format.

The output images will have the given width and size. They will be assigned the appropriate format at locations 0..#outputs-1. These locations should be bound with the layout keyword in any shader used with this framebuffer. Otherwise the results are not well-defined.

If the size of the outputs parameter is larger than the number of possible shader outputs for this platform, this method will fail.

Parameters

width	The drawing width of this framebuffer
height	The drawing width of this framebuffer
outputs	The list of desired image formats

Returns: true if initialization was successful.

◆ initWithFormats() [2/3]

bool cugl::graphics::FrameBuffer::initWithFormats	(	Uint32	width,
		Uint32	height,
		std::vector< TexelFormat >	outputs
	)

inline

Initializes this framebuffer with multiple images of the given format.

The output images will have the given width and size. They will be assigned the appropriate format at locations 0..#outputs-1. These locations should be bound with the layout keyword in any shader used with this framebuffer. Otherwise the results are not well-defined.

If the size of the outputs parameter is larger than the number of possible shader outputs for this platform, this method will fail.

Parameters

width	The drawing width of this framebuffer
height	The drawing width of this framebuffer
outputs	The list of desired image formats

Returns: true if initialization was successful.

◆ initWithFormats() [3/3]

bool cugl::graphics::FrameBuffer::initWithFormats	(	Uint32	width,
		Uint32	height,
		TexelFormat *	outputs,
		size_t	outsize
	)

Initializes this framebuffer with multiple images of the given format.

The output images will have the given width and size. They will be assigned the appropriate format at locations 0..#outsize-1. These locations should be bound with the layout keyword in any shader used with this framebuffer. Otherwise the results are not well-defined.

If the size of the outputs parameter is larger than the number of possible shader outputs for this platform, this method will fail.

Parameters

width	The drawing width of this framebuffer
height	The drawing width of this framebuffer
outputs	The list of desired image formats
outsize	The number of elements in outputs

Returns: true if initialization was successful.

◆ initWithRenderPass()

bool cugl::graphics::FrameBuffer::initWithRenderPass	(	Uint32	width,
		Uint32	height,
		const std::shared_ptr< RenderPass > &	pass
	)

Initializes this framebuffer with the given render pass

The framebuffer will use the formats of the render pass to construct its images.

Parameters

width	The drawing width of this framebuffer
height	The drawing width of this framebuffer
pass	The associated render pass

Returns: true if initialization was successful.

◆ isImmediate()

bool cugl::graphics::FrameBuffer::isImmediate ( ) const

Returns true if rendering to this framebuffer happens immediately

An immediate framebuffer guarantees that its image(s) are available as soon as GraphicsShader#end is called. Otherwise, there may be a delay between when GraphicsShader#end is called and getImage is available. There is no indication for when such an image is available, short of progressing to the next frame.

This is an optimization for subpass rendering on Vulkan. It has no effect in OpenGL. This value cannot be changed during the middle of an active render pass on this framebuffer.

Returns: true if rendering to this framebuffer happens immediately

◆ restoreViewPort()

void cugl::graphics::FrameBuffer::restoreViewPort ( )

Restores the viewport for this framebuffer

The viewport is reset to the default, matching getSize.

◆ setImmediate()

void cugl::graphics::FrameBuffer::setImmediate ( bool value )

Sets whether rendering to this framebuffer happens immediately

An immediate framebuffer guarantees that its image(s) are available as soon as GraphicsShader#end is called. Otherwise, there may be a delay between when GraphicsShader#end is called and getImage is available. There is no indication for when such an image is available, short of progressing to the next frame.

This is an optimization for subpass rendering on Vulkan. It has no effect in OpenGL. This value cannot be changed during the middle of an active render pass on this target.

Parameters

value Whether rendering to this framebuffer happens immediately

◆ setName()

void cugl::graphics::FrameBuffer::setName ( std::string name )

inline

Sets the name of this frame buffer.

A name is a user-defined way of identifying a buffer. It is used for debugging purposes only, and has no affect on the graphics pipeline.

Parameters

name	The name of this frame buffer.

◆ setViewPort() [1/2]

void cugl::graphics::FrameBuffer::setViewPort ( const Rect & viewport )

inline

Sets the active viewport for this framebuffer

By default, the viewport is the entire scope of the framebuffer. Changing this value restricts the portion of the framebuffer that a GraphicsShader will draw to. The viewport origin is from the bottom left for all graphics APIs.

Note that this value will not take affect until the call to the next drawing pass of a GraphicsShader.

Parameters

viewport The active viewport for this framebuffer

◆ setViewPort() [2/2]

void cugl::graphics::FrameBuffer::setViewPort	(	int	x,
		int	y,
		int	width,
		int	height
	)

Sets the active viewport for this framebuffer

By default, the viewport is the entire scope of the framebuffer. Changing this value restricts the portion of the framebuffer that a GraphicsShader will draw to. The viewport origin is from the bottom left for all graphics APIs.

Note that this value will not take affect until the call to the next drawing pass of a GraphicsShader.

Parameters

x	The x-coordinate of the origin
y	The y-coordinate of the origin
width	The viewport width
height	The viewport height

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

/Users/wmwhite/Developer/CUGL/include/cugl/graphics/CUFrameBuffer.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ FrameBuffer()

◆ ~FrameBuffer()

Member Function Documentation

◆ activate()

◆ alloc() [1/2]

◆ alloc() [2/2]

◆ allocWithFormats() [1/3]

◆ allocWithFormats() [2/3]

◆ allocWithFormats() [3/3]

◆ allocWithRenderPass()

◆ clear()

◆ dispose()

◆ getAttachments()

◆ getDepthStencil()

◆ getDisplay()

◆ getHeight()

◆ getImage()

◆ getImplementation()

◆ getName()

◆ getRenderPass()

◆ getSize()

◆ getTexture()

◆ getViewPort()

◆ getWidth()

◆ init() [1/2]

◆ init() [2/2]

◆ initWithFormats() [1/3]

◆ initWithFormats() [2/3]

◆ initWithFormats() [3/3]

◆ initWithRenderPass()

◆ isImmediate()

◆ restoreViewPort()

◆ setImmediate()

◆ setName()

◆ setViewPort() [1/2]

◆ setViewPort() [2/2]