Module screen_13::pool

Resource leasing and pooling types.

Screen 13 provides caching for acceleration structure, buffer and image resources which may be leased from configurable pools using their corresponding information structure. Most programs will do fine with a single FifoPool.

Leased resources may be bound directly to a render graph and used in the same manner as regular resources. After rendering has finished, the leased resources will return to the pool for reuse.

Buckets

The provided Pool implementations store resources in buckets, with each implementation offering a different strategy which balances performance (more buckets) with memory efficiency (fewer buckets).

Screen 13’s pools can be grouped into two major categories:

• Single-bucket: FifoPool
• Multi-bucket: LazyPool, HashPool

Examples

Leasing an image:

let mut pool = LazyPool::new(&device);

let info = ImageInfo::image_2d(8, 8, vk::Format::R8G8B8A8_UNORM, vk::ImageUsageFlags::STORAGE);
let my_image = pool.lease(info)?;

assert!(my_image.info.usage.contains(vk::ImageUsageFlags::STORAGE));

When Should You Use Which Pool?

These are fairly high-level break-downs of when each pool should be considered. You may need to investigate each type of pool individually to provide the absolute best fit for your purpose.

Use a FifoPool when:

• Low memory usage is most important
• Automatic bucket management is desired

Use a LazyPool when:

• Resources have different attributes each frame

Use a HashPool when:

• High performance is most important
• Resources have consistent attributes each frame

When Should You Use Resource Aliasing?

Wrapping any pool using AliasPool::new enables resource aliasing, which prevents excess resources from being created even when different parts of your code request new resources.

NOTE: Render graph submission will automatically attempt to re-order submitted passes to reduce contention between individual resources.

NOTE: In cases where multiple aliased resources using identical request information are used in the same render graph pass you must ensure the resources are aliased from different pools. There is currently no tagging or filter which would prevent “ping-pong” rendering of such resources from being the same actual resources; this causes Vulkan validation warnings when reading from and writing to the same images, or whatever your operations may be.

Pros:

• Fewer resources are created overall
• Wrapped pools behave like and retain all functionality of unwrapped pools
• Easy to experiment with and benchmark in your existing code

Cons:

• Non-zero cost: Atomic load and compatibility check per active alias
• May cause GPU stalling if there is not enough work being submitted
• Aliased resources are typed Arc<Lease<T>> and are not guaranteed to be mutable or unique

Modules

• alias
  Pool wrapper which enables memory-efficient resource aliasing.
• fifo
  Pool which leases from a single bucket per resource type.
• hash
  Pool which leases by exactly matching the information before creating new resources.
• lazy
  Pool which leases by looking for compatibile information before creating new resources.

Structs

• Lease
  Holds a leased resource and implements Drop in order to return the resource.
• PoolInfo
  Information used to create a FifoPool, HashPool or LazyPool instance.
• PoolInfoBuilder
  Builder for PoolInfo.

Traits

• Pool
  Allows leasing of resources using driver information structures.