cugl::RenderTarget Class Reference

#include <CURenderTarget.h>

Public Member Functions
	RenderTarget ()
	~RenderTarget ()
void	dispose ()
bool	init (int width, int height)
bool	init (int width, int height, size_t outputs)
bool	init (int width, int height, std::initializer_list< Texture::PixelFormat > outputs)
bool	init (int width, int height, std::vector< Texture::PixelFormat > outputs)
bool	init (int width, int height, std::unordered_map< GLuint, Texture::PixelFormat > outputs)
bool	init (int width, int height, Texture::PixelFormat *outputs, size_t outsize)
int	getWidth () const
int	getHeight () const
Color4	getClearColor () const
void	setClearColor (const Color4 color)
size_t	getOutputSize () const
const std::shared_ptr< Texture > &	getTexture (size_t index=0) const
const std::shared_ptr< Texture > &	getDepthStencil () const
void	begin ()
void	end ()

Static Public Member Functions
static std::shared_ptr< RenderTarget >	alloc (int width, int height)
static std::shared_ptr< RenderTarget >	alloc (int width, int height, size_t outputs)
static std::shared_ptr< RenderTarget >	alloc (int width, int height, std::initializer_list< Texture::PixelFormat > outputs)
static std::shared_ptr< RenderTarget >	alloc (int width, int height, std::vector< Texture::PixelFormat > outputs)
static std::shared_ptr< RenderTarget >	alloc (int width, int height, std::unordered_map< GLuint, Texture::PixelFormat > outputs)
static std::shared_ptr< RenderTarget >	alloc (int width, int height, Texture::PixelFormat *outputs, size_t outsize)

Detailed Description

This is a class representing an offscreen render target (framebuffer).

A render target allows the user to draw to a texture before drawing to a screen. This allows for the potential for post-processing effects. To draw to a render target simply call the begin method before drawing. From that point on all drawing commands will be sent to the associated texture instead of the screen. Call end to resume drawing to the screen.

Render targets should not be stacked. It is not safe to call a begin/end pair of one render target inside of another begin/end pair. Control to the screen should be resumed before using another render target.

While render targets must have at least one output texture, they can support multiple textures 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 OpenGL 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 Texture::PixelFormat. Finally, all output textures are bound sequentially to output locations 0..#outputs-1. However, we find that still allows us to handle the vast majority of applications with a framebuffer.

Constructor & Destructor Documentation

RenderTarget()

cugl::RenderTarget::RenderTarget

(

)

Creates an uninitialized render target with no output textures.

You must initialize the render target to create an output texture.

~RenderTarget()

cugl::RenderTarget::~RenderTarget

(

)

Deletes this render target, disposing all resources.

Member Function Documentation

alloc() [1/6]

static std::shared_ptr<RenderTarget> cugl::RenderTarget::alloc ( int  width, int  height  )

inlinestatic

Returns a new render target with a single RGBA output texture.

The output texture will have the given width and size.

Parameters

width	The drawing width of this render target
height	The drawing width of this render target

Returns

a new render target with a single RGBA output texture.

alloc() [2/6]

static std::shared_ptr<RenderTarget> cugl::RenderTarget::alloc ( int  width, int  height, size_t  outputs  )

inlinestatic

Returns a new render target with multiple RGBA output textures.

The output textures 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 render target. 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. OpenGL only guarantees up to 8 output textures.

Parameters

width	The drawing width of this render target
height	The drawing width of this render target
outputs	The number of output textures

Returns

a new render target with multiple RGBA output textures.

alloc() [3/6]

static std::shared_ptr<RenderTarget> cugl::RenderTarget::alloc ( int  width, int  height, std::initializer_list< Texture::PixelFormat >  outputs  )

inlinestatic

Returns a new render target with multiple textures of the given format.

The output textures will have the given width and size. They will be assigned the appropriate format as specified in Texture#init.
They will be assigned locations 0..#outputs-1. These locations should be bound with the layout keyword in any shader used with this render target. 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.
OpenGL only guarantees up to 8 output textures.

Parameters

width	The drawing width of this render target
height	The drawing width of this render target
outputs	The list of desired texture formats

Returns

a new render target with multiple textures of the given format.

alloc() [4/6]

static std::shared_ptr<RenderTarget> cugl::RenderTarget::alloc ( int  width, int  height, std::unordered_map< GLuint, Texture::PixelFormat >  outputs  )

inlinestatic

Returns a new render target with multiple textures of the given format.

The output textures will have the given width and size. They will be assigned the appropriate format as specified in Texture#init. They will be assigned locations matching the keys of the map outputs. These locations should be bound with the layout keyword in any shader used with this render target. 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. OpenGL only guarantees up to 8 output textures.

Parameters

width	The drawing width of this render target
height	The drawing width of this render target
outputs	The map of desired texture formats for each location

Returns

a new render target with multiple textures of the given format.

alloc() [5/6]

static std::shared_ptr<RenderTarget> cugl::RenderTarget::alloc ( int  width, int  height, std::vector< Texture::PixelFormat >  outputs  )

inlinestatic

Returns a new render target with multiple textures of the given format.

The output textures will have the given width and size. They will be assigned the appropriate format as specified in Texture#init.
They will be assigned locations 0..#outputs-1. These locations should be bound with the layout keyword in any shader used with this render target. 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.
OpenGL only guarantees up to 8 output textures.

Parameters

width	The drawing width of this render target
height	The drawing width of this render target
outputs	The list of desired texture formats

Returns

a new render target with multiple textures of the given format.

alloc() [6/6]

static std::shared_ptr<RenderTarget> cugl::RenderTarget::alloc ( int  width, int  height, Texture::PixelFormat *  outputs, size_t  outsize  )

inlinestatic

Returns a new render target with multiple textures of the given format.

The output textures will have the given width and size. They will be assigned the appropriate format as specified in Texture#init.
They will be assigned locations 0..#outsize-1. These locations should be bound with the layout keyword in any shader used with this render target. 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.
OpenGL only guarantees up to 8 output textures.

Parameters

width	The drawing width of this render target
height	The drawing width of this render target
outputs	The list of desired texture formats
outsize	The number of elements in outputs

Returns

a new render target with multiple textures of the given format.

begin()

void cugl::RenderTarget::begin

(

)

Begins sending draw commands to this render target.

This method clears all of the output textures with the clear color of this render target. It also sets the viewpoint to match the size of this render target (which may not be the same as the screen). The old viewport is saved and will be restored when end is called.

It is NOT safe to call a begin/end pair of a render target inside of another render target. Render targets do not keep a stack. They alway return control to the default render target (the screen) when done.

dispose()

void cugl::RenderTarget::dispose

(

)

Deletes the render target and resets all attributes.

You must reinitialize the render target to use it.

end()

void cugl::RenderTarget::end

(

)

Stops sendinging draw commands to this render target.

When this method is called, the original viewport will be restored. Future draw commands will be sent directly to the screen.

It is NOT safe to call a begin/end pair of a render target inside of another render target. Render targets do not keep a stack. They alway return control to the default render target (the screen) when done.

getClearColor()

Color4 cugl::RenderTarget::getClearColor ( ) const

inline

Returns the clear color for this render target.

The clear color is used to clear the texture when the method begin is called.

Returns

the clear color for this render target.

getDepthStencil()

const std::shared_ptr<Texture>& cugl::RenderTarget::getDepthStencil ( ) const

inline

Returns the depth/stencil buffer for this render target

The framebuffer for a render target always uses a combined depth and stencil buffer. 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 render target

getHeight()

int cugl::RenderTarget::getHeight ( ) const

inline

Returns the height of this render target

Returns

the height of this render target

getOutputSize()

size_t cugl::RenderTarget::getOutputSize ( ) const

inline

Returns the number of output textures for this render target.

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

Returns

the number of output textures for this render target.

getTexture()

const std::shared_ptr<Texture>& cugl::RenderTarget::getTexture

(

size_t

index = 0

)

const

Returns the output texture for the given index.

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

Parameters

index

The output index

Returns

the output texture for the given index.

getWidth()

int cugl::RenderTarget::getWidth ( ) const

inline

Returns the width of this render target

Returns

the width of this render target

init() [1/6]

bool cugl::RenderTarget::init ( int  width, int  height  )

inline

Initializes this target with a single RGBA output texture.

The output texture will have the given width and size.

Parameters

width	The drawing width of this render target
height	The drawing width of this render target

Returns

true if initialization was successful.

init() [2/6]

bool cugl::RenderTarget::init	(	int	width,
		int	height,
		size_t	outputs
	)

Initializes this target with multiple RGBA output textures.

The output textures 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 render target. 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. OpenGL only guarantees up to 8 output textures.

Parameters

width	The drawing width of this render target
height	The drawing width of this render target
outputs	The number of output textures

Returns

true if initialization was successful.

init() [3/6]

bool cugl::RenderTarget::init	(	int	width,
		int	height,
		std::initializer_list< Texture::PixelFormat >	outputs
	)

Initializes this target with multiple textures of the given format.

The output textures will have the given width and size. They will be assigned the appropriate format as specified in Texture#init.
They will be assigned locations 0..#outputs-1. These locations should be bound with the layout keyword in any shader used with this render target. 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.
OpenGL only guarantees up to 8 output textures.

Parameters

width	The drawing width of this render target
height	The drawing width of this render target
outputs	The list of desired texture formats

Returns

true if initialization was successful.

init() [4/6]

bool cugl::RenderTarget::init	(	int	width,
		int	height,
		std::unordered_map< GLuint, Texture::PixelFormat >	outputs
	)

Initializes this target with multiple textures of the given format.

The output textures will have the given width and size. They will be assigned the appropriate format as specified in Texture#init. They will be assigned locations matching the keys of the map outputs. These locations should be bound with the layout keyword in any shader used with this render target. 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. OpenGL only guarantees up to 8 output textures.

Parameters

width	The drawing width of this render target
height	The drawing width of this render target
outputs	The map of desired texture formats for each location

Returns

true if initialization was successful.

init() [5/6]

bool cugl::RenderTarget::init	(	int	width,
		int	height,
		std::vector< Texture::PixelFormat >	outputs
	)

Initializes this shader with multiple textures of the given format.

The output textures will have the given width and size. They will be assigned the appropriate format as specified in Texture#init.
They will be assigned locations 0..#outputs-1. These locations should be bound with the layout keyword in any shader used with this render target. 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.
OpenGL only guarantees up to 8 output textures.

Parameters

width	The drawing width of this render target
height	The drawing width of this render target
outputs	The list of desired texture formats

Returns

true if initialization was successful.

init() [6/6]

bool cugl::RenderTarget::init	(	int	width,
		int	height,
		Texture::PixelFormat *	outputs,
		size_t	outsize
	)

Initializes this target with multiple textures of the given format.

The output textures will have the given width and size. They will be assigned the appropriate format as specified in Texture#init.
They will be assigned locations 0..#outsize-1. These locations should be bound with the layout keyword in any shader used with this render target. 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.
OpenGL only guarantees up to 8 output textures.

Parameters

width	The drawing width of this render target
height	The drawing width of this render target
outputs	The list of desired texture formats
outsize	The number of elements in outputs

Returns

true if initialization was successful.

setClearColor()

void cugl::RenderTarget::setClearColor ( const Color4  color )

inline

Sets the clear color for this render target.

The clear color is used to clear the texture when the method begin is called.

Parameters

color

The clear color for this render target.

---

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

• include/cugl/render/CURenderTarget.h