LiteFX::Rendering::IBottomLevelAccelerationStructure::copy

Copies the acceleration structure into the acceleration structure provided by destination.

Synopsis

Declared in <litefx/rendering_api.hpp>

[[dllimport, dllexport]] void copy(
    ICommandBuffer const& commandBuffer,
    IBottomLevelAccelerationStructure& destination,
    bool compress = false,
    SharedPtr<IBuffer const> const& buffer = nullptr,
    UInt64 offset = 0,
    bool copyBuildInfo = true) const;

Description

This method copies the acceleration structure into another one, which is especially useful for compression. If called without any arguments besides commandBuffer and destination, the method will create a clone of the current acceleration structure, including any build info (i.e., triangle mesh or bounding box data). If the destination acceleration structure already contains a buffer and the buffer contains enough memory to store the copy, it will be re-used and its contents will be overwritten. Otherwise, a new buffer with enough memory to store the copy will be allocated.

If the compress option is set to true, the copy will be compressed. Note that this is only possible, if the acceleration structure was created with the AccelerationStructureFlags::AllowCompaction flag enabled. Note that compression requires a query for the size of the compressed data, which can only be determined after the acceleration structure was built or updated. This implies that a copy command that is used for compression is not valid on the same command buffer that did also record the build or update commands for it. You have to use a fence to wait for the build to finish before attempting a compression.

It is possible to provide a buffer for the destination acceleration structure to use after copying. This buffer can be set by providing 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 parameter to address where the copy should be stored. 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).

To reduce memory consumption, the build info (i.e., triangle mesh and bounding box data) is not copied to the destination acceleration structure by default. However, this also implies that further updates to it are inconvenient, requiring to manually copy the data in an additional pass. To also include build data in the copy, the copyBuildInfo setting can be set to true.

After a successful copy, the buffer pointer is stored by the acceleration structure destination and can be accessed by calling buffer on it.

Exceptions

Name	Thrown on
InvalidArgumentException	Thrown, if compress is set to true, but the current acceleration structure has not been created with the AccelerationStructureFlags::AllowCompaction flag.
InvalidArgumentException	Thrown, if offset is not aligned to 256 bytes.
ArgumentOutOfRangeException	Thrown, if buffer is not nullptr and does not fully contain the required memory to store the copy, starting at offset.

Parameters

Name	Description
commandBuffer	The command buffer used to record the acceleration structure copy commands.
destination	The acceleration structure to copy the current one into.
compress	If true, the acceleration structure data will be compressed.
buffer	If not nullptr, the destination acceleration structure will be written into the provided buffer. Otherwise a new buffer is allocated, or the existing one is used depending on the available size.
offset	The offset at which to store the copy within buffer. Must be a multiple of 256. Ignored if buffer is nullptr.
copyBuildInfo	If true, the mesh data or bounding box data is copied into the acceleration structure.