LiteFX 0.4.1.2025
Computer Graphics Engine
Loading...
Searching...
No Matches
LiteFX::Rendering::IFrameBuffer Class Referenceabstract

The interface for a frame buffer. More...

#include <rendering_api.hpp>

Inherits LiteFX::Rendering::IStateResource, and LiteFX::SharedObject.

Inherited by LiteFX::Rendering::FrameBuffer< IDirectX12Image >, LiteFX::Rendering::FrameBuffer< IVulkanImage >, and LiteFX::Rendering::FrameBuffer< TImage >.

Classes

struct  ReleasedEventArgs
 Event arguments that are published to subscribers when a frame buffer gets released. More...
 
struct  ResizeEventArgs
 Event arguments that are published to subscribers when a frame buffer gets resized. More...
 

Public Member Functions

 ~IFrameBuffer () noexcept override
 Releases the frame buffer.
 
virtual const Size2dsize () const noexcept=0
 Returns the current size of the frame buffer.
 
virtual size_t getWidth () const noexcept=0
 Returns the current width of the frame buffer.
 
virtual size_t getHeight () const noexcept=0
 Returns the current height of the frame buffer.
 
virtual void mapRenderTarget (const RenderTarget &renderTarget, UInt32 index)=0
 Maps a render target to a frame buffer image.
 
virtual void mapRenderTarget (const RenderTarget &renderTarget, StringView imageName)=0
 Maps a render target to a frame buffer image.
 
void mapRenderTarget (const RenderTarget &renderTarget)
 Maps a render target to a frame buffer image using the render targets name to look up the image.
 
void mapRenderTargets (Span< const RenderTarget > renderTargets)
 Maps a set of render targets to the frame buffer images, using the names of the render targets to look up the images.
 
virtual void unmapRenderTarget (const RenderTarget &renderTarget) noexcept=0
 Removes a mapping between a render target and an image in the frame buffer.
 
Enumerable< const IImage & > images () const
 Returns all images contained by the frame buffer.
 
virtual const IImageoperator[] (UInt32 index) const =0
 Returns an image from the frame buffer.
 
virtual const IImageimage (UInt32 index) const =0
 Returns an image from the frame buffer.
 
virtual const IImageoperator[] (const RenderTarget &renderTarget) const =0
 Resolves a render target and returns the image mapped to it.
 
virtual const IImageimage (const RenderTarget &renderTarget) const =0
 Resolves a render target and returns the image mapped to it.
 
virtual const IImageoperator[] (StringView renderTargetName) const =0
 Resolves a render target name and returns the image mapped to it.
 
virtual const IImageimage (StringView renderTargetName) const =0
 Resolves a render target name and returns the image mapped to it.
 
virtual const IImageresolveImage (UInt64 hash) const =0
 Resolves a render target name hash and returns the image mapped to it.
 
template<typename TSelf >
auto addImage (this TSelf &&self, Format format, MultiSamplingLevel samples=MultiSamplingLevel::x1, ResourceUsage usage=ResourceUsage::FrameBufferImage) -> TSelf &&
 Adds an image to the frame buffer.
 
void addImage (Format format, MultiSamplingLevel samples=MultiSamplingLevel::x1, ResourceUsage usage=ResourceUsage::FrameBufferImage)
 Adds an image to the frame buffer.
 
template<typename TSelf >
auto addImage (this TSelf &&self, StringView name, Format format, MultiSamplingLevel samples=MultiSamplingLevel::x1, ResourceUsage usage=ResourceUsage::FrameBufferImage) -> TSelf &&
 Adds an image to the frame buffer.
 
virtual void addImage (const String &name, Format format, MultiSamplingLevel samples=MultiSamplingLevel::x1, ResourceUsage usage=ResourceUsage::FrameBufferImage)=0
 Adds an image to the frame buffer.
 
template<typename TSelf >
auto addImage (this TSelf &&self, const RenderTarget &renderTarget, MultiSamplingLevel samples=MultiSamplingLevel::x1, ResourceUsage usage=ResourceUsage::FrameBufferImage) -> TSelf &&
 Adds an image for a render target to the frame buffer.
 
void addImage (const RenderTarget &renderTarget, MultiSamplingLevel samples=MultiSamplingLevel::x1, ResourceUsage usage=ResourceUsage::FrameBufferImage)
 Adds an image for a render target to the frame buffer.
 
template<typename TSelf >
auto addImage (this TSelf &&self, StringView name, const RenderTarget &renderTarget, MultiSamplingLevel samples=MultiSamplingLevel::x1, ResourceUsage usage=ResourceUsage::FrameBufferImage) -> TSelf &&
 Adds an image for a render target to the frame buffer.
 
virtual void addImage (const String &name, const RenderTarget &renderTarget, MultiSamplingLevel samples=MultiSamplingLevel::x1, ResourceUsage usage=ResourceUsage::FrameBufferImage)=0
 Adds an image for a render target to the frame buffer.
 
template<typename TSelf >
auto addImages (this TSelf &&self, Span< const RenderTarget > renderTargets, MultiSamplingLevel samples=MultiSamplingLevel::x1, ResourceUsage usage=ResourceUsage::FrameBufferImage) -> TSelf &&
 Adds multiple images for a set of render targets to the frame buffer.
 
virtual void resize (const Size2d &renderArea)=0
 Causes the frame buffer to be invalidated and recreated with a new size.
 
- Public Member Functions inherited from LiteFX::Rendering::IStateResource
virtual ~IStateResource () noexcept=default
 Releases the state resource instance.
 
virtual const Stringname () const noexcept=0
 Returns the name of the resource.
 
- Public Member Functions inherited from LiteFX::SharedObject
virtual ~SharedObject () noexcept=default
 Destroys the shared object.
 
template<typename TSelf >
auto shared_from_this (this TSelf &&self) noexcept
 Returns a shared pointer to the current object instance.
 
template<typename TSelf >
auto weak_from_this (this TSelf &&self) noexcept -> WeakPtr< std::remove_reference_t< TSelf > >
 Returns a weak pointer to the current object instance.
 

Public Attributes

Event< ResizeEventArgsresized
 Invoked when the frame buffer gets resized.
 
Event< ReleasedEventArgsreleased
 Invoked when the frame buffer gets released.
 

Protected Member Functions

 IFrameBuffer () noexcept=default
 
 IFrameBuffer (IFrameBuffer &&) noexcept=default
 
 IFrameBuffer (const IFrameBuffer &)=delete
 
IFrameBufferoperator= (IFrameBuffer &&) noexcept=default
 
IFrameBufferoperator= (const IFrameBuffer &)=delete
 
- Protected Member Functions inherited from LiteFX::Rendering::IStateResource
 IStateResource () noexcept=default
 
 IStateResource (const IStateResource &)=delete
 
 IStateResource (IStateResource &&) noexcept=default
 
IStateResourceoperator= (const IStateResource &)=delete
 
IStateResourceoperator= (IStateResource &&) noexcept=default
 
- Protected Member Functions inherited from LiteFX::SharedObject
 SharedObject () noexcept=default
 Initializes a new shared object.
 
 SharedObject (SharedObject &&) noexcept=default
 
 SharedObject (const SharedObject &)=default
 
SharedObjectoperator= (SharedObject &&) noexcept=default
 
SharedObjectoperator= (const SharedObject &)=default
 

Additional Inherited Members

- Static Protected Member Functions inherited from LiteFX::SharedObject
template<typename T , typename... TArgs>
static auto create (TArgs &&... args) -> SharedPtr< T >
 Generic factory method used to create instances of the shared object.
 

Detailed Description

The interface for a frame buffer.

A frame buffer is a set of images of equal size, that are used by render targets and/or input attachments in a IRenderPass. When creating a new frame buffer, it is empty by default and needs images to be added into it. When beginning a render pass during rendering, a frame buffer instance needs to be passed to it. The render pass then tries to obtain an image for each render target from the frame buffer. It does this by resolving it's render targets (IRenderPass::renderTargets). A render target stores a unique identifier (IRenderTarget::identifier), that is used to obtain the image. Before this resolution process can be successful, the render targets must first be mapped to the images in the frame buffer by calling IFrameBuffer::mapRenderTarget. Calling this method multiple times will overwrite the mapping. It is also possible to remove a render target mapping by calling IFrameBuffer::unmapRenderTarget. This will result in future attempts to resolve this render target using the frame buffer instance to fail.

Constructor & Destructor Documentation

◆ IFrameBuffer() [1/3]

LiteFX::Rendering::IFrameBuffer::IFrameBuffer ( )
protecteddefaultnoexcept

◆ IFrameBuffer() [2/3]

LiteFX::Rendering::IFrameBuffer::IFrameBuffer ( IFrameBuffer && )
protecteddefaultnoexcept

◆ IFrameBuffer() [3/3]

LiteFX::Rendering::IFrameBuffer::IFrameBuffer ( const IFrameBuffer & )
protecteddelete

◆ ~IFrameBuffer()

LiteFX::Rendering::IFrameBuffer::~IFrameBuffer ( )
inlineoverridenoexcept

Releases the frame buffer.

Member Function Documentation

◆ addImage() [1/8]

void LiteFX::Rendering::IFrameBuffer::addImage ( const RenderTarget & renderTarget,
MultiSamplingLevel samples = MultiSamplingLevel::x1,
ResourceUsage usage = ResourceUsage::FrameBufferImage )
inline

Adds an image for a render target to the frame buffer.

Parameters
renderTargetThe render target for which to add an image.
samplesThe number of samples of the image.
usageThe desired resource usage flags for the image.

◆ addImage() [2/8]

virtual void LiteFX::Rendering::IFrameBuffer::addImage ( const String & name,
const RenderTarget & renderTarget,
MultiSamplingLevel samples = MultiSamplingLevel::x1,
ResourceUsage usage = ResourceUsage::FrameBufferImage )
pure virtual

Adds an image for a render target to the frame buffer.

Parameters
nameThe name of the image.
renderTargetThe render target for which to add an image.
samplesThe number of samples of the image.
usageThe desired resource usage flags for the image.

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, LiteFX::Rendering::Backends::VulkanFrameBuffer, LiteFX::Rendering::FrameBuffer< TImage >, LiteFX::Rendering::FrameBuffer< IDirectX12Image >, and LiteFX::Rendering::FrameBuffer< IVulkanImage >.

◆ addImage() [3/8]

virtual void LiteFX::Rendering::IFrameBuffer::addImage ( const String & name,
Format format,
MultiSamplingLevel samples = MultiSamplingLevel::x1,
ResourceUsage usage = ResourceUsage::FrameBufferImage )
pure virtual

Adds an image to the frame buffer.

Parameters
nameThe name of the image.
formatThe format of the image.
samplesThe number of samples of the image.
usageThe desired resource usage flags for the image.
Exceptions
InvalidArgumentExceptionThrown, if another image with the same name as provided in name has already been added to the frame buffer.

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, LiteFX::Rendering::Backends::VulkanFrameBuffer, LiteFX::Rendering::FrameBuffer< TImage >, LiteFX::Rendering::FrameBuffer< IDirectX12Image >, and LiteFX::Rendering::FrameBuffer< IVulkanImage >.

◆ addImage() [4/8]

void LiteFX::Rendering::IFrameBuffer::addImage ( Format format,
MultiSamplingLevel samples = MultiSamplingLevel::x1,
ResourceUsage usage = ResourceUsage::FrameBufferImage )
inline

Adds an image to the frame buffer.

Parameters
formatThe format of the image.
samplesThe number of samples of the image.
usageThe desired resource usage flags for the image.

◆ addImage() [5/8]

template<typename TSelf >
auto LiteFX::Rendering::IFrameBuffer::addImage ( this TSelf && self,
const RenderTarget & renderTarget,
MultiSamplingLevel samples = MultiSamplingLevel::x1,
ResourceUsage usage = ResourceUsage::FrameBufferImage ) -> TSelf&&
inline

Adds an image for a render target to the frame buffer.

Parameters
renderTargetThe render target for which to add an image.
samplesThe number of samples of the image.
usageThe desired resource usage flags for the image.

◆ addImage() [6/8]

template<typename TSelf >
auto LiteFX::Rendering::IFrameBuffer::addImage ( this TSelf && self,
Format format,
MultiSamplingLevel samples = MultiSamplingLevel::x1,
ResourceUsage usage = ResourceUsage::FrameBufferImage ) -> TSelf&&
inline

Adds an image to the frame buffer.

Parameters
formatThe format of the image.
samplesThe number of samples of the image.
usageThe desired resource usage flags for the image.

◆ addImage() [7/8]

template<typename TSelf >
auto LiteFX::Rendering::IFrameBuffer::addImage ( this TSelf && self,
StringView name,
const RenderTarget & renderTarget,
MultiSamplingLevel samples = MultiSamplingLevel::x1,
ResourceUsage usage = ResourceUsage::FrameBufferImage ) -> TSelf&&
inline

Adds an image for a render target to the frame buffer.

Parameters
nameThe name of the image.
renderTargetThe render target for which to add an image.
samplesThe number of samples of the image.
usageThe desired resource usage flags for the image.

◆ addImage() [8/8]

template<typename TSelf >
auto LiteFX::Rendering::IFrameBuffer::addImage ( this TSelf && self,
StringView name,
Format format,
MultiSamplingLevel samples = MultiSamplingLevel::x1,
ResourceUsage usage = ResourceUsage::FrameBufferImage ) -> TSelf&&
inline

Adds an image to the frame buffer.

Parameters
nameThe name of the image.
formatThe format of the image.
samplesThe number of samples of the image.
usageThe desired resource usage flags for the image.

◆ addImages()

template<typename TSelf >
auto LiteFX::Rendering::IFrameBuffer::addImages ( this TSelf && self,
Span< const RenderTarget > renderTargets,
MultiSamplingLevel samples = MultiSamplingLevel::x1,
ResourceUsage usage = ResourceUsage::FrameBufferImage ) -> TSelf&&
inline

Adds multiple images for a set of render targets to the frame buffer.

Note that the names of the images are built from the render target names.

Parameters
renderTargetsThe render targets for which to add an image.
samplesThe number of samples of the image.
usageThe desired resource usage flags for the image.

◆ getHeight()

virtual size_t LiteFX::Rendering::IFrameBuffer::getHeight ( ) const
pure virtualnoexcept

Returns the current height of the frame buffer.

Returns
The current height of the frame buffer.</returns
See also
width, size, resize

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ getWidth()

virtual size_t LiteFX::Rendering::IFrameBuffer::getWidth ( ) const
pure virtualnoexcept

Returns the current width of the frame buffer.

Returns
The current width of the frame buffer.
See also
height, size, resize

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ image() [1/3]

virtual const IImage & LiteFX::Rendering::IFrameBuffer::image ( const RenderTarget & renderTarget) const
pure virtual

Resolves a render target and returns the image mapped to it.

Parameters
renderTargetThe render target to resolve.
Returns
The image mapped to the render target.
Exceptions
InvalidArgumentExceptionThrown, if renderTarget is not mapped to an image in the frame buffer.

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ image() [2/3]

virtual const IImage & LiteFX::Rendering::IFrameBuffer::image ( StringView renderTargetName) const
pure virtual

Resolves a render target name and returns the image mapped to it.

Parameters
renderTargetNameThe render target name to resolve.
Returns
The image mapped to the render target.
Exceptions
InvalidArgumentExceptionThrown, if renderTargetName is not mapped to an image in the frame buffer.

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ image() [3/3]

virtual const IImage & LiteFX::Rendering::IFrameBuffer::image ( UInt32 index) const
pure virtual

Returns an image from the frame buffer.

Parameters
indexThe index of the image.
Returns
The image from the frame buffer with the index index .
Exceptions
ArgumentOutOfRangeExceptionThrown, if the index does not address an image in the frame buffer.

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ images()

Enumerable< const IImage & > LiteFX::Rendering::IFrameBuffer::images ( ) const
inline

Returns all images contained by the frame buffer.

Returns
A set of pointers to the images contained by the frame buffer.

◆ mapRenderTarget() [1/3]

void LiteFX::Rendering::IFrameBuffer::mapRenderTarget ( const RenderTarget & renderTarget)
inline

Maps a render target to a frame buffer image using the render targets name to look up the image.

When calling IRenderPass::begin, passing a frame buffer, the render pass attempts to resolve all render target images. In order for this resolution to be successful, a mapping first needs to be established between the render target and the image. This method establishes this mapping.

Calling this method multiple times will overwrite the mapped index.

Parameters
renderTargetThe render target to map the image to.
Exceptions
InvalidArgumentExceptionThrown, if the frame buffer does not contain an image with the same name as the render target.
See also
unmapRenderTarget

◆ mapRenderTarget() [2/3]

virtual void LiteFX::Rendering::IFrameBuffer::mapRenderTarget ( const RenderTarget & renderTarget,
StringView imageName )
pure virtual

Maps a render target to a frame buffer image.

When calling IRenderPass::begin, passing a frame buffer, the render pass attempts to resolve all render target images. In order for this resolution to be successful, a mapping first needs to be established between the render target and the image. This method establishes this mapping.

Calling this method multiple times will overwrite the mapped index.

Parameters
renderTargetThe render target to map the image to.
imageNameThe name of the image the render target maps to.
Exceptions
InvalidArgumentExceptionThrown, if the frame buffer does not contain an image with the name specified in imageName .
See also
unmapRenderTarget

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ mapRenderTarget() [3/3]

virtual void LiteFX::Rendering::IFrameBuffer::mapRenderTarget ( const RenderTarget & renderTarget,
UInt32 index )
pure virtual

Maps a render target to a frame buffer image.

When calling IRenderPass::begin, passing a frame buffer, the render pass attempts to resolve all render target images. In order for this resolution to be successful, a mapping first needs to be established between the render target and the image. This method establishes this mapping.

Calling this method multiple times will overwrite the mapped index.

Parameters
renderTargetThe render target to map the image to.
indexThe index of the image to map to the render target.
Exceptions
ArgumentOutOfRangeExceptionThrown, if index does not address an image in the frame buffer.
See also
unmapRenderTarget

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ mapRenderTargets()

void LiteFX::Rendering::IFrameBuffer::mapRenderTargets ( Span< const RenderTarget > renderTargets)
inline

Maps a set of render targets to the frame buffer images, using the names of the render targets to look up the images.

Parameters
renderTargetsThe render targets to map to the frame buffer.
Exceptions
InvalidArgumentExceptionThrown, if the frame buffer cannot map the name of one or more render targets to images.
See also
mapRenderTarget, unmapRenderTarget

◆ operator=() [1/2]

IFrameBuffer & LiteFX::Rendering::IFrameBuffer::operator= ( const IFrameBuffer & )
protecteddelete

◆ operator=() [2/2]

IFrameBuffer & LiteFX::Rendering::IFrameBuffer::operator= ( IFrameBuffer && )
protecteddefaultnoexcept

◆ operator[]() [1/3]

virtual const IImage & LiteFX::Rendering::IFrameBuffer::operator[] ( const RenderTarget & renderTarget) const
pure virtual

Resolves a render target and returns the image mapped to it.

Parameters
renderTargetThe render target to resolve.
Returns
The image mapped to the render target.
Exceptions
InvalidArgumentExceptionThrown, if renderTarget is not mapped to an image in the frame buffer.

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ operator[]() [2/3]

virtual const IImage & LiteFX::Rendering::IFrameBuffer::operator[] ( StringView renderTargetName) const
pure virtual

Resolves a render target name and returns the image mapped to it.

Parameters
renderTargetNameThe render target name to resolve.
Returns
The image mapped to the render target.
Exceptions
InvalidArgumentExceptionThrown, if renderTargetName is not mapped to an image in the frame buffer.

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ operator[]() [3/3]

virtual const IImage & LiteFX::Rendering::IFrameBuffer::operator[] ( UInt32 index) const
pure virtual

Returns an image from the frame buffer.

Parameters
indexThe index of the image.
Returns
The image from the frame buffer with the index index .
Exceptions
ArgumentOutOfRangeExceptionThrown, if the index does not address an image in the frame buffer.

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ resize()

virtual void LiteFX::Rendering::IFrameBuffer::resize ( const Size2d & renderArea)
pure virtual

Causes the frame buffer to be invalidated and recreated with a new size.

Parameters
renderAreaThe new dimensions of the frame buffer.

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ resolveImage()

virtual const IImage & LiteFX::Rendering::IFrameBuffer::resolveImage ( UInt64 hash) const
pure virtual

Resolves a render target name hash and returns the image mapped to it.

Parameters
hashThe render target name hash to resolve.
Returns
The image mapped to the render target.
Exceptions
InvalidArgumentExceptionThrown, if hash is not mapped to an image in the frame buffer.
See also
image

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ size()

virtual const Size2d & LiteFX::Rendering::IFrameBuffer::size ( ) const
pure virtualnoexcept

Returns the current size of the frame buffer.

Returns
The current size of the frame buffer.
See also
height, width, resize

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

◆ unmapRenderTarget()

virtual void LiteFX::Rendering::IFrameBuffer::unmapRenderTarget ( const RenderTarget & renderTarget)
pure virtualnoexcept

Removes a mapping between a render target and an image in the frame buffer.

If no image in the frame buffer is currently mapped to renderTarget , calling this method will have no effect.

Parameters
renderTargetThe render target to remove the mapping for.
See also
mapRenderTarget

Implemented in LiteFX::Rendering::Backends::DirectX12FrameBuffer, and LiteFX::Rendering::Backends::VulkanFrameBuffer.

Member Data Documentation

◆ released

Event<ReleasedEventArgs> LiteFX::Rendering::IFrameBuffer::released
mutable

Invoked when the frame buffer gets released.

Note that it is no longer valid to access the frame buffer when receiving this event. The only thing that can be assumed to still be valid is the pointer to the frame buffer. The intent of this event is to release any resources that depend on the frame buffer instance. Internally, render passes and pipelines use this event to release cached frame buffer states they hold, such as descriptor sets for input attachment bindings or command buffers associated with the frame buffer.

See also
~IFrameBuffer

◆ resized

Event<ResizeEventArgs> LiteFX::Rendering::IFrameBuffer::resized
mutable

Invoked when the frame buffer gets resized.

See also
resize