From 29fc76e8ab7dd967b5bf1ff05d3f6aa6f54f9724 Mon Sep 17 00:00:00 2001 From: Marijn Suijten Date: Thu, 11 Nov 2021 09:36:21 +0100 Subject: [PATCH] Link _len() functions to their array-getter using intradoc-links Point the user in the right direction telling them where to get the length of the mutable slice that has to passed in, and document that these have to be default-initialized (so that `s_type` is set appropriately) and `p_next` can optionally be set too. --- ash/src/device.rs | 4 ++++ .../khr/get_memory_requirements2.rs | 10 +++++++--- .../khr/get_physical_device_properties2.rs | 20 +++++++++++++------ ash/src/instance.rs | 18 ++++++++++++++--- 4 files changed, 40 insertions(+), 12 deletions(-) diff --git a/ash/src/device.rs b/ash/src/device.rs index e0077ee50..fae9cc62e 100644 --- a/ash/src/device.rs +++ b/ash/src/device.rs @@ -297,6 +297,7 @@ impl Device { .get_buffer_memory_requirements2(self.handle(), info, out); } + /// Retrieve the number of elements to pass to [`Self::get_image_sparse_memory_requirements2()`] pub unsafe fn get_image_sparse_memory_requirements2_len( &self, info: &vk::ImageSparseMemoryRequirementsInfo2, @@ -312,6 +313,9 @@ impl Device { } #[doc = ""] + /// + /// Call [`Self::get_image_sparse_memory_requirements2_len()`] to query the number of elements to pass to `out`. + /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer. pub unsafe fn get_image_sparse_memory_requirements2( &self, info: &vk::ImageSparseMemoryRequirementsInfo2, diff --git a/ash/src/extensions/khr/get_memory_requirements2.rs b/ash/src/extensions/khr/get_memory_requirements2.rs index bdc7bfae0..6cb8f53e3 100644 --- a/ash/src/extensions/khr/get_memory_requirements2.rs +++ b/ash/src/extensions/khr/get_memory_requirements2.rs @@ -45,6 +45,7 @@ impl GetMemoryRequirements2 { .get_image_memory_requirements2_khr(self.handle, info, memory_requirements); } + /// Retrieve the number of elements to pass to [`Self::get_image_sparse_memory_requirements2()`] pub unsafe fn get_image_sparse_memory_requirements2_len( &self, info: &vk::ImageSparseMemoryRequirementsInfo2KHR, @@ -61,18 +62,21 @@ impl GetMemoryRequirements2 { } #[doc = ""] + /// + /// Call [`Self::get_image_sparse_memory_requirements2_len()`] to query the number of elements to pass to `out`. + /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer. pub unsafe fn get_image_sparse_memory_requirements2( &self, info: &vk::ImageSparseMemoryRequirementsInfo2KHR, - sparse_memory_requirements: &mut [vk::SparseImageMemoryRequirements2KHR], + out: &mut [vk::SparseImageMemoryRequirements2KHR], ) { - let mut count = sparse_memory_requirements.len() as u32; + let mut count = out.len() as u32; self.get_memory_requirements2_fn .get_image_sparse_memory_requirements2_khr( self.handle, info, &mut count, - sparse_memory_requirements.as_mut_ptr(), + out.as_mut_ptr(), ); } diff --git a/ash/src/extensions/khr/get_physical_device_properties2.rs b/ash/src/extensions/khr/get_physical_device_properties2.rs index abf23319a..6473b5a88 100644 --- a/ash/src/extensions/khr/get_physical_device_properties2.rs +++ b/ash/src/extensions/khr/get_physical_device_properties2.rs @@ -84,6 +84,7 @@ impl GetPhysicalDeviceProperties2 { .get_physical_device_properties2_khr(physical_device, properties); } + /// Retrieve the number of elements to pass to [`Self::get_physical_device_queue_family_properties2()`] pub unsafe fn get_physical_device_queue_family_properties2_len( &self, physical_device: vk::PhysicalDevice, @@ -99,20 +100,24 @@ impl GetPhysicalDeviceProperties2 { } #[doc = ""] + /// + /// Call [`Self::get_physical_device_queue_family_properties2_len()`] to query the number of elements to pass to `out`. + /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer. pub unsafe fn get_physical_device_queue_family_properties2( &self, physical_device: vk::PhysicalDevice, - queue_family_properties: &mut [vk::QueueFamilyProperties2KHR], + out: &mut [vk::QueueFamilyProperties2KHR], ) { - let mut count = queue_family_properties.len() as u32; + let mut count = out.len() as u32; self.get_physical_device_properties2_fn .get_physical_device_queue_family_properties2_khr( physical_device, &mut count, - queue_family_properties.as_mut_ptr(), + out.as_mut_ptr(), ); } + /// Retrieve the number of elements to pass to [`Self::get_physical_device_sparse_image_format_properties2()`] pub unsafe fn get_physical_device_sparse_image_format_properties2_len( &self, physical_device: vk::PhysicalDevice, @@ -130,19 +135,22 @@ impl GetPhysicalDeviceProperties2 { } #[doc = ""] + /// + /// Call [`Self::get_physical_device_sparse_image_format_properties2_len()`] to query the number of elements to pass to `out`. + /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer. pub unsafe fn get_physical_device_sparse_image_format_properties2( &self, physical_device: vk::PhysicalDevice, format_info: &vk::PhysicalDeviceSparseImageFormatInfo2KHR, - properties: &mut [vk::SparseImageFormatProperties2KHR], + out: &mut [vk::SparseImageFormatProperties2KHR], ) { - let mut count = properties.len() as u32; + let mut count = out.len() as u32; self.get_physical_device_properties2_fn .get_physical_device_sparse_image_format_properties2_khr( physical_device, format_info, &mut count, - properties.as_mut_ptr(), + out.as_mut_ptr(), ); } diff --git a/ash/src/instance.rs b/ash/src/instance.rs index ee1763a0e..d1ce1af63 100644 --- a/ash/src/instance.rs +++ b/ash/src/instance.rs @@ -51,6 +51,7 @@ impl Instance { &self.instance_fn_1_1 } + /// Retrieve the number of elements to pass to [`Self::enumerate_physical_device_groups()`] pub unsafe fn enumerate_physical_device_groups_len(&self) -> VkResult { let mut group_count = 0; self.instance_fn_1_1 @@ -59,6 +60,9 @@ impl Instance { } #[doc = ""] + /// + /// Call [`Self::enumerate_physical_device_groups_len()`] to query the number of elements to pass to `out`. + /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer. pub fn enumerate_physical_device_groups( &self, out: &mut [vk::PhysicalDeviceGroupProperties], @@ -118,6 +122,7 @@ impl Instance { .into() } + /// Retrieve the number of elements to pass to [`Self::get_physical_device_queue_family_properties2()`] pub unsafe fn get_physical_device_queue_family_properties2_len( &self, physical_device: vk::PhysicalDevice, @@ -133,17 +138,20 @@ impl Instance { } #[doc = ""] + /// + /// Call [`Self::get_physical_device_queue_family_properties2_len()`] to query the number of elements to pass to `out`. + /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer. pub unsafe fn get_physical_device_queue_family_properties2( &self, physical_device: vk::PhysicalDevice, - queue_family_props: &mut [vk::QueueFamilyProperties2], + out: &mut [vk::QueueFamilyProperties2], ) { - let mut queue_count = queue_family_props.len() as u32; + let mut queue_count = out.len() as u32; self.instance_fn_1_1 .get_physical_device_queue_family_properties2( physical_device, &mut queue_count, - queue_family_props.as_mut_ptr(), + out.as_mut_ptr(), ); } @@ -157,6 +165,7 @@ impl Instance { .get_physical_device_memory_properties2(physical_device, out); } + /// Retrieve the number of elements to pass to [`Self::get_physical_device_sparse_image_format_properties2()`] pub unsafe fn get_physical_device_sparse_image_format_properties2_len( &self, physical_device: vk::PhysicalDevice, @@ -174,6 +183,9 @@ impl Instance { } #[doc = ""] + /// + /// Call [`Self::get_physical_device_sparse_image_format_properties2_len()`] to query the number of elements to pass to `out`. + /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer. pub unsafe fn get_physical_device_sparse_image_format_properties2( &self, physical_device: vk::PhysicalDevice,