vk/mem/

binding.rs

//! Existing-resource allocation and checked binding, following pinned VMA 3.4.0
//! `vmaAllocateMemoryForBuffer`, `vmaAllocateMemoryForImage`, and ordinary binds.
//! See license/vma/MIT.txt. Raw handles reveal no creation usage/tiling; automatic
//! usage policies are rejected and unknown image placement is conservative.
use super::*;

struct Requirements {
	memory: vk::MemoryRequirements,
	dedication: Dedication,
	dedicated_supported: bool,
}

unsafe fn requirements(
	allocator: &Allocator<'_>,
	resource: Resource,
) -> Result<Requirements, AllocError> {
	// SAFETY: caller supplies a live ordinary resource; no disjoint plane is requested.
	unsafe { requirements_with_plane(allocator, resource, None) }
}

unsafe fn requirements_with_plane(
	allocator: &Allocator<'_>,
	resource: Resource,
	plane: Option<vk::ImageAspectFlagBits>,
) -> Result<Requirements, AllocError> {
	let route = allocator.requirements_route(matches!(resource, Resource::Image(_)))?;
	// SAFETY: same live native resource/plane query contract.
	unsafe { query_requirements(allocator.device.as_device(), route, resource, plane) }
}

unsafe fn query_requirements(
	device: &vk::Device,
	route: RequirementsRoute,
	resource: Resource,
	plane: Option<vk::ImageAspectFlagBits>,
) -> Result<Requirements, AllocError> {
	if plane.is_some() && matches!(route, RequirementsRoute::Legacy) {
		return Err(AllocError::UnsupportedCapability(
			"disjoint planes require memory requirements2",
		));
	}
	let plane_info = vk::ImagePlaneMemoryRequirementsInfo {
		plane_aspect: plane.unwrap_or_default(),
		..Default::default()
	};
	let mut dedication = vk::MemoryDedicatedRequirements::new();
	let mut output = vk::MemoryRequirements2 {
		p_next: std::ptr::from_mut(&mut dedication).cast(),
		..Default::default()
	};
	// SAFETY: caller supplies a live ordinary resource from this device; exact
	// route preflights its PFN and both writable output records remain in scope.
	unsafe {
		match resource {
			Resource::Buffer(buffer) => {
				let query = vk::BufferMemoryRequirementsInfo2 {
					buffer,
					..Default::default()
				};
				match route {
					RequirementsRoute::Legacy => {
						output.memory_requirements = device.get_buffer_memory_requirements(buffer)?
					}
					RequirementsRoute::Core => device.get_buffer_memory_requirements2(&query, &mut output)?,
					RequirementsRoute::Khr => {
						device.get_buffer_memory_requirements2_khr(&query, &mut output)?
					}
				}
			}
			Resource::Image(image) => {
				let query = vk::ImageMemoryRequirementsInfo2 {
					p_next: if plane.is_some() {
						std::ptr::from_ref(&plane_info).cast()
					} else {
						std::ptr::null()
					},
					image,
					..Default::default()
				};
				match route {
					RequirementsRoute::Legacy => {
						device.get_image_memory_requirements(image, &mut output.memory_requirements)?
					}
					RequirementsRoute::Core => device.get_image_memory_requirements2(&query, &mut output)?,
					RequirementsRoute::Khr => {
						device.get_image_memory_requirements2_khr(&query, &mut output)?
					}
				}
			}
		}
	}
	if output.memory_requirements.size == 0 || !output.memory_requirements.alignment.is_power_of_two()
	{
		return Err(AllocError::InvalidRequest(
			"invalid native resource requirements",
		));
	}
	Ok(Requirements {
		memory: output.memory_requirements,
		dedication: Dedication::new(&dedication),
		dedicated_supported: !matches!(route, RequirementsRoute::Legacy),
	})
}

/// Plane slot shared by the local association index and the synchronized owner
/// registry: ordinary bindings occupy slot zero and disjoint planes occupy
/// slots one through three, so one resource can own independent plane storage.
pub(in crate::mem) fn plane_slot(plane: Option<vk::ImageAspectFlagBits>) -> usize {
	match plane {
		Some(vk::ImageAspectFlagBits::PLANE_0_BIT) => 1,
		Some(vk::ImageAspectFlagBits::PLANE_1_BIT) => 2,
		Some(vk::ImageAspectFlagBits::PLANE_2_BIT) => 3,
		None => 0,
		_ => unreachable!("canonical binding validates plane aspects"),
	}
}

/// Raw-handle association index mirroring each allocator's `live` resource and
/// pending-binding claims. Values hold the claiming allocation serial per plane
/// slot (zero means unclaimed). An independent allocator indexes its bound
/// resources here; a partitioned child indexes only its own pending bindings
/// because the shared owner registry already covers bound resources.
pub(super) struct Associations<'device> {
	buffers: HostMap<'device, [u64; 4]>,
	images: HostMap<'device, [u64; 4]>,
}

impl<'device> Associations<'device> {
	pub fn new(host: HostMemory<'device>) -> Self {
		Self {
			buffers: HostMap::new(host),
			images: HostMap::new(host),
		}
	}

	fn registry(&self, resource: Resource) -> (&HostMap<'device, [u64; 4]>, u64) {
		match resource {
			Resource::Buffer(buffer) => (&self.buffers, buffer.as_raw()),
			Resource::Image(image) => (&self.images, image.as_raw()),
		}
	}

	fn registry_mut(&mut self, resource: Resource) -> (&mut HostMap<'device, [u64; 4]>, u64) {
		match resource {
			Resource::Buffer(buffer) => (&mut self.buffers, buffer.as_raw()),
			Resource::Image(image) => (&mut self.images, image.as_raw()),
		}
	}

	// Keys with no claimed slot are always removed, so presence is the check.
	pub fn associated(&self, resource: Resource) -> bool {
		let (registry, key) = self.registry(resource);
		registry.get(&key).is_some()
	}

	/// Duplicate rule for a raw binding of `resource` at `plane`: an ordinary
	/// claim rejects every owner, while a plane claim rejects the ordinary slot
	/// and the matching plane slot only.
	pub fn conflicts(&self, resource: Resource, plane: Option<vk::ImageAspectFlagBits>) -> bool {
		let (registry, key) = self.registry(resource);
		let Some(slots) = registry.get(&key) else {
			return false;
		};
		match plane {
			None => true,
			Some(_) => slots[0] != 0 || slots[plane_slot(plane)] != 0,
		}
	}

	pub fn try_reserve_for(&mut self, resource: Resource) -> Result<(), AllocError> {
		let (registry, _) = self.registry_mut(resource);
		registry.try_reserve(1)
	}

	/// Reserve `additional` keys in both registries. The shared index uses this
	/// because up to `domains` uncommitted claims can be outstanding at once.
	pub fn try_reserve(&mut self, additional: usize) -> Result<(), AllocError> {
		self.buffers.try_reserve(additional)?;
		self.images.try_reserve(additional)
	}

	// Capacity for the resource key must already be reserved.
	pub fn record(
		&mut self,
		resource: Resource,
		plane: Option<vk::ImageAspectFlagBits>,
		serial: u64,
	) {
		let (registry, key) = self.registry_mut(resource);
		registry.get_or_insert_reserved_with(key, || [0; 4])[plane_slot(plane)] = serial;
	}

	/// Release the claim owned by `serial`; other serials keep the slot so a
	/// recycled native handle cannot lose a newer association.
	pub fn release(
		&mut self,
		resource: Resource,
		plane: Option<vk::ImageAspectFlagBits>,
		serial: u64,
	) {
		let (registry, key) = self.registry_mut(resource);
		registry.remove_if(&key, |slots| {
			let slot = plane_slot(plane);
			if slots[slot] == serial {
				slots[slot] = 0;
			}
			slots.iter().all(|owner| *owner == 0)
		});
	}
}

pub(super) fn associated(allocator: &Allocator<'_>, resource: Resource) -> bool {
	if let Some(shared) = allocator.parallel_state() {
		let domain = allocator.partition_id;
		if shared.associated(resource, domain) {
			return true;
		}
	}
	allocator.associated.associated(resource)
}

/// Continue a resource transaction after options, mapping PFNs and publication
/// capacity have been admitted. The exclusive owner cannot be reentered by
/// native callbacks, so creation does not invalidate that admission.
///
/// # Safety
/// The resource is live/non-null; the caller has validated these options and
/// reserved publication before effects. Native requirements are still queried
/// and checked here, and association reservation remains fallible before binding.
pub(super) unsafe fn allocate_prepared_resource(
	allocator: &mut Allocator<'_>,
	resource: Resource,
	options: &AllocationCreateInfo,
	preferences: (
		vk::MemoryPropertyFlags,
		vk::MemoryPropertyFlags,
		vk::MemoryPropertyFlags,
	),
	class: ResourceClass,
	device_address: bool,
) -> Result<u64, AllocError> {
	let (required, preferred, avoided) = preferences;
	if allocator.parallel.is_none() {
		// Independent allocators publish bound resources into the local index;
		// partitioned claims publish the shared index instead.
		allocator.associated.try_reserve_for(resource)?;
	}
	let claim = parallel::claim(allocator, resource, None, None)?;
	let imported = options
		.memory_allocate_next
		.and_then(|chain| chain.data.import_info);
	let requirements = if let Some(info) = imported.filter(|info| info.resource.is_some()) {
		if import_resource(info.resource) != Some(resource) {
			return Err(AllocError::WrongResource);
		}
		// The unsafe import constructor admits exact external/resource metadata.
		// In particular, Android image requirements cannot be queried before binding.
		Requirements {
			memory: vk::MemoryRequirements {
				size: info.allocation_size,
				alignment: 1,
				memory_type_bits: info.memory_type_bits,
			},
			dedication: Dedication::Required,
			dedicated_supported: true,
		}
	} else {
		if options
			.memory_allocate_next
			.is_some_and(|chain| chain.data.import_kind.requires_info())
		{
			return Err(AllocError::InvalidRequest(
				"platform resource imports require exact resource metadata",
			));
		}
		// SAFETY: exact live ordinary resource supplied by caller; no platform pre-bind query.
		unsafe { requirements(allocator, resource) }?
	};
	let request = AllocRequest {
		size: requirements.memory.size,
		alignment: requirements
			.memory
			.alignment
			.max(options.min_allocation_alignment),
		memory_type_bits: requirements.memory.memory_type_bits & options.memory_type_bits,
		required_flags: required,
		preferred_flags: preferred,
	};
	let mut dedicated = vk::MemoryDedicatedAllocateInfo::new();
	match resource {
		Resource::Buffer(buffer) => dedicated.buffer = buffer,
		Resource::Image(image) => dedicated.image = image,
	}
	// SAFETY: matching queried requirements, exact supported dedication, and admitted class.
	let serial = unsafe {
		allocate_managed(
			allocator,
			&request,
			StorageOptions {
				chain: &super::super::chain::ChainData::EMPTY,
				dedicated: requirements.dedicated_supported.then_some(&dedicated),
				device_address,
				priority: options.priority,
				within_budget: options.within_budget,
			},
			requirements.dedication,
			options,
			class,
			avoided,
		)
	}?;
	let live = allocator.live.get_mut(&serial).expect("new allocation");
	live.resource = Some(resource);
	live.class = if options.can_alias {
		ResourceClass::Unknown
	} else {
		class
	};
	live.can_alias = options.can_alias;
	if let Some(claim) = claim {
		claim.commit(serial);
	} else {
		allocator.associated.record(resource, None, serial);
	}
	Ok(serial)
}

pub(super) unsafe fn persistent(
	allocator: &mut Allocator<'_>,
	allocation: &Allocation,
	options: &AllocationCreateInfo,
) -> Result<(), AllocError> {
	// SAFETY: unpublished unbound storage; debug mapping/checks retain no user references.
	unsafe { guard::initialize(allocator, allocation) }?;
	if options.persistent_map {
		// SAFETY: caller supplies new host-visible storage with preflighted inverse PFN.
		unsafe { map(allocator, allocation) }?;
		let live = allocator
			.live
			.get_mut(&allocation.serial)
			.expect("new allocation");
		live.map_count = 0;
		live.persistent = true;
	}
	Ok(())
}

unsafe fn allocate_existing(
	allocator: &mut Allocator<'_>,
	resource: Resource,
	options: &AllocationCreateInfo,
) -> Result<Allocation, AllocError> {
	allocator.ensure_open()?;
	if associated(allocator, resource) {
		return Err(AllocError::InvalidRequest(
			"resource already has an allocation",
		));
	}

	if options.usage != super::super::MemoryUsage::Explicit {
		return Err(AllocError::UnsupportedCapability(
			"existing resource usage is unknown; use explicit memory flags",
		));
	}
	let preferences = super::super::policy::preferences(options, false, allocator.integrated)?;
	let class = match resource {
		Resource::Buffer(_) => ResourceClass::Buffer,
		Resource::Image(_) => ResourceClass::UnknownImage,
	};
	let address = matches!(resource, Resource::Buffer(_)) && allocator.buffer_device_address;
	if resource.is_null() {
		return Err(AllocError::InvalidRequest("null resource"));
	}
	request::validate_options(allocator, options, preferences.0)?;
	if options.persistent_map {
		require(allocator.device.fp().map_memory.is_some(), "vkMapMemory")?;
		require(
			allocator.device.fp().unmap_memory.is_some(),
			"vkUnmapMemory",
		)?;
	}
	allocator.reserve()?;
	// SAFETY: caller guarantees ordinary resource semantics; unknown usage never enables a feature.
	let serial = unsafe {
		allocate_prepared_resource(allocator, resource, options, preferences, class, address)
	}?;
	let mut allocation = allocator.published(serial);
	// SAFETY: unpublished new allocation; no binding or external access exists.
	if let Err(error) = unsafe { persistent(allocator, &allocation, options) } {
		// SAFETY: unbound storage only; the caller's resource remains untouched.
		unsafe { rollback_allocation(allocator, &mut allocation) }
			.expect("preflighted allocation rollback");
		return Err(error);
	}
	Ok(allocation)
}

/// Allocate for a caller-created unbound ordinary buffer without creating, binding or destroying it.
///
/// Queries exact legacy/core/KHR requirements and dedication. Imports carrying
/// resource-specific ImportMemoryInfo instead use those admitted external
/// requirements without an otherwise illegal pre-bind native query. Policy must use
/// `MemoryUsage::Explicit`; creation usage is unavailable from the opaque handle.
/// BDA-enabled allocators flag separate buffer storage conservatively, following VMA.
/// Allocation/map failure retains the caller's resource. Release unbound storage
/// with `free`; bind it explicitly with `bind_buffer_memory` when ready.
/// # Errors
/// Rejects null/already-associated resources, unsupported policy, identity/type/
/// limit failures or preserves the native allocation/map/query error.
/// # Safety
/// Buffer must be live, unbound, from this device and remain so until binding or
/// allocation release. Supply ordinary non-sparse,
/// non-capture/replay resource semantics; admitted import chains retain their
/// exact external metadata/handle obligations. Address usage requires enabled core/KHR
/// BDA metadata. Protected storage requires enabled features and explicit flags.
/// The caller owns resource lifetime, callbacks and synchronization.
pub unsafe fn allocate_for_buffer(
	allocator: &mut Allocator<'_>,
	buffer: vk::Buffer,
	options: &AllocationCreateInfo,
) -> Result<Allocation, AllocError> {
	// SAFETY: identical native resource/ownership contract.
	unsafe { allocate_existing(allocator, Resource::Buffer(buffer), options) }
}

/// Allocate for a caller-created unbound ordinary image; no creation, binding or destruction.
///
/// Unknown tiling conflicts with every native class, including another unknown
/// image, on a granularity page. Explicit memory flags are required. Native
/// requirements/dedication, pool limits, persistent mapping and rollback share
/// the managed-resource implementation. Resource-specific import metadata
/// replaces pre-bind queries where native external-memory rules forbid them. Failure retains the caller's handle.
/// # Errors
/// Same checked policy, identity/type/limit and native errors as `allocate_for_buffer`.
/// # Safety
/// Image must be live, unbound and from this device. Sparse, disjoint, DRM-modifier,
/// implicit aliasing and unsupported allocation capabilities are excluded. Ordinary
/// external allocation profiles retain caller-owned native compatibility obligations.
/// Protected storage requires captured enablement and explicit required flags.
/// The caller owns resource lifetime, callbacks, valid usage and synchronization.
pub unsafe fn allocate_for_image(
	allocator: &mut Allocator<'_>,
	image: vk::Image,
	options: &AllocationCreateInfo,
) -> Result<Allocation, AllocError> {
	// SAFETY: identical native resource/ownership contract.
	unsafe { allocate_existing(allocator, Resource::Image(image), options) }
}

struct BindChain {
	status: Option<*mut vk::Result>,
	plane: Option<vk::ImageAspectFlagBits>,
}

#[inline]
unsafe fn binding_status(next: *const std::ffi::c_void) -> Result<BindChain, AllocError> {
	if next.is_null() {
		return Ok(BindChain {
			status: None,
			plane: None,
		});
	}
	// SAFETY: caller supplies the same complete readable/writable chain records.
	unsafe { nonempty_binding_status(next) }
}

#[inline(never)]
unsafe fn nonempty_binding_status(
	mut next: *const std::ffi::c_void,
) -> Result<BindChain, AllocError> {
	let mut seen = [std::ptr::null(); 64];
	let mut count = 0;
	let mut status = None;
	let mut plane = None;
	let mut tags = [vk::StructureType::from_raw(0); 64];
	while !next.is_null() {
		if count == seen.len() || seen[..count].contains(&next) {
			return Err(AllocError::InvalidRequest("cyclic/excessive bind chain"));
		}
		seen[count] = next;
		// SAFETY: caller supplies readable native headers and correctly tagged complete records.
		let node = unsafe { &*next.cast::<vk::BaseInStructure>() };
		if tags[..count].contains(&node.s_type) {
			return Err(AllocError::InvalidRequest("duplicate bind chain record"));
		}
		tags[count] = node.s_type;
		count += 1;
		if node.s_type == vk::StructureType::BIND_IMAGE_PLANE_MEMORY_INFO {
			// SAFETY: caller supplies a complete correctly tagged native record.
			let aspect = unsafe { (*next.cast::<vk::BindImagePlaneMemoryInfo>()).plane_aspect };
			use crate::ImageAspectFlagBits as A;
			if !matches!(aspect, A::PLANE_0_BIT | A::PLANE_1_BIT | A::PLANE_2_BIT) {
				return Err(AllocError::UnsupportedCapability(
					"ordinary disjoint image plane aspect required",
				));
			}
			plane = Some(aspect);
		}
		if node.s_type == vk::StructureType::BIND_MEMORY_STATUS {
			// SAFETY: caller supplies the complete native status record matching the tag.
			let pointer = unsafe { (*next.cast::<vk::BindMemoryStatus>()).p_result };
			if status.is_some() || pointer.is_null() {
				return Err(AllocError::InvalidRequest(
					"duplicate/null bind status output",
				));
			}
			status = Some(pointer);
		}
		next = node.p_next.cast();
	}
	Ok(BindChain { status, plane })
}

/// Bind one ordinary buffer with a checked allocation-local offset and borrowed native chain.
///
/// Uses exact core 1.1 or enabled KHR bind_memory2. Associated resource allocations
/// require offset zero; raw allocations re-query type/size/alignment. Any supplied
/// per-bind status must report success before bound state is published.
/// # Errors
/// Reports state/range/capability, malformed chain, per-item status or native errors.
/// # Safety
/// Buffer must be live, ordinary and unbound on this device. Chain records and
/// outputs must be valid and enabled for this exact native call; caller owns their
/// extents/lifetimes and native error/device-loss recovery. No aliasing is admitted.
pub unsafe fn bind_buffer_memory2(
	allocator: &mut Allocator<'_>,
	buffer: vk::Buffer,
	allocation: &Allocation,
	local_offset: u64,
	next: *const std::ffi::c_void,
) -> Result<(), AllocError> {
	// SAFETY: caller establishes canonical native binding/chain guarantees.
	unsafe {
		bind_resource(
			allocator,
			Resource::Buffer(buffer),
			allocation,
			local_offset,
			next,
			true,
			false,
		)
	}
}

/// 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.
/// # Errors
/// Same checked state/range/chain, per-item and native errors as `bind_buffer_memory2`.
/// # Safety
/// Same native chain/lifetime/completion contract as `bind_buffer_memory2`; image
/// semantics must meet native valid usage for the selected plane. Destroy a
/// disjoint image once, then free all its plane allocations; do not use the
/// ordinary paired `destroy_image` helper for a plane allocation.
pub unsafe fn bind_image_memory2(
	allocator: &mut Allocator<'_>,
	image: vk::Image,
	allocation: &Allocation,
	local_offset: u64,
	next: *const std::ffi::c_void,
) -> Result<(), AllocError> {
	// SAFETY: caller establishes canonical native image binding/chain guarantees.
	unsafe {
		bind_resource(
			allocator,
			Resource::Image(image),
			allocation,
			local_offset,
			next,
			true,
			false,
		)
	}
}

pub(super) unsafe fn bind_alias(
	allocator: &mut Allocator<'_>,
	resource: Resource,
	allocation: &Allocation,
	local_offset: u64,
) -> Result<(), AllocError> {
	// SAFETY: caller establishes native alias/resource valid usage; backing storage is explicitly aliasable.
	unsafe {
		bind_resource(
			allocator,
			resource,
			allocation,
			local_offset,
			std::ptr::null(),
			false,
			true,
		)
	}
}

unsafe fn bind_resource(
	allocator: &mut Allocator<'_>,
	resource: Resource,
	allocation: &Allocation,
	local_offset: u64,
	next: *const std::ffi::c_void,
	extended: bool,
	alias: bool,
) -> Result<(), AllocError> {
	// SAFETY: canonical operation checks and borrowed native-chain contract.
	let operation = unsafe {
		prepare_bind(
			allocator,
			resource,
			allocation,
			local_offset,
			next,
			extended,
			alias,
		)
	}?;
	// The exclusive ordinary owner and synchronized backing leases share this
	// exact execution/publication route. No registry guard is needed by execute.
	let backing = allocator.mapping(allocation);
	// SAFETY: caller owns this native resource and meets bind synchronization.
	unsafe { operation.execute(allocator.device.as_device()) }?;
	drop(backing);
	operation.commit(allocator)
}

/// Complete binding for a resource claimed and published by
/// `allocate_prepared_resource` under the same exclusive borrow. Publication
/// already recorded the exact resource association, so identity, claim,
/// reservation and chain stages are not repeated; the backing lease, native
/// call and publication commit keep the canonical operation order. Failure
/// leaves the claim and unpublished allocation to the caller's rollback.
/// SAFETY: `allocation` is the fresh result for this exact `resource`, created
/// unbound within this borrow on a preflighted legacy bind route; the caller
/// owns the native resource and meets bind synchronization.
pub(super) unsafe fn bind_prepared(
	allocator: &mut Allocator<'_>,
	resource: Resource,
	allocation: &Allocation,
) -> Result<(), AllocError> {
	let operation = BindOperation {
		route: RequirementsRoute::Legacy,
		requirements_route: None,
		resource,
		serial: allocation.serial,
		handle: allocation.handle,
		native_offset: allocation.offset,
		remaining_size: allocation.size,
		memory_type_index: allocation.memory_type_index,
		next: std::ptr::null(),
		status: None,
		plane: None,
		alias: false,
		claim: None,
	};
	let backing = allocator.mapping(allocation);
	// SAFETY: identical exclusive execution/publication route as `bind_resource`.
	unsafe { operation.execute(allocator.device.as_device()) }?;
	drop(backing);
	operation.commit(allocator)
}

pub(super) struct BindOperation<'device> {
	route: RequirementsRoute,
	requirements_route: Option<RequirementsRoute>,
	resource: Resource,
	serial: u64,
	handle: vk::DeviceMemory,
	native_offset: u64,
	remaining_size: u64,
	memory_type_index: u32,
	next: *const std::ffi::c_void,
	status: Option<*mut vk::Result>,
	pub(super) plane: Option<vk::ImageAspectFlagBits>,
	alias: bool,
	claim: Option<parallel::resource::Claim<'device>>,
}

pub(super) unsafe fn prepare_bind<'device>(
	allocator: &mut Allocator<'device>,
	resource: Resource,
	allocation: &Allocation,
	local_offset: u64,
	next: *const std::ffi::c_void,
	extended: bool,
	alias: bool,
) -> Result<BindOperation<'device>, AllocError> {
	let route = if !extended {
		RequirementsRoute::Legacy
	} else {
		let capabilities =
			allocator
				.device
				.as_device()
				.capabilities()
				.ok_or(AllocError::UnsupportedCapability(
					"extended binding requires creation metadata",
				))?;
		if capabilities.api_version() >= vk::API_VERSION_1_1 {
			RequirementsRoute::Core
		} else if super::super::resource::extension(
			allocator.device.as_device(),
			c"VK_KHR_bind_memory2",
		) {
			RequirementsRoute::Khr
		} else {
			return Err(AllocError::UnsupportedCapability(
				"bind_memory2 is not enabled",
			));
		}
	};
	// SAFETY: caller supplies valid readable/writable native bind-chain records for this call.
	let BindChain { status, plane } = unsafe { binding_status(next) }?;
	let live = allocator.validate(allocation)?;
	if live.native_users != 0 {
		return Err(AllocError::InvalidRequest("native operation in progress"));
	}
	if plane.is_some() {
		if !extended || !matches!(resource, Resource::Image(_)) || live.resource.is_some() || alias {
			return Err(AllocError::InvalidRequest(
				"plane binding requires unassociated raw storage and image bind2",
			));
		}
		if !allocator
			.device
			.as_device()
			.capabilities()
			.is_some_and(|caps| caps.api_version() >= vk::API_VERSION_1_1)
			&& !super::super::resource::extension(
				allocator.device.as_device(),
				c"VK_KHR_sampler_ycbcr_conversion",
			) {
			return Err(AllocError::UnsupportedCapability(
				"disjoint plane binding is not enabled",
			));
		}
	}
	if resource.is_null() {
		return Err(AllocError::InvalidRequest("null resource"));
	}
	if alias && !live.can_alias {
		return Err(AllocError::UnsupportedCapability(
			"allocation was not created for aliasing",
		));
	}
	if !alias && live.bound {
		return Err(AllocError::InvalidRequest("allocation already bound"));
	}
	if !alias && live.resource.is_some_and(|target| target != resource) {
		return Err(AllocError::WrongResource);
	}
	let raw = alias || live.resource.is_none();
	// Snapshot authoritative live metadata once. Binding needs neither a public
	// token reconstruction nor a scan for its block size/host mapping properties.
	let (handle, offset, size, memory_type_index) =
		(live.handle, live.offset, live.size, live.memory_type_index);
	// Partitioned children cover bound resources through the shared owner claim
	// below; the local index always covers this allocator's own pending binds.
	if raw && allocator.associated.conflicts(resource, plane) {
		return Err(AllocError::WrongResource);
	}
	allocator.associated.try_reserve_for(resource)?;
	let claim = parallel::claim(
		allocator,
		resource,
		plane,
		(!raw).then_some(allocation.serial),
	)?;
	let fp = allocator.device.fp();
	match (resource, route) {
		(Resource::Buffer(_), RequirementsRoute::Legacy) => {
			require(fp.bind_buffer_memory.is_some(), "vkBindBufferMemory")?
		}
		(Resource::Image(_), RequirementsRoute::Legacy) => {
			require(fp.bind_image_memory.is_some(), "vkBindImageMemory")?
		}
		(Resource::Buffer(_), RequirementsRoute::Core) => {
			require(fp.bind_buffer_memory2.is_some(), "vkBindBufferMemory2")?
		}
		(Resource::Image(_), RequirementsRoute::Core) => {
			require(fp.bind_image_memory2.is_some(), "vkBindImageMemory2")?
		}
		(Resource::Buffer(_), RequirementsRoute::Khr) => require(
			fp.bind_buffer_memory2_khr.is_some(),
			"vkBindBufferMemory2KHR",
		)?,
		(Resource::Image(_), RequirementsRoute::Khr) => {
			require(fp.bind_image_memory2_khr.is_some(), "vkBindImageMemory2KHR")?
		}
	}
	let native_offset = offset
		.checked_add(local_offset)
		.ok_or(AllocError::InvalidRange)?;
	if local_offset > size || (!raw && local_offset != 0) {
		return Err(AllocError::InvalidRange);
	}
	let requirements_route = if raw {
		Some(allocator.requirements_route(matches!(resource, Resource::Image(_)))?)
	} else {
		None
	};
	Ok(BindOperation {
		route,
		requirements_route,
		resource,
		serial: allocation.serial,
		handle,
		native_offset,
		remaining_size: size - local_offset,
		memory_type_index,
		next,
		status,
		plane,
		alias,
		claim,
	})
}

impl BindOperation<'_> {
	pub(super) unsafe fn execute(&self, device: &vk::Device) -> Result<(), AllocError> {
		let (route, resource, handle, native_offset, next, status, plane) = (
			self.route,
			self.resource,
			self.handle,
			self.native_offset,
			self.next,
			self.status,
			self.plane,
		);

		if let Some(requirements_route) = self.requirements_route {
			// SAFETY: caller guarantees the live ordinary resource and native identity.
			let requirements =
				unsafe { query_requirements(device, requirements_route, resource, plane) }?;
			if requirements.dedication == Dedication::Required {
				return Err(AllocError::UnsupportedCapability(
					"raw allocation cannot satisfy required resource dedication",
				));
			}
			if requirements.memory.memory_type_bits & (1 << self.memory_type_index) == 0 {
				return Err(AllocError::NoCompatibleMemoryType);
			}
			if requirements.memory.size > self.remaining_size
				|| !native_offset.is_multiple_of(requirements.memory.alignment)
			{
				return Err(AllocError::InvalidRange);
			}
		}
		if let Some(status) = status {
			// SAFETY: validated writable output pointer from caller-owned live bind chain.
			unsafe {
				*status = vk::Result::NOT_READY;
			}
		}
		// SAFETY: one matching ordinary resource, checked storage offset/extent, admitted exact PFN and live caller chain.
		unsafe {
			match resource {
				Resource::Buffer(buffer) => {
					let info = vk::BindBufferMemoryInfo {
						buffer,
						memory: handle,
						memory_offset: native_offset,
						p_next: next,
						..Default::default()
					};
					match route {
						RequirementsRoute::Legacy => {
							device.bind_buffer_memory(buffer, handle, native_offset)?
						}
						RequirementsRoute::Core => device.bind_buffer_memory2(&[info])?,
						RequirementsRoute::Khr => device.bind_buffer_memory2_khr(&[info])?,
					}
				}
				Resource::Image(image) => {
					let info = vk::BindImageMemoryInfo {
						image,
						memory: handle,
						memory_offset: native_offset,
						p_next: next,
						..Default::default()
					};
					match route {
						RequirementsRoute::Legacy => device.bind_image_memory(image, handle, native_offset)?,
						RequirementsRoute::Core => device.bind_image_memory2(&[info])?,
						RequirementsRoute::Khr => device.bind_image_memory2_khr(&[info])?,
					}
				}
			}
		}
		if let Some(status) = status {
			// SAFETY: caller-owned status storage remains live after the synchronous native call.
			let result = unsafe { *status };
			if result != vk::Result::SUCCESS {
				return Err(
					if result.as_raw() < 0 {
						CallError::Vulkan(result)
					} else {
						CallError::InvalidOutput("native binding did not publish success status")
					}
					.into(),
				);
			}
		}
		Ok(())
	}

	pub(super) fn commit(self, allocator: &mut Allocator<'_>) -> Result<(), AllocError> {
		if self.alias {
			return Ok(());
		}
		let live = allocator
			.live
			.get_mut(&self.serial)
			.expect("validated allocation");
		let already_associated = live.resource == Some(self.resource) && live.plane == self.plane;
		live.resource = Some(self.resource);
		live.plane = self.plane;
		live.bound = true;
		if let Some(claim) = self.claim {
			claim.commit(self.serial);
		} else if !already_associated {
			allocator
				.associated
				.record(self.resource, self.plane, self.serial);
		}
		Ok(())
	}
}

/// Bind at the allocation's actual native offset. Failed binds retain allocation and resource for retry.
///
/// Allocations for a resource accept only that target. Raw allocations
/// query size/type/alignment and reject required dedication. Repeated library
/// binding and aliasing are rejected. No pointer lookup or resource destruction occurs.
/// # Errors
/// Returns identity/state/association, requirement/type/range or native bind errors.
/// # Safety
/// Buffer must be live, unbound, ordinary and from this device. Meet allocation/
/// feature/lifetime and external host synchronization valid usage. Native calls
/// performed outside this allocator remain caller-owned state; do not rebind them.
pub unsafe fn bind_buffer_memory(
	allocator: &mut Allocator<'_>,
	buffer: vk::Buffer,
	allocation: &Allocation,
) -> Result<(), AllocError> {
	// SAFETY: identical native binding contract.
	unsafe {
		bind_resource(
			allocator,
			Resource::Buffer(buffer),
			allocation,
			0,
			std::ptr::null(),
			false,
			false,
		)
	}
}

/// Bind a live ordinary image at its allocation's native offset; failure retains both objects.
/// # Errors
/// Same checked identity/association/requirement/type/range and native errors as buffer binding.
/// # Safety
/// Image must be live, unbound, non-disjoint/non-sparse/non-external,
/// non-aliased and from this device. Meet native feature and synchronization valid
/// usage. Never infer linear pixel layout from mapping optimal/unknown image storage.
pub unsafe fn bind_image_memory(
	allocator: &mut Allocator<'_>,
	image: vk::Image,
	allocation: &Allocation,
) -> Result<(), AllocError> {
	// SAFETY: identical native binding contract.
	unsafe {
		bind_resource(
			allocator,
			Resource::Image(image),
			allocation,
			0,
			std::ptr::null(),
			false,
			false,
		)
	}
}

impl Allocator<'_> {
	/// Bind an ordinary buffer with explicit local offset and borrowed native bind chain.
	/// # Safety
	/// Same native chain/resource contract as `mem::bind_buffer_memory2`.
	pub unsafe fn bind_buffer_memory2(
		&mut self,
		buffer: vk::Buffer,
		allocation: &Allocation,
		local_offset: u64,
		next: *const std::ffi::c_void,
	) -> Result<(), AllocError> {
		// SAFETY: caller supplies canonical binding/chain guarantees.
		unsafe { bind_buffer_memory2(self, buffer, allocation, local_offset, next) }
	}

	/// Bind an ordinary image with explicit local offset and borrowed native bind chain.
	/// # Safety
	/// Same native chain/resource contract as `mem::bind_image_memory2`.
	pub unsafe fn bind_image_memory2(
		&mut self,
		image: vk::Image,
		allocation: &Allocation,
		local_offset: u64,
		next: *const std::ffi::c_void,
	) -> Result<(), AllocError> {
		// SAFETY: caller supplies canonical image binding/chain guarantees.
		unsafe { bind_image_memory2(self, image, allocation, local_offset, next) }
	}
	/// Allocate for an existing unbound ordinary buffer; retains caller ownership on error.
	/// # Safety
	/// Same resource/feature/callback/lifetime contract as `mem::allocate_for_buffer`.
	pub unsafe fn allocate_for_buffer(
		&mut self,
		buffer: vk::Buffer,
		options: &AllocationCreateInfo,
	) -> Result<Allocation, AllocError> {
		// SAFETY: identical native contract to the canonical operation.
		unsafe { allocate_for_buffer(self, buffer, options) }
	}

	/// Allocate for an existing ordinary image using conservative unknown-tiling placement.
	/// # Safety
	/// Same resource/feature/callback/lifetime contract as `mem::allocate_for_image`.
	pub unsafe fn allocate_for_image(
		&mut self,
		image: vk::Image,
		options: &AllocationCreateInfo,
	) -> Result<Allocation, AllocError> {
		// SAFETY: identical native contract to the canonical operation.
		unsafe { allocate_for_image(self, image, options) }
	}

	/// Bind a matching buffer/allocation pair; failure retains both for explicit retry.
	/// # Safety
	/// Same native unbound-resource and synchronization contract as `mem::bind_buffer_memory`.
	pub unsafe fn bind_buffer_memory(
		&mut self,
		buffer: vk::Buffer,
		allocation: &Allocation,
	) -> Result<(), AllocError> {
		// SAFETY: identical native contract to the canonical operation.
		unsafe { bind_buffer_memory(self, buffer, allocation) }
	}

	/// Bind a matching ordinary image/allocation pair; no implicit destruction on failure.
	/// # Safety
	/// Same native image/lifetime/synchronization contract as `mem::bind_image_memory`.
	pub unsafe fn bind_image_memory(
		&mut self,
		image: vk::Image,
		allocation: &Allocation,
	) -> Result<(), AllocError> {
		// SAFETY: identical native contract to the canonical operation.
		unsafe { bind_image_memory(self, image, allocation) }
	}
}

#[cfg(test)]
#[path = "../../../test/rs/mem/test_associated.rs"]
mod tests;