Skip to main content

Module pool

vk_graph

Module pool 

Source
Expand description

Resource pooling, requesting, and caching types.

Resource pools provide caching for buffer, image, and acceleration structure resources. Pooled resources may be requested from a pool using their corresponding information structure.

Leased resources may be bound directly to a Graph and used in the same manner as regular resources. After execution has completed pooled resources are automatically returned to their 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).

vk-graph’s pools can be grouped into two major categories:

§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.resource(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 Caching?

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

NOTE: Graph submission will automatically attempt to re-order submitted commands to reduce contention between individual resources.

NOTE: In cases where multiple cached resources using identical request information are used in the same graph command, ensure they come from different cache tags or different pool wrappers. Otherwise, two requests may resolve to the same underlying resource and trigger Vulkan validation warnings when reading from and writing to the same images.

§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 cached resource
  • May cause GPU stalling if there is not enough work being submitted
  • Cached resources are typed Arc<Lease<T>> and are not guaranteed to be mutable or unique

Modules§

cache
Pool wrapper which enables memory-efficient resource caching.
fifo
Pool which requests from a single bucket per resource type.
hash
Pool which requests by exactly matching the information before creating new resources.
lazy
Pool which requests by looking for compatible information before creating new resources.

Structs§

Lease
Holds a pooled resource and implements Drop in order to return the resource.
PoolConfig
Information used to create a FifoPool, HashPool or LazyPool instance.
PoolConfigBuilder
Builder for PoolConfig.

Traits§

Pool
Allows requesting resources using driver information structures.
SubmissionPool
Pool capability required by graph submission scheduling.