From e120dd78387dd44cf98f19a7be4e5eaa9dab7ece Mon Sep 17 00:00:00 2001 From: Marijn Suijten Date: Thu, 11 Nov 2021 19:51:12 +0100 Subject: [PATCH] Link _len() functions to their array-getter using intradoc-links (#490) 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 e0077ee..fae9cc6 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 bdc7bfa..6cb8f53 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 abf2331..6473b5a 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 432bfdf..b27f3d2 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 unsafe fn enumerate_physical_device_groups( &self, out: &mut [vk::PhysicalDeviceGroupProperties], @@ -116,6 +120,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, @@ -131,17 +136,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(), ); } @@ -155,6 +163,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, @@ -172,6 +181,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,