CUGL 2.5
Cornell University Game Library
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | List of all members
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
 
GLuint getFramebuffer () const
 
void begin ()
 
void end ()
 

Static Public Member Functions

static std::shared_ptr< RenderTargetalloc (int width, int height)
 
static std::shared_ptr< RenderTargetalloc (int width, int height, size_t outputs)
 
static std::shared_ptr< RenderTargetalloc (int width, int height, std::initializer_list< Texture::PixelFormat > outputs)
 
static std::shared_ptr< RenderTargetalloc (int width, int height, std::vector< Texture::PixelFormat > outputs)
 
static std::shared_ptr< RenderTargetalloc (int width, int height, std::unordered_map< GLuint, Texture::PixelFormat > outputs)
 
static std::shared_ptr< RenderTargetalloc (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
widthThe drawing width of this render target
heightThe 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
widthThe drawing width of this render target
heightThe drawing width of this render target
outputsThe 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
widthThe drawing width of this render target
heightThe drawing width of this render target
outputsThe 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
widthThe drawing width of this render target
heightThe drawing width of this render target
outputsThe 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
widthThe drawing width of this render target
heightThe drawing width of this render target
outputsThe 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
widthThe drawing width of this render target
heightThe drawing width of this render target
outputsThe list of desired texture formats
outsizeThe 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

◆ getFramebuffer()

GLuint cugl::RenderTarget::getFramebuffer ( ) const
inline

Returns the framebuffer object for this render target

The framebuffer object is the OpenGL object that stores the output textures and depth/stencil buffer. It is created when the render target is initialized.

This function should only be necessary for the Vulkan renderer, as Vulkan::begin requires a framebuffer object if you wish to render to a different render target than the swapchain.

Returns
the framebuffer object 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
indexThe 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
widthThe drawing width of this render target
heightThe 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
widthThe drawing width of this render target
heightThe drawing width of this render target
outputsThe 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
widthThe drawing width of this render target
heightThe drawing width of this render target
outputsThe 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
widthThe drawing width of this render target
heightThe drawing width of this render target
outputsThe 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
widthThe drawing width of this render target
heightThe drawing width of this render target
outputsThe 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
widthThe drawing width of this render target
heightThe drawing width of this render target
outputsThe list of desired texture formats
outsizeThe 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
colorThe clear color for this render target.

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