ash: Hide provisional extensions behind new provisional feature flag

Provisional extensions are susceptible to **breaking** API changes
at any point (with accompanying `SPEC_VERSION` bump).  By hiding them
behind a non-default feature flag, we can document that opting into
this feature allows us to do breaking changes to these modules in
non-breaking `ash` releases when driven by upstream `Vulkan-Headers`
changes to `vk.xml`.

Moreover, upstream Khronos repositories that build `ash` in their CI
can continue to build-test their changes without compile-testing any
extension behind a `provisional` flag, which is especially useful if
we've already wrapped a `provisional` extension that is seeing breaking
changes.

Author: MarijnS95

.github/workflows/ci.yml

@@ -49,6 +49,10 @@ jobs:
         run: cargo test --workspace --all-targets
       - name: Test docs
         run: cargo test --workspace --doc
+      - name: Test all targets
+        run: cargo test --workspace --all-targets -F provisional
+      - name: Test docs
+        run: cargo test --workspace --doc -F provisional
 
   fmt:
     name: Rustfmt

ash-examples/Cargo.toml

@@ -11,5 +11,6 @@ winit = { version = "0.29", features = ["rwh_06"] }
 # The examples require the validation layers, which means the SDK or
 # equivalent development packages should be present, so we can link
 # directly and benefit from the infallible `Entry` constructor.
-ash = { path = "../ash", default-features = false, features = ["linked", "debug", "std"] }
+# Provisional features are required to access VK_KHR_portability_subset for MoltenVK
+ash = { path = "../ash", default-features = false, features = ["linked", "debug", "std", "provisional"] }
 ash-window = { path = "../ash-window" }

ash/Cargo.toml

@@ -37,6 +37,8 @@ loaded = ["libloading", "std"]
 debug = []
 # Whether the standard library should be required
 std = []
+# Enable provisional Vulkan extensions. May see *semver-breaking* code changes in non-breaking releases!
+provisional = []
 
 [package.metadata.release]
 no-dev-version = true

ash/src/extensions/amdx/shader_enqueue.rs

@@ -1,3 +1,4 @@
+#![cfg(feature = "provisional")]
 //! <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_AMDX_shader_enqueue.html>
 
 use crate::vk;

ash/src/extensions/nv/cuda_kernel_launch.rs

@@ -1,3 +1,4 @@
+#![cfg(feature = "provisional")]
 //! <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_NV_cuda_kernel_launch.html>
 
 use crate::read_into_uninitialized_vector;

ash/src/extensions_generated.rs

@@ -495,6 +495,7 @@ pub mod amd {
 #[doc = "Extensions tagged AMDX"]
 pub mod amdx {
     #[doc = "VK_AMDX_shader_enqueue"]
+    #[cfg(feature = "provisional")]
     pub mod shader_enqueue {
         use crate::vk::*;
         use core::ffi::*;
@@ -14792,6 +14793,7 @@ pub mod khr {
         }
     }
     #[doc = "VK_KHR_portability_subset"]
+    #[cfg(feature = "provisional")]
     pub mod portability_subset {
         pub use {
             crate::vk::KHR_PORTABILITY_SUBSET_NAME as NAME,
@@ -19181,6 +19183,7 @@ pub mod nv {
         };
     }
     #[doc = "VK_NV_cuda_kernel_launch"]
+    #[cfg(feature = "provisional")]
     pub mod cuda_kernel_launch {
         use crate::vk::*;
         use core::ffi::*;
@@ -19591,6 +19594,7 @@ pub mod nv {
         }
     }
     #[doc = "VK_NV_displacement_micromap"]
+    #[cfg(feature = "provisional")]
     pub mod displacement_micromap {
         pub use {
             crate::vk::NV_DISPLACEMENT_MICROMAP_NAME as NAME,

ash/src/vk/const_debugs.rs

@@ -608,6 +608,7 @@ impl fmt::Debug for BufferUsageFlags {
                 BufferUsageFlags::CONDITIONAL_RENDERING_EXT.0,
                 "CONDITIONAL_RENDERING_EXT",
             ),
+            #[cfg(feature = "provisional")]
             (
                 BufferUsageFlags::EXECUTION_GRAPH_SCRATCH_AMDX.0,
                 "EXECUTION_GRAPH_SCRATCH_AMDX",
@@ -678,6 +679,7 @@ impl fmt::Debug for BufferUsageFlags2KHR {
             (BufferUsageFlags2KHR::INDEX_BUFFER.0, "INDEX_BUFFER"),
             (BufferUsageFlags2KHR::VERTEX_BUFFER.0, "VERTEX_BUFFER"),
             (BufferUsageFlags2KHR::INDIRECT_BUFFER.0, "INDIRECT_BUFFER"),
+            #[cfg(feature = "provisional")]
             (
                 BufferUsageFlags2KHR::EXECUTION_GRAPH_SCRATCH_AMDX.0,
                 "EXECUTION_GRAPH_SCRATCH_AMDX",
@@ -784,6 +786,7 @@ impl fmt::Debug for BuildAccelerationStructureFlagsKHR {
                 BuildAccelerationStructureFlagsKHR::ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT.0,
                 "ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT",
             ),
+            #[cfg(feature = "provisional")]
             (
                 BuildAccelerationStructureFlagsKHR::ALLOW_DISPLACEMENT_MICROMAP_UPDATE_NV.0,
                 "ALLOW_DISPLACEMENT_MICROMAP_UPDATE_NV",
@@ -1221,7 +1224,9 @@ impl fmt::Debug for DebugReportObjectTypeEXT {
             Self::CU_FUNCTION_NVX => Some("CU_FUNCTION_NVX"),
             Self::ACCELERATION_STRUCTURE_KHR => Some("ACCELERATION_STRUCTURE_KHR"),
             Self::ACCELERATION_STRUCTURE_NV => Some("ACCELERATION_STRUCTURE_NV"),
+            #[cfg(feature = "provisional")]
             Self::CUDA_MODULE_NV => Some("CUDA_MODULE_NV"),
+            #[cfg(feature = "provisional")]
             Self::CUDA_FUNCTION_NV => Some("CUDA_FUNCTION_NV"),
             Self::BUFFER_COLLECTION_FUCHSIA => Some("BUFFER_COLLECTION_FUCHSIA"),
             _ => None,
@@ -1626,6 +1631,7 @@ impl fmt::Debug for DiscardRectangleModeEXT {
         }
     }
 }
+#[cfg(feature = "provisional")]
 impl fmt::Debug for DisplacementMicromapFormatNV {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         let name = match *self {
@@ -3309,6 +3315,7 @@ impl fmt::Debug for MicromapTypeEXT {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         let name = match *self {
             Self::OPACITY_MICROMAP => Some("OPACITY_MICROMAP"),
+            #[cfg(feature = "provisional")]
             Self::DISPLACEMENT_MICROMAP_NV => Some("DISPLACEMENT_MICROMAP_NV"),
             _ => None,
         };
@@ -3651,6 +3658,7 @@ impl fmt::Debug for PipelineBindPoint {
         let name = match *self {
             Self::GRAPHICS => Some("GRAPHICS"),
             Self::COMPUTE => Some("COMPUTE"),
+            #[cfg(feature = "provisional")]
             Self::EXECUTION_GRAPH_AMDX => Some("EXECUTION_GRAPH_AMDX"),
             Self::RAY_TRACING_KHR => Some("RAY_TRACING_KHR"),
             Self::SUBPASS_SHADING_HUAWEI => Some("SUBPASS_SHADING_HUAWEI"),
@@ -3808,6 +3816,7 @@ impl fmt::Debug for PipelineCreateFlags {
                 PipelineCreateFlags::RAY_TRACING_OPACITY_MICROMAP_EXT.0,
                 "RAY_TRACING_OPACITY_MICROMAP_EXT",
             ),
+            #[cfg(feature = "provisional")]
             (
                 PipelineCreateFlags::RAY_TRACING_DISPLACEMENT_MICROMAP_NV.0,
                 "RAY_TRACING_DISPLACEMENT_MICROMAP_NV",
@@ -5520,18 +5529,23 @@ impl fmt::Debug for StructureType {
             Self::ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_2_ANDROID => {
                 Some("ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_2_ANDROID")
             }
+            #[cfg(feature = "provisional")]
             Self::PHYSICAL_DEVICE_SHADER_ENQUEUE_FEATURES_AMDX => {
                 Some("PHYSICAL_DEVICE_SHADER_ENQUEUE_FEATURES_AMDX")
             }
+            #[cfg(feature = "provisional")]
             Self::PHYSICAL_DEVICE_SHADER_ENQUEUE_PROPERTIES_AMDX => {
                 Some("PHYSICAL_DEVICE_SHADER_ENQUEUE_PROPERTIES_AMDX")
             }
+            #[cfg(feature = "provisional")]
             Self::EXECUTION_GRAPH_PIPELINE_SCRATCH_SIZE_AMDX => {
                 Some("EXECUTION_GRAPH_PIPELINE_SCRATCH_SIZE_AMDX")
             }
+            #[cfg(feature = "provisional")]
             Self::EXECUTION_GRAPH_PIPELINE_CREATE_INFO_AMDX => {
                 Some("EXECUTION_GRAPH_PIPELINE_CREATE_INFO_AMDX")
             }
+            #[cfg(feature = "provisional")]
             Self::PIPELINE_SHADER_STAGE_NODE_CREATE_INFO_AMDX => {
                 Some("PIPELINE_SHADER_STAGE_NODE_CREATE_INFO_AMDX")
             }
@@ -5652,9 +5666,11 @@ impl fmt::Debug for StructureType {
             Self::SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT => {
                 Some("SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT")
             }
+            #[cfg(feature = "provisional")]
             Self::PHYSICAL_DEVICE_PORTABILITY_SUBSET_FEATURES_KHR => {
                 Some("PHYSICAL_DEVICE_PORTABILITY_SUBSET_FEATURES_KHR")
             }
+            #[cfg(feature = "provisional")]
             Self::PHYSICAL_DEVICE_PORTABILITY_SUBSET_PROPERTIES_KHR => {
                 Some("PHYSICAL_DEVICE_PORTABILITY_SUBSET_PROPERTIES_KHR")
             }
@@ -6081,12 +6097,17 @@ impl fmt::Debug for StructureType {
             Self::DEVICE_DIAGNOSTICS_CONFIG_CREATE_INFO_NV => {
                 Some("DEVICE_DIAGNOSTICS_CONFIG_CREATE_INFO_NV")
             }
+            #[cfg(feature = "provisional")]
             Self::CUDA_MODULE_CREATE_INFO_NV => Some("CUDA_MODULE_CREATE_INFO_NV"),
+            #[cfg(feature = "provisional")]
             Self::CUDA_FUNCTION_CREATE_INFO_NV => Some("CUDA_FUNCTION_CREATE_INFO_NV"),
+            #[cfg(feature = "provisional")]
             Self::CUDA_LAUNCH_INFO_NV => Some("CUDA_LAUNCH_INFO_NV"),
+            #[cfg(feature = "provisional")]
             Self::PHYSICAL_DEVICE_CUDA_KERNEL_LAUNCH_FEATURES_NV => {
                 Some("PHYSICAL_DEVICE_CUDA_KERNEL_LAUNCH_FEATURES_NV")
             }
+            #[cfg(feature = "provisional")]
             Self::PHYSICAL_DEVICE_CUDA_KERNEL_LAUNCH_PROPERTIES_NV => {
                 Some("PHYSICAL_DEVICE_CUDA_KERNEL_LAUNCH_PROPERTIES_NV")
             }
@@ -6368,12 +6389,15 @@ impl fmt::Debug for StructureType {
             Self::ACCELERATION_STRUCTURE_TRIANGLES_OPACITY_MICROMAP_EXT => {
                 Some("ACCELERATION_STRUCTURE_TRIANGLES_OPACITY_MICROMAP_EXT")
             }
+            #[cfg(feature = "provisional")]
             Self::PHYSICAL_DEVICE_DISPLACEMENT_MICROMAP_FEATURES_NV => {
                 Some("PHYSICAL_DEVICE_DISPLACEMENT_MICROMAP_FEATURES_NV")
             }
+            #[cfg(feature = "provisional")]
             Self::PHYSICAL_DEVICE_DISPLACEMENT_MICROMAP_PROPERTIES_NV => {
                 Some("PHYSICAL_DEVICE_DISPLACEMENT_MICROMAP_PROPERTIES_NV")
             }
+            #[cfg(feature = "provisional")]
             Self::ACCELERATION_STRUCTURE_TRIANGLES_DISPLACEMENT_MICROMAP_NV => {
                 Some("ACCELERATION_STRUCTURE_TRIANGLES_DISPLACEMENT_MICROMAP_NV")
             }

ash/src/vk/constants.rs

@@ -34,4 +34,5 @@ pub const MAX_GLOBAL_PRIORITY_SIZE_EXT: usize = MAX_GLOBAL_PRIORITY_SIZE_KHR;
 pub const MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT: usize = 32;
 pub const MAX_PIPELINE_BINARY_KEY_SIZE_KHR: usize = 32;
 pub const MAX_VIDEO_AV1_REFERENCES_PER_FRAME_KHR: usize = 7;
+#[cfg(feature = "provisional")]
 pub const SHADER_INDEX_UNUSED_AMDX: u32 = !0;