Skip to content

Commit

Permalink
extensions: Always return pipeline/shaders, even on error (#828)
Browse files Browse the repository at this point in the history
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
  • Loading branch information
MarijnS95 authored Mar 31, 2024
1 parent 1b24430 commit 9e36403
Show file tree
Hide file tree
Showing 6 changed files with 74 additions and 24 deletions.
5 changes: 5 additions & 0 deletions Changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
8 changes: 8 additions & 0 deletions ash/src/device.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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,
Expand Down
16 changes: 12 additions & 4 deletions ash/src/extensions/amdx/shader_enqueue.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
21 changes: 17 additions & 4 deletions ash/src/extensions/ext/shader_object.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
24 changes: 16 additions & 8 deletions ash/src/extensions/khr/ray_tracing_pipeline.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
24 changes: 16 additions & 8 deletions ash/src/extensions/nv/ray_tracing.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down

0 comments on commit 9e36403

Please sign in to comment.