#include <tb_render_target.hpp>

Inheritance diagram for TurtleBrains::Graphics::RenderTarget:

Public Member Functions
	RenderTarget (const PixelSpace &targetWidth, const PixelSpace &targetHeight, TextureFormat colorFormat=TextureFormat::ColorARGB8, TextureFormat depthFormat=TextureFormat::InvalidFormat)

	RenderTarget (const PixelSpace &targetWidth, const PixelSpace &targetHeight, std::vector< TextureFormat > colorFormats, TextureFormat depthFormat=TextureFormat::InvalidFormat)

	~RenderTarget (void)

void	BindRenderTarget (const tbCore::uint16 mipLevel=0) const

void	UnbindRenderTarget (void) const

void	BindPartialRenderTarget (const tbCore::uint8 attachmentIndex=0, const tbCore::uint16 mipLevel=0) const

void	UnbindPartialRenderTarget (const tbCore::uint8 attachmentIndex=0) const

void	ClearRenderTarget (const Color clearColor=ColorPalette::White) const

void	ManagePixelData (const bool managePixelData)

void	SetMipmap (bool doMipmaps, bool manualMipmaps=false)

tbCore::uint32	GetNumberOfMipmapLevels (void) const

void	BlitBetweenMipLevels (const tbCore::uint8 attachmentLayer, const tbCore::uint16 destinationMipLevel, const tbCore::uint16 sourceMipLevel)

bool	IsTextureValid (void) const

tbGraphics::TextureHandle	GetColorTextureHandle (const tbCore::uint8 attachmentIndex=0) const

tbGraphics::TextureHandle	GetDepthTextureHandle (void) const

PixelSpace	GetWidth (void) const

PixelSpace	GetHeight (void) const

float	GetAspectRatio (void) const

Static Public Member Functions
static void	CreateGraphicsContext (void)

static void	DestroyGraphicsContext (void)

Detailed Description

The RenderTarget sets up a texture to render to and apply to be rendered after. Just call BindRenderTarget() to start rendering on the texture and UnbindRenderTarget() to go back to normal.

Constructor & Destructor Documentation

◆ RenderTarget() [1/2]

TurtleBrains::Graphics::RenderTarget::RenderTarget	(	const PixelSpace &	targetWidth,
		const PixelSpace &	targetHeight,
		TextureFormat	colorFormat = `TextureFormat::ColorARGB8`,
		TextureFormat	depthFormat = `TextureFormat::InvalidFormat`
	)

explicit

Creates a RenderTarget with specified width and height that can be used to setup and render desired results to the target texture and then applied however later, for full screen effects or other.

Parameters

targetWidth	The width of the target texture(s) in pixels.
targetHeight	The height of the target texture(s) in pixels.
colorFormat	The format of the color texture to render to, this defauls to 32 bit-per-pixel ARGB8 format but can be changed, and can also be InvalidFormat to create a depth only render target.
depthFormat	The format of the depth texture, if one should exist. Defaults to no depth target by using InvalidFormat but otherwise should be Depth16 or Depth24.

Note: When converting from the old TargetType constructor (demolished 2023-08-04) any use of a color target had a texture format of TextureFormat::ColorARGB8 and any depth target used TextureFormat::Depth24 with the exception of HDR formats, which wasn't added to any project specific code prior to this removal.

◆ RenderTarget() [2/2]

TurtleBrains::Graphics::RenderTarget::RenderTarget	(	const PixelSpace &	targetWidth,
		const PixelSpace &	targetHeight,
		std::vector< TextureFormat >	colorFormats,
		TextureFormat	depthFormat = `TextureFormat::InvalidFormat`
	)

explicit

Creates a RenderTarget with specified width and height that can be used to setup and render desired results to multiple target textures with possibly a variety of formats. Currently limited to a maximum of 4 colorFormat and a single depthFormat.

Parameters

targetWidth	The width of the target texture(s) in pixels.
targetHeight	The height of the target texture(s) in pixels.
colorFormat	The formats of the color textures to render to in order of their attachment points. Can also be only InvalidFormat to create a depth only render target.
depthFormat	The format of the depth texture, if one should exist. Defaults to no depth target by using InvalidFormat but otherwise should be Depth16 or Depth24.

◆ ~RenderTarget()

TurtleBrains::Graphics::RenderTarget::~RenderTarget ( void )

Cleans up all resources used by the RenderTarget.

Member Function Documentation

◆ BindPartialRenderTarget()

void TurtleBrains::Graphics::RenderTarget::BindPartialRenderTarget	(	const tbCore::uint8	attachmentIndex = `0`,
		const tbCore::uint16	mipLevel = `0`
	)		const

Similar to BindRenderTarget() this sets up the context for draw calls to be displayed to the RenderTarget. With a RenderTarget that contains multiple color attachments you can use this function to bind a specific texture to attachment point 0, including the depth target if one existed.

Parameters

attachmentIndex	The 0 based index of the color texture as added during construction.
mipLevel	Can be used to specify a mipLevel to bind for rendering to that level. This requires mipmapping to be on and set to manualMipmaps to avoid auto generated mipmaps from overwriting.

Note: Make sure to pair with a matching UnbindPartialRenderTarget() to get back to the frame buffer.

◆ BindRenderTarget()

void TurtleBrains::Graphics::RenderTarget::BindRenderTarget ( const tbCore::uint16 mipLevel = 0 ) const

Binds the RenderTarget to the context so any other Render calls will get displayed on the target texture(s) instead of the frame buffer. Must call UnbindRenderTarget() to return back to the frame buffer. This will bind all the attached color textures in their order, as well as a depth texture if valid format was specified during construction. Use BindPartialRenderTarget() for a specific target texture if not all are desired.

Parameters

mipLevel Can be used to specify a mipLevel to bind for rendering to that level. This requires mipmapping to be on and set to manualMipmaps to avoid auto generated mipmaps from overwriting.

Note: If multiple RenderTargets are used, only one should be bound at any given time, so be sure to unbind before attempting to bind another RenderTarget.; Prior to 2023-08-01 the BindRenderTarget() function would also clear the render target to white color and reset the depth. This was removed to decrease losses of performance, for the old behaviour you can call ClearRenderTarget().

◆ BlitBetweenMipLevels()

void TurtleBrains::Graphics::RenderTarget::BlitBetweenMipLevels	(	const tbCore::uint8	attachmentLayer,
		const tbCore::uint16	destinationMipLevel,
		const tbCore::uint16	sourceMipLevel
	)

Performs a blit (linear-filtered copy) between two separate mip levels.

Parameters

destinationMipLevel	The destination mip level.
sourceMipLevel	The source mip level.

Note: Currently this only blits the color image data.; This trashes any bound RenderTargets, so assume you have to bind them after this.

◆ ClearRenderTarget()

void TurtleBrains::Graphics::RenderTarget::ClearRenderTarget ( const Color clearColor = ColorPalette::White ) const

Clears the render target to white color with maximum depth values for rendering purposes.

Parameters

clearColor Sets the color to clear the target to.

◆ CreateGraphicsContext()

static void TurtleBrains::Graphics::RenderTarget::CreateGraphicsContext ( void )

static

Call when the graphics context is created, or recreated, to ensure the ManagedPixelData is reuploaded to the GPU correctly so active RenderTargets can be recreated as they were.

◆ DestroyGraphicsContext()

static void TurtleBrains::Graphics::RenderTarget::DestroyGraphicsContext ( void )

static

Call as the graphics context is being destroyed to cleanup after all the active RenderTargets.

◆ GetAspectRatio()

float TurtleBrains::Graphics::RenderTarget::GetAspectRatio ( void ) const

Computes and returns the aspect ratio of the RenderTarget, (width/height) 1920 / 1080 ~= 1.77778.

◆ GetColorTextureHandle()

tbGraphics::TextureHandle TurtleBrains::Graphics::RenderTarget::GetColorTextureHandle ( const tbCore::uint8 attachmentIndex = 0 ) const

Retrieves the texture handle of a color attachment within the RenderTarget. The attachmentIndex is in the same order you specified during construction of the RenderTarget. This texture will be plain white unless it was rendered to between Bind/Unbind.

Parameters

attachmentIndex The 0 based index of the color texture as added during construction.

Note: This will return an InvalidTexture() if the format at attachmentIndex was invalid.

◆ GetDepthTextureHandle()

tbGraphics::TextureHandle TurtleBrains::Graphics::RenderTarget::GetDepthTextureHandle ( void ) const

Retrieves the texture handle of the RenderTarget's depth 'buffer' to be used how one wishes.

Note: This will return an InvalidTexture() if there was no depth texture attached during construction.

◆ GetHeight()

PixelSpace TurtleBrains::Graphics::RenderTarget::GetHeight ( void ) const

Retrieves the height in pixels.

◆ GetNumberOfMipmapLevels()

tbCore::uint32 TurtleBrains::Graphics::RenderTarget::GetNumberOfMipmapLevels ( void ) const

This is for rendering to the various mip levels in manual mipmap mode. The number of mip levels available is only valid after BindRenderTarget on the object with a mipLevel of 0 as this will generate the mipmaps for the target textures. This means you'll generally need to loop from 1 <= i < numberOfMips.

◆ GetWidth()

PixelSpace TurtleBrains::Graphics::RenderTarget::GetWidth ( void ) const

Retrieves the width in pixels.

◆ IsTextureValid()

bool TurtleBrains::Graphics::RenderTarget::IsTextureValid ( void ) const

Returns true if at some point Bind and Unbind has been called to render to the texture target since creation or a graphics context change.

Note: This can be used instead of raw memory to refresh a RenderTarget after context change by polling this before it would get rendered.

◆ ManagePixelData()

void TurtleBrains::Graphics::RenderTarget::ManagePixelData ( const bool managePixelData )

This function will set a flag that will keep or destroy the pixel data after a bind. This will increase memory usage on the system side, as well as incur a performance penalty on UnbindRenderTarget, when the texture data is getting copied, but it allows the render target texture to be reloaded on the fly when the graphics context changes. By default this is disabled; to keep the context change support when disabled, use IsTextureValid() to redraw the texture before it gets used/rendered.

Note: If pixel data exists and this is turned off, that pixel data is destroyed. If there is no pixel data when this is turned on, there will still be no pixel data. Call Bind/Unbind to render to the target and create the pixel data.; 2023-08-04: Managed pixel data is only working when a single color attachment is used with a format of ColorARGB8 and possibly the Depth24, although that might be hit or miss. There are plans to someday support other formats and ensure depth is working as well.

◆ SetMipmap()

void TurtleBrains::Graphics::RenderTarget::SetMipmap	(	bool	doMipmaps,
		bool	manualMipmaps = `false`
	)

Sets whether or not the color and depth textures will generate mipmaps and use mipmap filtering. By default mipmapping is turned OFF.

Parameters

doMipmaps	Set this to true to turn mipmapping on, or false to turn it off.
manualMipmaps	When true the mipmaps will not automatically generate with exception of during this call to ensure the GPU allocates space for the mipmaps. You are responsible for binding to and rendering the mip levels yourself.

Note: The toggle may occur on the next Bind/Unbind instead of immediately, although it may also regenerate the textures to attach in order to create or destroy mipmaps.

◆ UnbindPartialRenderTarget()

void TurtleBrains::Graphics::RenderTarget::UnbindPartialRenderTarget ( const tbCore::uint8 attachmentIndex = 0 ) const

Changes the graphics context back to rendering on the frame buffer again. The pixel data of attached textures will be valid and retrievable by binding textures from GetColorTextureHandle() and GetDepthTextureHandle() when ready. The pixel data may also remain in system memory (or not) depending on the storage setting; ManagePixelData().

Parameters

attachmentIndex The 0 based index of the color texture as added during construction. Must match the value in the BindPartialRenderTarget() call.

◆ UnbindRenderTarget()

void TurtleBrains::Graphics::RenderTarget::UnbindRenderTarget ( void ) const

Changes the graphics context back to rendering on the frame buffer again. The pixel data of attached textures will be valid and retrievable by binding textures from GetColorTextureHandle() and GetDepthTextureHandle() when ready. The pixel data may also remain in system memory (or not) depending on the storage setting; ManagePixelData().

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ RenderTarget() [1/2]

◆ RenderTarget() [2/2]

◆ ~RenderTarget()

Member Function Documentation

◆ BindPartialRenderTarget()

◆ BindRenderTarget()

◆ BlitBetweenMipLevels()

◆ ClearRenderTarget()

◆ CreateGraphicsContext()

◆ DestroyGraphicsContext()

◆ GetAspectRatio()

◆ GetColorTextureHandle()

◆ GetDepthTextureHandle()

◆ GetHeight()

◆ GetNumberOfMipmapLevels()

◆ GetWidth()

◆ IsTextureValid()

◆ ManagePixelData()

◆ SetMipmap()

◆ UnbindPartialRenderTarget()

◆ UnbindRenderTarget()