Expand description
Rust-native, VMA-derived allocation, managed buffers/images and virtual placement.
Free functions and Allocator methods share one implementation. For example,
create_buffer_with_options and Allocator::create_buffer_with_options
create, allocate and bind a managed buffer. The root crate::create_buffer
is the raw Vulkan operation and creates an unbound buffer.
Use use vk::mem as vma; for a caller-local alias. This adds no wrapper,
runtime cost or second allocator type; crate::Allocator is Allocator.
Full VMA equivalence, broad concurrent stress, multi-driver execution and
additional platforms remain
unqualified. See the qualification report.
Every public field on a plain record has a consuming set_*() method alongside
direct field access. Default-backed records support new().set_*();
AllocRequest, ImportMemoryInfo and CacheRange take required inputs
in new. Setters retain borrows and leave validation to the using operation.
Editing a diagnostic snapshot changes only that record, never live allocator
state. Resource identities and owners retain their checked operation APIs.
Allocator operations do not submit or wait. GPU completion, resource destruction and host/GPU access ordering remain caller responsibilities.
Re-exports§
pub use virtual_block::PlacementStrategy;pub use virtual_block::VirtualAllocation;pub use virtual_block::VirtualAllocationInfo;pub use virtual_block::VirtualBlock;pub use virtual_block::VirtualBlockDetails;pub use virtual_block::VirtualBlockStats;
Modules§
- virtual_
block - Host-only region placement over an integer byte range.
Structs§
- Alloc
Request - Allocation
- One live native region. No implicit free, unmap, submission or wait in Drop.
- Allocation
Chain - A caller-owned
VkMemoryAllocateInfo::pNextchain. - Allocation
Create Info - Managed-resource policy, including optional borrowed native allocation storage; this Rust record is not part of the Vulkan ABI.
- Allocation
Info - Checked binding and mapping snapshot of one live allocation.
- Allocator
- Borrows one device; native memory is released only by explicit operations.
- Allocator
Info - Captured native identities. Manual metadata constructors do not invent parent identities.
- Allocator
Stats - Local accounting snapshot; excludes allocations made by other allocators/raw calls.
- Budget
Snapshot - Cache
Range - One allocation-relative cache range. Each allocation must own a mapping hold.
- Debug
Memory Settings - Opt-in host-visible debug instrumentation, configured before native acquisition. Guard margins follow VMA’s coherent pooled-memory policy. Zero disables guards.
- Defragmentation
Context - Persistent multi-pass relocation state with one exclusive allocator borrow.
Ignored allocations stay immovable for subsequent passes in this context.
Each pass must be explicitly resolved and finished; neither context nor pass
Drop submits, waits or destroys native resources. An abandoned unresolved pass
leaks its reservations, as documented by
DefragmentationPass. - Defragmentation
Info - Bounded relocation planning. Zero limits produce an empty pass.
- Defragmentation
Move - Borrow-free binding snapshots. They do not retain resources or mappings. Mapped pointers describe counted holds owned by the pass’s live regions. Source pointers expire on commit/destroy, destination pointers on ignore/destroy; copied snapshots extend no lifetime.
- Defragmentation
Pass - Exclusively borrows the allocator while replacement resources are prepared.
- Defragmentation
Stats - Actual completed work; proposed or ignored moves are not counted as moved bytes.
- Detailed
Statistics - Detailed local byte/count statistics. Empty populations have None extrema.
- Device
Memory Callbacks - Informative notifications for actual native memory allocation/free effects. Callbacks do not allocate Rust metadata and do not own the native memory.
- Heap
Budget - One heap at the explicit snapshot boundary. Budget/usage can change immediately.
- Import
Memory Info - Actual external backing extent and compatible types for one import.
- Memory
Priority - Finite native memory priority in the inclusive range 0..=1.
- Memory
Statistics - Explicit diagnostic snapshot, indexed by native memory type and heap.
- Memory
Type Selector - Validated device memory properties and non-coherent atom size.
- Pool
- Identity of one live custom pool. Dropping it never destroys native storage.
- Pool
Create Info - Fixed-type ordinary-memory pool; not a Vulkan ABI record.
- Pool
Stats - Local pool statistics. No native budget query or host allocation is performed. Free spans describe physical holes; alignment/granularity may prevent their use. Linear holes additionally wait for their stack/ring lifetime to retire. Counts/bytes include pool-owned dedicated allocations and retained empty blocks.
- Synchronized
Allocator - One allocator with synchronized direct operations and concurrent pool scopes.
- Synchronized
Virtual Block - One virtual block with serialized operation access from any host thread.
- Trim
Stats - Native cache released by one explicit maintenance call. Live regions never move.
Enums§
- Alloc
Error - Allocation
Algorithm - Placement metadata for custom pools and host-only virtual blocks.
- Allocation
Policy - Managed resource storage policy. Required or preferred native dedication takes precedence.
- Budget
Source - Budget provenance. Heap-size/local accounting does not measure external pressure.
- Defragmentation
Algorithm - Existing-block relocation policy, derived from the pinned VMA algorithms.
- Defragmentation
Resource - Allocator-recorded primary resource, or raw storage, associated with a move.
- Host
Access - CPU access intent used by automatic memory selection; never submits a transfer.
- Import
Resource - Resource-specific native dedication for an imported payload. The resource remains caller-owned; this record never destroys it.
- Memory
Usage - Policy for managed resources. Raw allocation always uses explicit flags.
Functions§
- allocate⚠
- Allocate separate native storage with automatically admitted allocation flags.
- allocate_
dedicated ⚠ - Allocate separate native storage with an optional borrowed allocation chain.
Equivalent to
allocate_with_optionswithdedicated_memoryenabled. - allocate_
for_ ⚠buffer - Allocate for a caller-created unbound ordinary buffer without creating, binding or destroying it.
- allocate_
for_ ⚠image - Allocate for a caller-created unbound ordinary image; no creation, binding or destruction.
- allocate_
many ⚠ - Allocate identical ordinary requirement pages; failure releases new pages only.
- allocate_
with_ ⚠options - Allocate unbound ordinary storage from native requirements with explicit policy.
- allocation_
info - Snapshot one live allocation’s binding, actual properties and current mapping.
- allocation_
name - Borrow an allocation’s diagnostic name; no native lifetime is acquired.
- allocator_
info - Observe captured native identities without inferring manually omitted parent metadata.
- begin_
defragmentation ⚠ - Reserve earlier free storage without creating native resources, growing blocks or copying data.
- begin_
defragmentation_ ⚠with_ break - Plan a pass with a borrowed cooperative stop predicate, following VMA’s
pfnBreakCallback/CheckCounterscontract. Returning true stops scheduling; already proposed moves still need explicit resolution. Usewas_interruptedto distinguish a stop from an exhausted search. Polls occur between source candidates, after host snapshot/preflight, and never during consumer copies. A panic rolls back unpublished destinations before unwinding (with panic=unwind). The callback is used only during this call and cannot borrow this allocator. - bind_
buffer_ ⚠memory - Bind at the allocation’s actual native offset. Failed binds retain allocation and resource for retry.
- bind_
buffer_ ⚠memory2 - Bind one ordinary buffer with a checked allocation-local offset and borrowed native chain.
- bind_
image_ ⚠memory - Bind a live ordinary image at its allocation’s native offset; failure retains both objects.
- bind_
image_ ⚠memory2 - Bind an ordinary image or one disjoint plane with an allocation-local offset and native chain. A plane uses unassociated raw storage allocated from caller-queried plane requirements. The allocator re-queries that exact plane before binding and tracks each plane independently; DRM modifier plane aspects remain excluded.
- budget_
snapshot - Local accounting is always distinguished from implementation-reported usage.
- check_
corruption ⚠ - Check enabled coherent pooled guard tails without waiting for GPU work.
- check_
pool_ ⚠corruption - Check coherent guard tails belonging to one checked custom pool.
- close
- Checked shutdown after all regions and their blocks have been explicitly released.
- copy_
from_ ⚠allocation - Invalidate and copy allocation bytes to initialized writable host storage.
- copy_
to_ ⚠allocation - Copy host bytes to an allocation, flush them and release only this helper’s map hold.
- create_
aliasing_ ⚠buffer - Create an ordinary alias buffer at a checked allocation-local offset.
- create_
aliasing_ ⚠image - Create a caller-owned ordinary alias image without allocating new native memory.
- create_
buffer ⚠ - Transactionally create, query, allocate and bind an ordinary buffer.
- create_
buffer_ ⚠with_ options - Create, allocate, optionally map and bind an ordinary buffer transactionally.
- create_
dedicated_ ⚠buffer - Create, separately allocate and bind a buffer, optionally importing/exporting memory.
- create_
dedicated_ ⚠image - Create, separately allocate and bind an ordinary non-disjoint image with an optional chain.
- create_
image ⚠ - Create an ordinary image with separate storage and explicit memory properties.
- create_
image_ ⚠with_ options - Create, query, allocate, optionally map and bind a non-disjoint image transactionally.
- create_
pool ⚠ - Create a fixed-memory-type TLSF pool transactionally.
- create_
pool_ ⚠with_ chain - Create a pool retaining a borrowed native allocation chain for every block. Import chains are rejected: a single imported payload cannot back repeated growth.
- destroy_
buffer ⚠ - Destroy a matching resource pair in buffer-before-memory order with matching retained callbacks.
- destroy_
image ⚠ - Destroy the exact image/token pair with matching retained callbacks before freeing memory.
- destroy_
pool - Destroy an empty pool, releasing its retained native blocks explicitly.
- detailed_
pool_ statistics - Walk actual blocks/live regions belonging to one checked custom pool.
- detailed_
statistics - Walk actual native blocks and live regions to build detailed local statistics.
- external_
memory_ types - Observe the export flags retained for this allocation’s entire native block.
- find_
memory_ type - Select from explicit native memory-type bits without allocating or querying a budget.
- find_
memory_ ⚠type_ for_ buffer_ info - Select memory for an ordinary buffer using its actual creation usage and requirements.
- find_
memory_ ⚠type_ for_ image_ info - Select memory for an ordinary non-disjoint image from creation usage and native requirements.
- flush⚠
- Flush a bounded allocation-relative mapped range, observing atom/end rules.
- flush_
many ⚠ - Flush checked ranges in one native call; coherent/empty ranges remain checked no-ops.
- free⚠
- Release a separate allocation or pooled placement and invalidate its token.
- free_
many ⚠ - Validate an entire release batch before freeing any allocation.
- get_
memory_ ⚠fd - Export a new caller-owned file descriptor for the complete backing memory. Allocation offsets still apply. Close the returned descriptor using the OS; neither token nor allocator owns it. No GPU synchronization occurs.
- heap_
budgets - Return an owned cached budget, refreshed on frame changes or after 30 region operations.
- invalidate⚠
- Invalidate a bounded allocation-relative mapped range; never waits for the GPU.
- invalidate_
many ⚠ - Invalidate checked ranges in one native call; never waits for device writes.
- map⚠
- Map one allocation. Distinct regions share a reference-counted block mapping. Repeated explicit maps acquire checked holds on the same native mapping.
- mapped_
pointer - Return a region pointer only if that region has an explicit or persistent hold. Does not map, acquire a hold, synchronize, or authorize pointer dereferences.
- memory_
properties - Borrow validated native memory metadata used by this allocator’s selection policy.
- memory_
type_ properties - Observe one checked native memory type’s actual property flags.
- physical_
device_ properties - Borrow queried physical-device properties, or None after manual metadata construction.
- pool_
name - Borrow a custom pool’s copied diagnostic name without native effects.
- pool_
statistics - Query a pool’s local native bytes, placements and free ranges.
- query_
budget ⚠ - Return an explicit native budget snapshot without caching admission decisions.
- refresh_
budget - Refresh an allocator-owned budget snapshot from the retained native context.
- refresh_
budget_ ⚠with_ context - Capture a checked budget context for future refreshes, including manual constructors.
- set_
allocation_ name - Replace a copied UTF-8 diagnostic name transactionally; None clears it.
- set_
allocation_ pinned - Explicitly pin/unpin a region against future allocator relocation planning.
- set_
allocation_ user_ data - Set uninterpreted consumer metadata. It is never dereferenced, freed or owned.
- set_
current_ frame_ index - Mark a frame boundary for budget refresh; this never retires resources or waits.
- set_
debug_ memory_ settings - Configure debug instrumentation before native allocations or pools exist.
- set_
external_ ⚠memory_ types - Configure copied per-memory-type external export flags before creating pools/storage.
Zero flags leave that type ordinary. Every native allocation of a configured
type receives
VkExportMemoryAllocateInfo, including separate allocations. - set_
heap_ limit - Change a local policy ceiling; this never reserves native heap capacity.
- set_
mapping_ hysteresis - Configure native pooled mapping retention before creating storage or pools. Enabled by default. Separate allocations never cache mappings. This affects native map/unmap call counts, never allocation-level pointer access rights.
- set_
pool_ name - Replace a pool diagnostic name; metadata allocation failure preserves its old name.
- set_
preferred_ block_ size - Set preferred block bytes for heaps larger than 1 GiB before pool/storage creation.
Small heaps use one eighth of their heap size; both paths round up to 32 bytes.
Does not alter explicit
Pooled/Adaptivepolicies or query/reserve a budget. - statistics
- Calculate local live-region/native-block accounting without querying the driver.
- trim
- Release surplus empty, unmapped cached blocks, preserving each pool minimum.
- trim_
with_ ⚠budget - Query an explicit budget snapshot, then trim surplus empty blocks on pressured heaps.
- unmap⚠
- Release one explicit map; persistent holds and other regions remain mapped.
- write_
statistics_ json - Write ordered local allocator diagnostics as
vk.memory.statistics.v1JSON.