From 64f3de38abee1f38a60bf3ef54b31f5d796174d9 Mon Sep 17 00:00:00 2001 From: Marijn Suijten Date: Tue, 23 Nov 2021 20:11:42 +0100 Subject: [PATCH] generator: Add missing documentation to bitflag extension variants (#501) --- ash/src/vk/constants.rs | 1 + ash/src/vk/extensions.rs | 21 +++++++++++++++++++++ ash/src/vk/feature_extensions.rs | 18 ++++++++++++++++++ generator/src/lib.rs | 26 ++++++++++++++++---------- 4 files changed, 56 insertions(+), 10 deletions(-) diff --git a/ash/src/vk/constants.rs b/ash/src/vk/constants.rs index 95a976e..361b197 100644 --- a/ash/src/vk/constants.rs +++ b/ash/src/vk/constants.rs @@ -5,6 +5,7 @@ pub const LUID_SIZE: usize = 8; pub const MAX_EXTENSION_NAME_SIZE: usize = 256; pub const MAX_DESCRIPTION_SIZE: usize = 256; pub const MAX_MEMORY_TYPES: usize = 32; +#[doc = "The maximum number of unique memory heaps, each of which supporting 1 or more memory types"] pub const MAX_MEMORY_HEAPS: usize = 16; pub const LOD_CLAMP_NONE: f32 = 1000.00; pub const REMAINING_MIP_LEVELS: u32 = !0; diff --git a/ash/src/vk/extensions.rs b/ash/src/vk/extensions.rs index 0f22cb3..3dd0ac0 100644 --- a/ash/src/vk/extensions.rs +++ b/ash/src/vk/extensions.rs @@ -660,10 +660,12 @@ impl StructureType { } #[doc = "Generated from 'VK_KHR_swapchain'"] impl SwapchainCreateFlagsKHR { + #[doc = "Allow images with VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT"] pub const SPLIT_INSTANCE_BIND_REGIONS: Self = Self(0b1); } #[doc = "Generated from 'VK_KHR_swapchain'"] impl SwapchainCreateFlagsKHR { + #[doc = "Swapchain is protected"] pub const PROTECTED: Self = Self(0b10); } impl KhrDisplayFn { @@ -1971,6 +1973,7 @@ impl StructureType { } #[doc = "Generated from 'VK_EXT_debug_report'"] impl StructureType { + #[deprecated = "Backwards-compatible alias containing a typo"] pub const DEBUG_REPORT_CREATE_INFO_EXT: Self = Self::DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT; } #[doc = "Generated from 'VK_EXT_debug_report'"] @@ -2052,10 +2055,12 @@ impl KhrSamplerMirrorClampToEdgeFn { } #[doc = "Generated from 'VK_KHR_sampler_mirror_clamp_to_edge'"] impl SamplerAddressMode { + #[doc = "Note that this defines what was previously a core enum, and so uses the 'value' attribute rather than 'offset', and does not have a suffix. This is a special case, and should not be repeated"] pub const MIRROR_CLAMP_TO_EDGE: Self = Self(4); } #[doc = "Generated from 'VK_KHR_sampler_mirror_clamp_to_edge'"] impl SamplerAddressMode { + #[deprecated = "Alias introduced for consistency with extension suffixing rules"] pub const MIRROR_CLAMP_TO_EDGE_KHR: Self = Self::MIRROR_CLAMP_TO_EDGE; } impl ImgFilterCubicFn { @@ -2083,6 +2088,7 @@ impl Filter { } #[doc = "Generated from 'VK_IMG_filter_cubic'"] impl FormatFeatureFlags { + #[doc = "Format can be filtered with VK_FILTER_CUBIC_IMG when being sampled"] pub const SAMPLED_IMAGE_FILTER_CUBIC_IMG: Self = Self(0b10_0000_0000_0000); } impl AmdExtension17Fn { @@ -2951,10 +2957,12 @@ impl StructureType { } #[doc = "Generated from 'VK_KHR_video_queue'"] impl ObjectType { + #[doc = "VkVideoSessionKHR"] pub const VIDEO_SESSION_KHR: Self = Self(1_000_023_000); } #[doc = "Generated from 'VK_KHR_video_queue'"] impl ObjectType { + #[doc = "VkVideoSessionParametersKHR"] pub const VIDEO_SESSION_PARAMETERS_KHR: Self = Self(1_000_023_001); } #[doc = "Generated from 'VK_KHR_video_queue'"] @@ -4472,6 +4480,7 @@ impl PipelineCreateFlags { } #[doc = "Generated from 'VK_KHR_dynamic_rendering'"] impl PipelineCreateFlags { + #[deprecated = "Backwards-compatible alias containing a typo"] pub const RASTERIZATION_STATE_FRAGMENT_SHADING_RATE_ATTACHMENT_KHR: Self = Self::RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_KHR; } @@ -4486,6 +4495,7 @@ impl PipelineCreateFlags { } #[doc = "Generated from 'VK_KHR_dynamic_rendering'"] impl PipelineCreateFlags { + #[deprecated = "Backwards-compatible alias containing a typo"] pub const RASTERIZATION_STATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_EXT: Self = Self::RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_EXT; } @@ -6971,10 +6981,12 @@ impl StructureType { } #[doc = "Generated from 'VK_KHR_push_descriptor'"] impl DescriptorSetLayoutCreateFlags { + #[doc = "Descriptors are pushed via flink:vkCmdPushDescriptorSetKHR"] pub const PUSH_DESCRIPTOR_KHR: Self = Self(0b1); } #[doc = "Generated from 'VK_KHR_push_descriptor'"] impl DescriptorUpdateTemplateType { + #[doc = "Create descriptor update template for pushed descriptor updates"] pub const PUSH_DESCRIPTORS_KHR: Self = Self(1); } impl ExtConditionalRenderingFn { @@ -7073,14 +7085,17 @@ impl StructureType { } #[doc = "Generated from 'VK_EXT_conditional_rendering'"] impl AccessFlags { + #[doc = "read access flag for reading conditional rendering predicate"] pub const CONDITIONAL_RENDERING_READ_EXT: Self = Self(0b1_0000_0000_0000_0000_0000); } #[doc = "Generated from 'VK_EXT_conditional_rendering'"] impl BufferUsageFlags { + #[doc = "Specifies the buffer can be used as predicate in conditional rendering"] pub const CONDITIONAL_RENDERING_EXT: Self = Self(0b10_0000_0000); } #[doc = "Generated from 'VK_EXT_conditional_rendering'"] impl PipelineStageFlags { + #[doc = "A pipeline stage for conditional rendering predicate fetch"] pub const CONDITIONAL_RENDERING_EXT: Self = Self(0b100_0000_0000_0000_0000); } impl KhrShaderFloat16Int8Fn { @@ -7678,6 +7693,7 @@ impl StructureType { } #[doc = "Generated from 'VK_EXT_display_surface_counter'"] impl StructureType { + #[deprecated = "Backwards-compatible alias containing a typo"] pub const SURFACE_CAPABILITIES2_EXT: Self = Self::SURFACE_CAPABILITIES_2_EXT; } impl ExtDisplayControlFn { @@ -8345,6 +8361,7 @@ impl ColorSpaceKHR { } #[doc = "Generated from 'VK_EXT_swapchain_colorspace'"] impl ColorSpaceKHR { + #[deprecated = "Backwards-compatible alias containing a typo"] pub const DCI_P3_LINEAR_EXT: Self = Self::DISPLAY_P3_LINEAR_EXT; } impl ExtHdrMetadataFn { @@ -16882,6 +16899,7 @@ impl StructureType { } #[doc = "Generated from 'VK_INTEL_performance_query'"] impl StructureType { + #[deprecated = "Backwards-compatible alias containing a typo"] pub const QUERY_POOL_CREATE_INFO_INTEL: Self = Self::QUERY_POOL_PERFORMANCE_QUERY_CREATE_INFO_INTEL; } @@ -22252,10 +22270,12 @@ impl AccessFlags2KHR { } #[doc = "Generated from 'VK_KHR_synchronization2'"] impl PipelineStageFlags2KHR { + #[doc = "A pipeline stage for conditional rendering predicate fetch"] pub const CONDITIONAL_RENDERING_EXT: Self = Self(0b100_0000_0000_0000_0000); } #[doc = "Generated from 'VK_KHR_synchronization2'"] impl AccessFlags2KHR { + #[doc = "read access flag for reading conditional rendering predicate"] pub const CONDITIONAL_RENDERING_READ_EXT: Self = Self(0b1_0000_0000_0000_0000_0000); } #[doc = "Generated from 'VK_KHR_synchronization2'"] @@ -24417,6 +24437,7 @@ impl StructureType { } #[doc = "Generated from 'VK_FUCHSIA_buffer_collection'"] impl ObjectType { + #[doc = "VkBufferCollectionFUCHSIA"] pub const BUFFER_COLLECTION_FUCHSIA: Self = Self(1_000_366_000); } #[doc = "Generated from 'VK_FUCHSIA_buffer_collection'"] diff --git a/ash/src/vk/feature_extensions.rs b/ash/src/vk/feature_extensions.rs index 8cf9b89..52c2e47 100644 --- a/ash/src/vk/feature_extensions.rs +++ b/ash/src/vk/feature_extensions.rs @@ -58,6 +58,7 @@ impl PipelineCreateFlags { } #[doc = "Generated from 'VK_VERSION_1_1'"] impl DependencyFlags { + #[doc = "Dependency is across devices"] pub const DEVICE_GROUP: Self = Self(0b100); } #[doc = "Generated from 'VK_VERSION_1_1'"] @@ -70,6 +71,7 @@ impl StructureType { } #[doc = "Generated from 'VK_VERSION_1_1'"] impl ImageCreateFlags { + #[doc = "Allows using VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions when binding memory to the image"] pub const SPLIT_INSTANCE_BIND_REGIONS: Self = Self(0b100_0000); } #[doc = "Generated from 'VK_VERSION_1_1'"] @@ -82,6 +84,7 @@ impl StructureType { } #[doc = "Generated from 'VK_VERSION_1_1'"] impl MemoryHeapFlags { + #[doc = "If set, heap allocations allocate multiple instances by default"] pub const MULTI_INSTANCE: Self = Self(0b10); } #[doc = "Generated from 'VK_VERSION_1_1'"] @@ -146,14 +149,17 @@ impl Result { } #[doc = "Generated from 'VK_VERSION_1_1'"] impl FormatFeatureFlags { + #[doc = "Format can be used as the source image of image transfer commands"] pub const TRANSFER_SRC: Self = Self(0b100_0000_0000_0000); } #[doc = "Generated from 'VK_VERSION_1_1'"] impl FormatFeatureFlags { + #[doc = "Format can be used as the destination image of image transfer commands"] pub const TRANSFER_DST: Self = Self(0b1000_0000_0000_0000); } #[doc = "Generated from 'VK_VERSION_1_1'"] impl ImageCreateFlags { + #[doc = "The 3D image can be viewed as a 2D or 2D array image"] pub const TYPE_2D_ARRAY_COMPATIBLE: Self = Self(0b10_0000); } #[doc = "Generated from 'VK_VERSION_1_1'"] @@ -231,26 +237,32 @@ impl StructureType { } #[doc = "Generated from 'VK_VERSION_1_1'"] impl QueueFlags { + #[doc = "Queues may support protected operations"] pub const PROTECTED: Self = Self(0b1_0000); } #[doc = "Generated from 'VK_VERSION_1_1'"] impl DeviceQueueCreateFlags { + #[doc = "Queue is a protected-capable device queue"] pub const PROTECTED: Self = Self(0b1); } #[doc = "Generated from 'VK_VERSION_1_1'"] impl MemoryPropertyFlags { + #[doc = "Memory is protected"] pub const PROTECTED: Self = Self(0b10_0000); } #[doc = "Generated from 'VK_VERSION_1_1'"] impl BufferCreateFlags { + #[doc = "Buffer requires protected memory"] pub const PROTECTED: Self = Self(0b1000); } #[doc = "Generated from 'VK_VERSION_1_1'"] impl ImageCreateFlags { + #[doc = "Image requires protected memory"] pub const PROTECTED: Self = Self(0b1000_0000_0000); } #[doc = "Generated from 'VK_VERSION_1_1'"] impl CommandPoolCreateFlags { + #[doc = "Command buffers allocated from pool are protected command buffers"] pub const PROTECTED: Self = Self(0b100); } #[doc = "Generated from 'VK_VERSION_1_1'"] @@ -435,14 +447,17 @@ impl ImageCreateFlags { } #[doc = "Generated from 'VK_VERSION_1_1'"] impl FormatFeatureFlags { + #[doc = "Format can have midpoint rather than cosited chroma samples"] pub const MIDPOINT_CHROMA_SAMPLES: Self = Self(0b10_0000_0000_0000_0000); } #[doc = "Generated from 'VK_VERSION_1_1'"] impl FormatFeatureFlags { + #[doc = "Format can be used with linear filtering whilst color conversion is enabled"] pub const SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER: Self = Self(0b100_0000_0000_0000_0000); } #[doc = "Generated from 'VK_VERSION_1_1'"] impl FormatFeatureFlags { + #[doc = "Format can have different chroma, min and mag filters"] pub const SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER: Self = Self(0b1000_0000_0000_0000_0000); } @@ -458,10 +473,12 @@ impl FormatFeatureFlags { } #[doc = "Generated from 'VK_VERSION_1_1'"] impl FormatFeatureFlags { + #[doc = "Format supports disjoint planes"] pub const DISJOINT: Self = Self(0b100_0000_0000_0000_0000_0000); } #[doc = "Generated from 'VK_VERSION_1_1'"] impl FormatFeatureFlags { + #[doc = "Format can have cosited rather than midpoint chroma samples"] pub const COSITED_CHROMA_SAMPLES: Self = Self(0b1000_0000_0000_0000_0000_0000); } #[doc = "Generated from 'VK_VERSION_1_1'"] @@ -675,6 +692,7 @@ impl StructureType { } #[doc = "Generated from 'VK_VERSION_1_2'"] impl FormatFeatureFlags { + #[doc = "Format can be used with min/max reduction filtering"] pub const SAMPLED_IMAGE_FILTER_MINMAX: Self = Self(0b1_0000_0000_0000_0000); } #[doc = "Generated from 'VK_VERSION_1_2'"] diff --git a/generator/src/lib.rs b/generator/src/lib.rs index e9e512f..cc36833 100644 --- a/generator/src/lib.rs +++ b/generator/src/lib.rs @@ -359,6 +359,15 @@ pub trait ConstantExt { fn is_alias(&self) -> bool { false } + fn doc_attribute(&self) -> TokenStream { + match self.notation() { + Some(n) if n.starts_with("Backwards") || n.starts_with("Alias") => { + quote!(#[deprecated = #n]) + } + Some(n) => quote!(#[doc = #n]), + None => quote!(), + } + } } impl ConstantExt for vkxml::ExtensionEnum { @@ -1064,6 +1073,7 @@ fn generate_function_pointers<'a>( pub struct ExtensionConstant<'a> { pub name: &'a str, pub constant: Constant, + pub notation: Option<&'a str>, } impl<'a> ConstantExt for ExtensionConstant<'a> { fn constant(&self, _enum_name: &str) -> Constant { @@ -1073,7 +1083,7 @@ impl<'a> ConstantExt for ExtensionConstant<'a> { variant_ident(enum_name, self.name) } fn notation(&self) -> Option<&str> { - None + self.notation } } @@ -1103,6 +1113,7 @@ pub fn generate_extension_constants<'a>( let ext_constant = ExtensionConstant { name: &enum_.name, constant, + notation: enum_.comment.as_deref(), }; let ident = name_to_tokens(&extends); const_values @@ -1435,15 +1446,7 @@ pub fn bitflags_impl_block( }) .collect_vec(); - let notations = constants.iter().map(|constant| { - constant.notation().map(|n| { - if n.to_lowercase().contains("backwards") { - quote!(#[deprecated = #n]) - } else { - quote!(#[doc = #n]) - } - }) - }); + let notations = constants.iter().map(|constant| constant.doc_attribute()); let variants = variants @@ -2374,12 +2377,15 @@ pub fn generate_constant<'a>( let c = Constant::from_constant(constant); let name = constant_name(&constant.name); let ident = format_ident!("{}", name); + let notation = constant.doc_attribute(); + let ty = if name == "TRUE" || name == "FALSE" { CType::Bool32 } else { c.ty() }; quote! { + #notation pub const #ident: #ty = #c; } }