extensions: Always return pipeline/shaders, even on error (#828)

In `ash::Device` `create_compute_pipeline()` and
`create_graphics_pipeline()` already return the list of pipelines
regardless of the error code, as [documented in the Multiple Pipeline
Creation chapter].  Callers are expected to scan the returned array
for valid pipeline handles and either use or destroy them (when
handling an error).  Furthermore, the caller is guaranteed that
all handles will be NULL after the first returned NULL handle when
`VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT` is set.

An upstream Khronos/Vulkan request which has since been merged to the
documentation makes all pipeline creation functions across the core and
extensions point to this `Multiple Pipeline Creation` chapter which has
also been improved, clarifying that they too return impartial results.
This documentation reference has been embedded in `ash`.

`VK_EXT_shader_object` is similar in nature, but has its own
documentation to account for the difference in naming.

[documented in the Multiple Pipeline Creation chapter]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/chap10.html#pipelines-multiple

Changelog.md

@@ -73,6 +73,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `VK_KHR_device_group_creation`: Take borrow of `Entry` in `fn new()` (#753)
 - `VK_KHR_device_group_creation`: Rename `vk::Instance`-returning function from `device()` to `instance()` (#759)
 - Windows `HANDLE` types (`HWND`, `HINSTANCE`, `HMONITOR`) are now defined as `isize` instead of `*const c_void` (#797)
+- extensions: Make all `vk::Pipeline` and `vk::ShaderEXT` creation functions return their impartial result on error (#828)
+  - `VK_AMDX_shader_enqueue`
+  - `VK_EXT_shader_object`
+  - `VK_KHR_ray_tracing_pipeline`
+  - `VK_NV_ray_tracing`
 - extensions/ext/ray_tracing_pipeline: Pass indirect SBT regions as single item reference (#829)
 - Replaced `c_char` array setters with `CStr` setters (#831)
 - `push_next()` functions now allow unsized `p_next` argument (#855)

ash/src/device.rs

@@ -2142,6 +2142,10 @@ impl Device {
     }
 
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCreateGraphicsPipelines.html>
+    ///
+    /// Pipelines are created and returned as described for [Multiple Pipeline Creation].
+    ///
+    /// [Multiple Pipeline Creation]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#pipelines-multiple
     #[inline]
     pub unsafe fn create_graphics_pipelines(
         &self,
@@ -2166,6 +2170,10 @@ impl Device {
     }
 
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCreateComputePipelines.html>
+    ///
+    /// Pipelines are created and returned as described for [Multiple Pipeline Creation].
+    ///
+    /// [Multiple Pipeline Creation]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#pipelines-multiple
     #[inline]
     pub unsafe fn create_compute_pipelines(
         &self,

ash/src/extensions/amdx/shader_enqueue.rs

@@ -8,23 +8,31 @@ use core::mem;
 
 impl crate::amdx::shader_enqueue::Device {
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCreateExecutionGraphPipelinesAMDX.html>
+    ///
+    /// Pipelines are created and returned as described for [Multiple Pipeline Creation].
+    ///
+    /// [Multiple Pipeline Creation]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#pipelines-multiple
     #[inline]
     pub unsafe fn create_execution_graph_pipelines(
         &self,
         pipeline_cache: vk::PipelineCache,
         create_infos: &[vk::ExecutionGraphPipelineCreateInfoAMDX<'_>],
         allocation_callbacks: Option<&vk::AllocationCallbacks<'_>>,
-    ) -> VkResult<Vec<vk::Pipeline>> {
+    ) -> Result<Vec<vk::Pipeline>, (Vec<vk::Pipeline>, vk::Result)> {
         let mut pipelines = Vec::with_capacity(create_infos.len());
-        (self.fp.create_execution_graph_pipelines_amdx)(
+        let err_code = (self.fp.create_execution_graph_pipelines_amdx)(
             self.handle,
             pipeline_cache,
             create_infos.len() as u32,
             create_infos.as_ptr(),
             allocation_callbacks.as_raw_ptr(),
             pipelines.as_mut_ptr(),
-        )
-        .set_vec_len_on_success(pipelines, create_infos.len())
+        );
+        pipelines.set_len(create_infos.len());
+        match err_code {
+            vk::Result::SUCCESS => Ok(pipelines),
+            _ => Err((pipelines, err_code)),
+        }
     }
 
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetExecutionGraphPipelineScratchSizeAMDX.html>

ash/src/extensions/ext/shader_object.rs

@@ -8,21 +8,34 @@ use core::ptr;
 
 impl crate::ext::shader_object::Device {
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCreateShadersEXT.html>
+    ///
+    /// When this function returns, whether or not it succeeds, it is guaranteed that every returned
+    /// element is either [`vk::ShaderEXT::null()`] or a valid [`vk::ShaderEXT`] handle.
+    ///
+    /// This means that whenever shader creation fails, the application can determine which shader
+    /// the returned error pertains to by locating the first [`vk::Handle::is_null()`] element
+    /// in the returned [`Vec`]. It also means that an application can reliably clean up from a
+    /// failed call by iterating over the returned [`Vec`] and destroying every element that is not
+    /// [`vk::Handle::is_null()`].
     #[inline]
     pub unsafe fn create_shaders(
         &self,
         create_infos: &[vk::ShaderCreateInfoEXT<'_>],
         allocator: Option<&vk::AllocationCallbacks<'_>>,
-    ) -> VkResult<Vec<vk::ShaderEXT>> {
+    ) -> Result<Vec<vk::ShaderEXT>, (Vec<vk::ShaderEXT>, vk::Result)> {
         let mut shaders = Vec::with_capacity(create_infos.len());
-        (self.fp.create_shaders_ext)(
+        let err_code = (self.fp.create_shaders_ext)(
             self.handle,
             create_infos.len() as u32,
             create_infos.as_ptr(),
             allocator.as_raw_ptr(),
             shaders.as_mut_ptr(),
-        )
-        .set_vec_len_on_success(shaders, create_infos.len())
+        );
+        shaders.set_len(create_infos.len());
+        match err_code {
+            vk::Result::SUCCESS => Ok(shaders),
+            _ => Err((shaders, err_code)),
+        }
     }
 
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkDestroyShaderEXT.html>

ash/src/extensions/khr/ray_tracing_pipeline.rs

@@ -32,25 +32,33 @@ impl crate::khr::ray_tracing_pipeline::Device {
     }
 
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCreateRayTracingPipelinesKHR.html>
+    ///
+    /// Pipelines are created and returned as described for [Multiple Pipeline Creation].
+    ///
+    /// [Multiple Pipeline Creation]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#pipelines-multiple
     #[inline]
     pub unsafe fn create_ray_tracing_pipelines(
         &self,
         deferred_operation: vk::DeferredOperationKHR,
         pipeline_cache: vk::PipelineCache,
-        create_info: &[vk::RayTracingPipelineCreateInfoKHR<'_>],
+        create_infos: &[vk::RayTracingPipelineCreateInfoKHR<'_>],
         allocation_callbacks: Option<&vk::AllocationCallbacks<'_>>,
-    ) -> VkResult<Vec<vk::Pipeline>> {
-        let mut pipelines = Vec::with_capacity(create_info.len());
-        (self.fp.create_ray_tracing_pipelines_khr)(
+    ) -> Result<Vec<vk::Pipeline>, (Vec<vk::Pipeline>, vk::Result)> {
+        let mut pipelines = Vec::with_capacity(create_infos.len());
+        let err_code = (self.fp.create_ray_tracing_pipelines_khr)(
             self.handle,
             deferred_operation,
             pipeline_cache,
-            create_info.len() as u32,
-            create_info.as_ptr(),
+            create_infos.len() as u32,
+            create_infos.as_ptr(),
             allocation_callbacks.as_raw_ptr(),
             pipelines.as_mut_ptr(),
-        )
-        .set_vec_len_on_success(pipelines, create_info.len())
+        );
+        pipelines.set_len(create_infos.len());
+        match err_code {
+            vk::Result::SUCCESS => Ok(pipelines),
+            _ => Err((pipelines, err_code)),
+        }
     }
 
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetRayTracingShaderGroupHandlesKHR.html>

ash/src/extensions/nv/ray_tracing.rs

@@ -146,23 +146,31 @@ impl crate::nv::ray_tracing::Device {
     }
 
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCreateRayTracingPipelinesNV.html>
+    ///
+    /// Pipelines are created and returned as described for [Multiple Pipeline Creation].
+    ///
+    /// [Multiple Pipeline Creation]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#pipelines-multiple
     #[inline]
     pub unsafe fn create_ray_tracing_pipelines(
         &self,
         pipeline_cache: vk::PipelineCache,
-        create_info: &[vk::RayTracingPipelineCreateInfoNV<'_>],
+        create_infos: &[vk::RayTracingPipelineCreateInfoNV<'_>],
         allocation_callbacks: Option<&vk::AllocationCallbacks<'_>>,
-    ) -> VkResult<Vec<vk::Pipeline>> {
-        let mut pipelines = Vec::with_capacity(create_info.len());
-        (self.fp.create_ray_tracing_pipelines_nv)(
+    ) -> Result<Vec<vk::Pipeline>, (Vec<vk::Pipeline>, vk::Result)> {
+        let mut pipelines = Vec::with_capacity(create_infos.len());
+        let err_code = (self.fp.create_ray_tracing_pipelines_nv)(
             self.handle,
             pipeline_cache,
-            create_info.len() as u32,
-            create_info.as_ptr(),
+            create_infos.len() as u32,
+            create_infos.as_ptr(),
             allocation_callbacks.as_raw_ptr(),
             pipelines.as_mut_ptr(),
-        )
-        .set_vec_len_on_success(pipelines, create_info.len())
+        );
+        pipelines.set_len(create_infos.len());
+        match err_code {
+            vk::Result::SUCCESS => Ok(pipelines),
+            _ => Err((pipelines, err_code)),
+        }
     }
 
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetRayTracingShaderGroupHandlesNV.html>