LiteFX::Rendering::IDescriptorSetLayout::allocate¶
Allocates a new descriptor set or returns an instance of an unused descriptor set.
Synopsis¶
Declared in <litefx/rendering_api.hpp>
[[dllimport, dllexport]] UniquePtr<IDescriptorSet> allocate(Span<DescriptorBinding> bindings) const;
Description¶
Allocating a new descriptor set may be an expensive operation. To improve performance, and prevent fragmentation, the descriptor set layout keeps track of created descriptor sets. It does this by never releasing them. Instead, when a DescriptorSet instance gets destroyed, it should call free in order to mark itself (i.e. its handle) as not being used any longer.
Before allocating a new descriptor set from a pool (which may even result in the creation of a new pool, if the existing pools are full), the layout tries to hand out descriptor sets that marked as unused. Descriptor sets are only deleted, if the whole layout instance and therefore the descriptor pools are deleted.
The above does not apply to unbounded descriptor arrays. A unbounded descriptor array is one, for which IDescriptorLayout::descriptors returns -1 (or 0xFFFFFFFF). They must be allocated by specifying the descriptors parameter. This parameter defines the number of descriptors to allocate in the array.
Note that descriptor sets, that contain an unbounded descriptor array must only contain one single descriptor (the one that identifies this array). Such descriptor sets are never cached. Instead, they are released when calling free. It is a good practice to cache such descriptor sets as global descriptor tables once and never release them. They provide more flexibility than regular descriptor arrays, since they may be updated, even after they have been bound to a command buffer or from different threads. However, you must ensure yourself not to overwrite any descriptors that are currently in use. Because unbounded arrays are not cached, freeing and re-allocating such descriptor sets may leave the descriptor heap fragmented, which might cause the allocation to fail, if the heap is full.
Note that providing bindings for descriptors of type DescriptorType::ResourceDescriptorHeap or DescriptorType::SamplerDescriptorHeap here is not supported and will cause an exception to be thrown.
Return Value¶
The instance of the descriptor set.
Parameters¶
| Name | Description |
|---|---|
| bindings | Optional default bindings for descriptors in the descriptor set. |
See Also¶
IDescriptorLayout