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::*;
@@ -5493,8 +5494,10 @@ pub mod ext {
                 self.handle
             }
         }
-        #[allow(non_camel_case_types)]
         #[doc = "Implemented for all types that can be passed as argument to `pipeline_properties` in [`PFN_vkGetPipelinePropertiesEXT`]"]
+        #[doc = ""]
+        #[doc = "Provided by VK_EXT_pipeline_properties"]
+        #[allow(non_camel_case_types)]
         pub unsafe trait GetPipelinePropertiesEXTParamPipelineProperties {}
         unsafe impl GetPipelinePropertiesEXTParamPipelineProperties
             for PipelinePropertiesIdentifierEXT<'_>
@@ -14792,6 +14795,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 +19185,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 +19596,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/bitflags.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/const_debugs.rs

@@ -1,31 +1,61 @@
 use super::definitions::*;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const MAX_PHYSICAL_DEVICE_NAME_SIZE: usize = 256;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const UUID_SIZE: usize = 16;
+#[doc = "Provided by VK_VERSION_1_1"]
 pub const LUID_SIZE: usize = 8;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const MAX_EXTENSION_NAME_SIZE: usize = 256;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const MAX_DESCRIPTION_SIZE: usize = 256;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const MAX_MEMORY_TYPES: usize = 32;
 #[doc = "The maximum number of unique memory heaps, each of which supporting 1 or more memory types"]
+#[doc = ""]
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const MAX_MEMORY_HEAPS: usize = 16;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const LOD_CLAMP_NONE: f32 = 1000.00;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const REMAINING_MIP_LEVELS: u32 = !0;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const REMAINING_ARRAY_LAYERS: u32 = !0;
+#[doc = "Provided by VK_EXT_image_sliced_view_of_3d"]
 pub const REMAINING_3D_SLICES_EXT: u32 = !0;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const WHOLE_SIZE: u64 = !0;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const ATTACHMENT_UNUSED: u32 = !0;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const TRUE: Bool32 = 1;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const FALSE: Bool32 = 0;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const QUEUE_FAMILY_IGNORED: u32 = !0;
+#[doc = "Provided by VK_VERSION_1_1"]
 pub const QUEUE_FAMILY_EXTERNAL: u32 = !1;
+#[doc = "Provided by VK_EXT_queue_family_foreign"]
 pub const QUEUE_FAMILY_FOREIGN_EXT: u32 = !2;
+#[doc = "Provided by VK_VERSION_1_0"]
 pub const SUBPASS_EXTERNAL: u32 = !0;
+#[doc = "Provided by VK_VERSION_1_1"]
 pub const MAX_DEVICE_GROUP_SIZE: usize = 32;
+#[doc = "Provided by VK_VERSION_1_2"]
 pub const MAX_DRIVER_NAME_SIZE: usize = 256;
+#[doc = "Provided by VK_VERSION_1_2"]
 pub const MAX_DRIVER_INFO_SIZE: usize = 256;
+#[doc = "Provided by VK_KHR_ray_tracing_pipeline"]
 pub const SHADER_UNUSED_KHR: u32 = !0;
+#[doc = "Provided by VK_KHR_global_priority"]
 pub const MAX_GLOBAL_PRIORITY_SIZE_KHR: usize = 16;
+#[doc = "Provided by VK_EXT_shader_module_identifier"]
 pub const MAX_SHADER_MODULE_IDENTIFIER_SIZE_EXT: usize = 32;
+#[doc = "Provided by VK_KHR_pipeline_binary"]
 pub const MAX_PIPELINE_BINARY_KEY_SIZE_KHR: usize = 32;
+#[doc = "Provided by VK_KHR_video_decode_av1"]
 pub const MAX_VIDEO_AV1_REFERENCES_PER_FRAME_KHR: usize = 7;
+#[doc = "Provided by VK_AMDX_shader_enqueue"]
+#[cfg(feature = "provisional")]
 pub const SHADER_INDEX_UNUSED_AMDX: u32 = !0;
 pub const SHADER_UNUSED_NV: u32 = SHADER_UNUSED_KHR;