Base interface for a ray tracing acceleration structure.
More...
#include <rendering_api.hpp>
Inherits LiteFX::Rendering::IStateResource.
Inherited by LiteFX::Rendering::Backends::IDirectX12AccelerationStructure [virtual], LiteFX::Rendering::Backends::IVulkanAccelerationStructure [virtual], LiteFX::Rendering::IBottomLevelAccelerationStructure [virtual], and LiteFX::Rendering::ITopLevelAccelerationStructure [virtual].
◆ IAccelerationStructure() [1/3]
| LiteFX::Rendering::IAccelerationStructure::IAccelerationStructure |
( |
| ) |
|
|
protecteddefaultnoexcept |
◆ IAccelerationStructure() [2/3]
◆ IAccelerationStructure() [3/3]
◆ ~IAccelerationStructure()
| LiteFX::Rendering::IAccelerationStructure::~IAccelerationStructure |
( |
| ) |
|
|
overridedefaultnoexcept |
◆ buffer()
| SharedPtr< const IBuffer > LiteFX::Rendering::IAccelerationStructure::buffer |
( |
| ) |
const |
|
inlinenoexcept |
Returns the acceleration structure backing buffer, that stores its last build.
- Returns
- The acceleration structure backing buffer, that stores its last build.
- See also
- offset, size
◆ build()
Performs a complete build of the acceleration structure.
This method builds or rebuilds the entire acceleration structure. If called without any further arguments beside commandBuffer , a new buffer and scratch buffer will be allocated from the IGraphicsDevice that created the command buffer. Alternatively, it is possible to provide a pre-allocated buffer in the buffer parameter. This allows to re-use memory from another acceleration structure, that no longer uses the memory. It is possible to store the buffer from an acceleration structure (acquired by calling buffer) and destroy it afterwards, which enables re-use scenarios for example for caching. Alternatively, it is possible store multiple acceleration structures within the same buffer, reducing overall memory consumption. This is done by also providing the offset and maxSize parameters to address a range within the buffer itself, the acceleration structure may be written into. Note that the pointer passed to the buffer parameter must have been initialized with the BufferType::AccelerationStructure buffer type and must be writable (ResourceUsage::AllowWrite).
By providing a scratchBuffer, it is possible to re-use temporary memory while building. This can lower memory consumption when building multiple acceleration structures. However, this also requires proper barriers to be executed between two build commands, as they are not allowed to access the same scratch memory simultaneously. Note that the pointer passed to the scratchBuffer parameter must have been initialized on the ResourceHeap::Resource heap and must be writable (ResourceUsage::AllowWrite).
After a successful build, the buffer pointer is stored by the acceleration structure and can be accessed by calling buffer on it.
- Parameters
-
| commandBuffer | The command buffer used to record the acceleration structure build commands. |
| scratchBuffer | The scratch buffer used during the acceleration structure build, or nullptr if a temporary buffer should be created. |
| buffer | The buffer that stores the acceleration structure after building, or nullptr if a new buffer should be created. |
| offset | The offset into buffer at which the acceleration structure should be stored. Must be a multiple of 256. Ignored if buffer is nullptr. |
| maxSize | The maximum available size within buffer at offset . Ignored if buffer is nullptr. |
- Exceptions
-
- See also
- update
◆ flags()
◆ offset()
| virtual UInt64 LiteFX::Rendering::IAccelerationStructure::offset |
( |
| ) |
const |
|
pure virtualnoexcept |
◆ operator=() [1/2]
◆ operator=() [2/2]
◆ size()
| virtual UInt64 LiteFX::Rendering::IAccelerationStructure::size |
( |
| ) |
const |
|
pure virtualnoexcept |
◆ update()
Performs an update on the acceleration structure.
Updating an acceleration structure works similar to performing a build, but may be faster compared to a full re-build. Note that in order to support updates, the acceleration structure must have been created with the <see cref=AccelerationStructureFlags::AllowUpdate" /> flag provided. Note that this flag may cause the acceleration structure build times and memory consumption to increase and may
lower the ray-tracing performance.
If no arguments beside <paramref name="commandBuffer" /> are provided, the acceleration structure may re-use the same backing memory used for building, if the buffer holds enough space to contain it.
Otherwise, a new buffer will be allocated. Alternatively, it is possible to provide a pre-allocated buffer in the <paramref name="buffer" /> parameter. This allows to re-use memory from another
acceleration structure, that no longer uses the memory. It is possible to store the buffer from an acceleration structure (acquired by calling <see cref="buffer" />) and destroy it afterwards, which
enables re-use scenarios for example for caching. Alternatively, it is possible store multiple acceleration structures within the same buffer, reducing overall memory consumption. This is done by also
providing the <paramref name="offset" /> and <paramref name="maxSize" /> parameters to address a range within the buffer itself, the acceleration structure may be written into. Note that the pointer
passed to the <see cref="buffer" /> parameter must have been initialized with the <see cref="BufferType::AccelerationStructure" /> buffer type and must be writable
(<see cref="ResourceUsage::AllowWrite" />).
By providing a <see cref="scratchBuffer" />, it is possible to re-use temporary memory while building. This can lower memory consumption when building multiple acceleration structures. However, this
also requires proper barriers to be executed between two build commands, as they are not allowed to access the same scratch memory simultaneously. Note that the pointer passed to the
<see cref="scratchBuffer" /> parameter must have been initialized on the <see cref="ResourceHeap::Resource" /> heap and must be writable (<see cref="ResourceUsage::AllowWrite" />).
After a successful update, the buffer pointer is stored by the acceleration structure and can be accessed by calling <see cref="buffer" /> on it.
</remarks>
<param name="commandBuffer">The command buffer used to record the acceleration structure build commands.</param>
<param name="scratchBuffer">The scratch buffer used during the acceleration structure build, or <tt>nullptr</tt> if a temporary buffer should be created.</param>
<param name="buffer">The buffer that stores the acceleration structure after updating, or <tt>nullptr</tt> if a new buffer should be created.</param>
<param name="offset">The offset into <paramref name="buffer" /> at which the acceleration structure should be stored. Must be a multiple of 256. Ignored if <paramref name="buffer" /> is <tt>nullptr</tt>.</param>
<param name="maxSize">The maximum available size within <paramref name="buffer" /> at <paramref name="offset" />. Ignored if <paramref name="buffer" /> is <tt>nullptr</tt>.</param>
<exception cref="RuntimeException">Thrown, if the acceleration structure backing buffer is not initialized, indicating the acceleration structure has not yet been built.</exception>
<exception cref="InvalidArgumentException">Thrown, if <paramref name="scratchBuffer" /> is not <tt>nullptr</tt> and does not contain enough scratch memory to build the acceleration structure.</exception>
<exception cref="InvalidArgumentException">Thrown, if <paramref name="offset" /> is not aligned to 256 bytes.</exception>
<exception cref="ArgumentOutOfRangeException">Thrown, if <paramref name="buffer" /> is not <tt>nullptr</tt> and the range provided by <paramref name="offset" /> and <paramref name="maxSize" /> is not fully contained by the buffer.</exception>
<seealso cref="build" />
Public Member Functions inherited from LiteFX::Rendering::IStateResource