diff --git a/appendices/VK_IMG_format_pvrtc.txt b/appendices/VK_IMG_format_pvrtc.txt new file mode 100644 index 00000000..3155a8b1 --- /dev/null +++ b/appendices/VK_IMG_format_pvrtc.txt @@ -0,0 +1,16 @@ +include::meta/VK_IMG_format_pvrtc.txt[] + +*IP Status*:: + TBD (See https://github.com/KhronosGroup/Vulkan-Docs/issues/512) + +=== New Enum Constants + + * Extending elink:VkFormat: + ** ename:VK_FORMAT_PVRTC1_2BPP_UNORM_BLOCK_IMG + ** ename:VK_FORMAT_PVRTC1_4BPP_UNORM_BLOCK_IMG + ** ename:VK_FORMAT_PVRTC2_2BPP_UNORM_BLOCK_IMG + ** ename:VK_FORMAT_PVRTC2_4BPP_UNORM_BLOCK_IMG + ** ename:VK_FORMAT_PVRTC1_2BPP_SRGB_BLOCK_IMG + ** ename:VK_FORMAT_PVRTC1_4BPP_SRGB_BLOCK_IMG + ** ename:VK_FORMAT_PVRTC2_2BPP_SRGB_BLOCK_IMG + ** ename:VK_FORMAT_PVRTC2_4BPP_SRGB_BLOCK_IMG diff --git a/appendices/extensions.txt b/appendices/extensions.txt index 1d69e884..ec511133 100644 --- a/appendices/extensions.txt +++ b/appendices/extensions.txt @@ -58,528 +58,5 @@ not be equivalent to `KHX`, but it is likely to indicate a lesser degree of interface stability than a non-`X` extension from the same vendor. ==== -// Extension appendix sections are included here, grouped by the author ID -// Adding the section headers here means that there will usually be -// a bunch of empty sections, which is undesirable. - -// == Khronos `KHR` Extensions -// - -ifdef::VK_KHR_16bit_storage[] -include::VK_KHR_16bit_storage.txt[] -endif::VK_KHR_16bit_storage[] - -ifdef::VK_KHR_android_surface[] -include::VK_KHR_android_surface.txt[] -endif::VK_KHR_android_surface[] - -ifdef::VK_KHR_bind_memory2[] -include::VK_KHR_bind_memory2.txt[] -endif::VK_KHR_bind_memory2[] - -ifdef::VK_KHR_dedicated_allocation[] -include::VK_KHR_dedicated_allocation.txt[] -endif::VK_KHR_dedicated_allocation[] - -ifdef::VK_KHR_descriptor_update_template[] -include::VK_KHR_descriptor_update_template.txt[] -endif::VK_KHR_descriptor_update_template[] - -ifdef::VK_KHR_device_group[] -include::VK_KHR_device_group.txt[] -endif::VK_KHR_device_group[] - -ifdef::VK_KHR_device_group_creation[] -include::VK_KHR_device_group_creation.txt[] -endif::VK_KHR_device_group_creation[] - -ifdef::VK_KHR_display[] -include::VK_KHR_display.txt[] -endif::VK_KHR_display[] - -ifdef::VK_KHR_display_swapchain[] -include::VK_KHR_display_swapchain.txt[] -endif::VK_KHR_display_swapchain[] - -ifdef::VK_KHR_draw_indirect_count[] -include::VK_KHR_draw_indirect_count.txt[] -endif::VK_KHR_draw_indirect_count[] - -ifdef::VK_KHR_external_fence[] -include::VK_KHR_external_fence.txt[] -endif::VK_KHR_external_fence[] - -ifdef::VK_KHR_external_fence_capabilities[] -include::VK_KHR_external_fence_capabilities.txt[] -endif::VK_KHR_external_fence_capabilities[] - -ifdef::VK_KHR_external_fence_fd[] -include::VK_KHR_external_fence_fd.txt[] -endif::VK_KHR_external_fence_fd[] - -ifdef::VK_KHR_external_fence_win32[] -include::VK_KHR_external_fence_win32.txt[] -endif::VK_KHR_external_fence_win32[] - -ifdef::VK_KHR_external_memory[] -include::VK_KHR_external_memory.txt[] -endif::VK_KHR_external_memory[] - -ifdef::VK_KHR_external_memory_capabilities[] -include::VK_KHR_external_memory_capabilities.txt[] -endif::VK_KHR_external_memory_capabilities[] - -ifdef::VK_KHR_external_memory_fd[] -include::VK_KHR_external_memory_fd.txt[] -endif::VK_KHR_external_memory_fd[] - -ifdef::VK_KHR_external_memory_win32[] -include::VK_KHR_external_memory_win32.txt[] -endif::VK_KHR_external_memory_win32[] - -ifdef::VK_KHR_external_semaphore[] -include::VK_KHR_external_semaphore.txt[] -endif::VK_KHR_external_semaphore[] - -ifdef::VK_KHR_external_semaphore_capabilities[] -include::VK_KHR_external_semaphore_capabilities.txt[] -endif::VK_KHR_external_semaphore_capabilities[] - -ifdef::VK_KHR_external_semaphore_fd[] -include::VK_KHR_external_semaphore_fd.txt[] -endif::VK_KHR_external_semaphore_fd[] - -ifdef::VK_KHR_external_semaphore_win32[] -include::VK_KHR_external_semaphore_win32.txt[] -endif::VK_KHR_external_semaphore_win32[] - -ifdef::VK_KHR_get_display_properties2[] -include::VK_KHR_get_display_properties2.txt[] -endif::VK_KHR_get_display_properties2[] - -ifdef::VK_KHR_get_memory_requirements2[] -include::VK_KHR_get_memory_requirements2.txt[] -endif::VK_KHR_get_memory_requirements2[] - -ifdef::VK_KHR_get_physical_device_properties2[] -include::VK_KHR_get_physical_device_properties2.txt[] -endif::VK_KHR_get_physical_device_properties2[] - -ifdef::VK_KHR_get_surface_capabilities2[] -include::VK_KHR_get_surface_capabilities2.txt[] -endif::VK_KHR_get_surface_capabilities2[] - -ifdef::VK_KHR_image_format_list[] -include::VK_KHR_image_format_list.txt[] -endif::VK_KHR_image_format_list[] - -ifdef::VK_KHR_incremental_present[] -include::VK_KHR_incremental_present.txt[] -endif::VK_KHR_incremental_present[] - -ifdef::VK_KHR_maintenance1[] -include::VK_KHR_maintenance1.txt[] -endif::VK_KHR_maintenance1[] - -ifdef::VK_KHR_maintenance2[] -include::VK_KHR_maintenance2.txt[] -endif::VK_KHR_maintenance2[] - -ifdef::VK_KHR_maintenance3[] -include::VK_KHR_maintenance3.txt[] -endif::VK_KHR_maintenance3[] - -ifdef::VK_KHR_mir_surface[] -include::VK_KHR_mir_surface.txt[] -endif::VK_KHR_mir_surface[] - -ifdef::VK_KHR_multiview[] -include::VK_KHR_multiview.txt[] -endif::VK_KHR_multiview[] - -ifdef::VK_KHR_push_descriptor[] -include::VK_KHR_push_descriptor.txt[] -endif::VK_KHR_push_descriptor[] - -ifdef::VK_KHR_relaxed_block_layout[] -include::VK_KHR_relaxed_block_layout.txt[] -endif::VK_KHR_relaxed_block_layout[] - -include::VK_KHR_sampler_mirror_clamp_to_edge.txt[] - -ifdef::VK_KHR_sampler_ycbcr_conversion[] -include::VK_KHR_sampler_ycbcr_conversion.txt[] -endif::VK_KHR_sampler_ycbcr_conversion[] - -ifdef::VK_KHR_shader_draw_parameters[] -include::VK_KHR_shader_draw_parameters.txt[] -endif::VK_KHR_shader_draw_parameters[] - -ifdef::VK_KHR_shared_presentable_image[] -include::VK_KHR_shared_presentable_image.txt[] -endif::VK_KHR_shared_presentable_image[] - -ifdef::VK_KHR_storage_buffer_storage_class[] -include::VK_KHR_storage_buffer_storage_class.txt[] -endif::VK_KHR_storage_buffer_storage_class[] - -ifdef::VK_KHR_surface[] -include::VK_KHR_surface.txt[] -endif::VK_KHR_surface[] - -ifdef::VK_KHR_swapchain[] -include::VK_KHR_swapchain.txt[] -endif::VK_KHR_swapchain[] - -ifdef::VK_KHR_variable_pointers[] -include::VK_KHR_variable_pointers.txt[] -endif::VK_KHR_variable_pointers[] - -ifdef::VK_KHR_wayland_surface[] -include::VK_KHR_wayland_surface.txt[] -endif::VK_KHR_wayland_surface[] - -ifdef::VK_KHR_win32_keyed_mutex[] -include::VK_KHR_win32_keyed_mutex.txt[] -endif::VK_KHR_win32_keyed_mutex[] - -ifdef::VK_KHR_win32_surface[] -include::VK_KHR_win32_surface.txt[] -endif::VK_KHR_win32_surface[] - -ifdef::VK_KHR_xcb_surface[] -include::VK_KHR_xcb_surface.txt[] -endif::VK_KHR_xcb_surface[] - -ifdef::VK_KHR_xlib_surface[] -include::VK_KHR_xlib_surface.txt[] -endif::VK_KHR_xlib_surface[] - - -// == Multivendor `EXT` Extensions -// -// :leveloffset: 2 - -ifdef::VK_EXT_acquire_xlib_display[] -include::VK_EXT_acquire_xlib_display.txt[] -endif::VK_EXT_acquire_xlib_display[] - -ifdef::VK_EXT_blend_operation_advanced[] -include::VK_EXT_blend_operation_advanced.txt[] -endif::VK_EXT_blend_operation_advanced[] - -ifdef::VK_EXT_conservative_rasterization[] -include::VK_EXT_conservative_rasterization.txt[] -endif::VK_EXT_conservative_rasterization[] - -ifdef::VK_EXT_debug_marker[] -include::VK_EXT_debug_marker.txt[] -endif::VK_EXT_debug_marker[] - -ifdef::VK_EXT_debug_report[] -include::VK_EXT_debug_report.txt[] -endif::VK_EXT_debug_report[] - -ifdef::VK_EXT_debug_utils[] -include::VK_EXT_debug_utils.txt[] -endif::VK_EXT_debug_utils[] - -ifdef::VK_EXT_depth_range_unrestricted[] -include::VK_EXT_depth_range_unrestricted.txt[] -endif::VK_EXT_depth_range_unrestricted[] - -ifdef::VK_EXT_descriptor_indexing[] -include::VK_EXT_descriptor_indexing.txt[] -endif::VK_EXT_descriptor_indexing[] - -ifdef::VK_EXT_direct_mode_display[] -include::VK_EXT_direct_mode_display.txt[] -endif::VK_EXT_direct_mode_display[] - -ifdef::VK_EXT_discard_rectangles[] -include::VK_EXT_discard_rectangles.txt[] -endif::VK_EXT_discard_rectangles[] - -ifdef::VK_EXT_display_control[] -include::VK_EXT_display_control.txt[] -endif::VK_EXT_display_control[] - -ifdef::VK_EXT_display_surface_counter[] -include::VK_EXT_display_surface_counter.txt[] -endif::VK_EXT_display_surface_counter[] - -ifdef::VK_EXT_external_memory_dma_buf[] -include::VK_EXT_external_memory_dma_buf.txt[] -endif::VK_EXT_external_memory_dma_buf[] - -ifdef::VK_EXT_external_memory_host[] -include::VK_EXT_external_memory_host.txt[] -endif::VK_EXT_external_memory_host[] - -ifdef::VK_EXT_global_priority[] -include::VK_EXT_global_priority.txt[] -endif::VK_EXT_global_priority[] - -ifdef::VK_EXT_hdr_metadata[] -include::VK_EXT_hdr_metadata.txt[] -endif::VK_EXT_hdr_metadata[] - -ifdef::VK_EXT_post_depth_coverage[] -include::VK_EXT_post_depth_coverage.txt[] -endif::VK_EXT_post_depth_coverage[] - -ifdef::VK_EXT_queue_family_foreign[] -include::VK_EXT_queue_family_foreign.txt[] -endif::VK_EXT_queue_family_foreign[] - -ifdef::VK_EXT_sample_locations[] -include::VK_EXT_sample_locations.txt[] -endif::VK_EXT_sample_locations[] - -ifdef::VK_EXT_sampler_filter_minmax[] -include::VK_EXT_sampler_filter_minmax.txt[] -endif::VK_EXT_sampler_filter_minmax[] - -ifdef::VK_EXT_shader_stencil_export[] -include::VK_EXT_shader_stencil_export.txt[] -endif::VK_EXT_shader_stencil_export[] - -ifdef::VK_EXT_shader_subgroup_ballot[] -include::VK_EXT_shader_subgroup_ballot.txt[] -endif::VK_EXT_shader_subgroup_ballot[] - -ifdef::VK_EXT_shader_subgroup_vote[] -include::VK_EXT_shader_subgroup_vote.txt[] -endif::VK_EXT_shader_subgroup_vote[] - -ifdef::VK_EXT_shader_viewport_index_layer[] -include::VK_EXT_shader_viewport_index_layer.txt[] -endif::VK_EXT_shader_viewport_index_layer[] - -ifdef::VK_EXT_swapchain_colorspace[] -include::VK_EXT_swapchain_colorspace.txt[] -endif::VK_EXT_swapchain_colorspace[] - -ifdef::VK_EXT_validation_flags[] -include::VK_EXT_validation_flags.txt[] -endif::VK_EXT_validation_flags[] - -ifdef::VK_EXT_validation_cache[] -include::VK_EXT_validation_cache.txt[] -endif::VK_EXT_validation_cache[] - -ifdef::VK_EXT_vertex_attribute_divisor[] -include::VK_EXT_vertex_attribute_divisor.txt[] -endif::VK_EXT_vertex_attribute_divisor[] - -// :leveloffset: 1 - - -// == Advanced Micro Devices `AMD` Vendor Extensions -// -// :leveloffset: 2 - -ifdef::VK_AMD_buffer_marker[] -include::VK_AMD_buffer_marker.txt[] -endif::VK_AMD_buffer_marker[] - -ifdef::VK_AMD_draw_indirect_count[] -include::VK_AMD_draw_indirect_count.txt[] -endif::VK_AMD_draw_indirect_count[] - -ifdef::VK_AMD_gcn_shader[] -include::VK_AMD_gcn_shader.txt[] -endif::VK_AMD_gcn_shader[] - -ifdef::VK_AMD_gpu_shader_half_float[] -include::VK_AMD_gpu_shader_half_float.txt[] -endif::VK_AMD_gpu_shader_half_float[] - -ifdef::VK_AMD_gpu_shader_int16[] -include::VK_AMD_gpu_shader_int16.txt[] -endif::VK_AMD_gpu_shader_int16[] - -ifdef::VK_AMD_mixed_attachment_samples[] -include::VK_AMD_mixed_attachment_samples.txt[] -endif::VK_AMD_mixed_attachment_samples[] - -ifdef::VK_AMD_negative_viewport_height[] -include::VK_AMD_negative_viewport_height.txt[] -endif::VK_AMD_negative_viewport_height[] - -ifdef::VK_AMD_rasterization_order[] -include::VK_AMD_rasterization_order.txt[] -endif::VK_AMD_rasterization_order[] - -ifdef::VK_AMD_shader_ballot[] -include::VK_AMD_shader_ballot.txt[] -endif::VK_AMD_shader_ballot[] - -ifdef::VK_AMD_shader_core_properties[] -include::VK_AMD_shader_core_properties.txt[] -endif::VK_AMD_shader_core_properties[] - -ifdef::VK_AMD_shader_explicit_vertex_parameter[] -include::VK_AMD_shader_explicit_vertex_parameter.txt[] -endif::VK_AMD_shader_explicit_vertex_parameter[] - -ifdef::VK_AMD_shader_fragment_mask[] -include::VK_AMD_shader_fragment_mask.txt[] -endif::VK_AMD_shader_fragment_mask[] - -ifdef::VK_AMD_shader_image_load_store_lod[] -include::VK_AMD_shader_image_load_store_lod.txt[] -endif::VK_AMD_shader_image_load_store_lod[] - -ifdef::VK_AMD_shader_info[] -include::VK_AMD_shader_info.txt[] -endif::VK_AMD_shader_info[] - -ifdef::VK_AMD_shader_trinary_minmax[] -include::VK_AMD_shader_trinary_minmax.txt[] -endif::VK_AMD_shader_trinary_minmax[] - -ifdef::VK_AMD_texture_gather_bias_lod[] -include::VK_AMD_texture_gather_bias_lod.txt[] -endif::VK_AMD_texture_gather_bias_lod[] - -// :leveloffset: 1 - - -// == Android `ANDROID` Vendor Extensions -// -// :leveloffset: 2 - -ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] -include::VK_ANDROID_external_memory_android_hardware_buffer.txt[] -endif::VK_ANDROID_external_memory_android_hardware_buffer[] - -// :leveloffset: 1 - - -// == Google `GOOGLE` Vendor Extensions -// -// :leveloffset: 2 - -ifdef::VK_GOOGLE_display_timing[] -include::VK_GOOGLE_display_timing.txt[] -endif::VK_GOOGLE_display_timing[] - -// :leveloffset: 1 - - -// == Imagination `IMG` Vendor Extensions -// -// :leveloffset: 2 - -ifdef::VK_IMG_filter_cubic[] -include::VK_IMG_filter_cubic.txt[] -endif::VK_IMG_filter_cubic[] - -// :leveloffset: 1 - - -// == MoltenVK `MVK` Vendor Extensions -// -// :leveloffset: 2 - -ifdef::VK_MVK_ios_surface[] -include::VK_MVK_ios_surface.txt[] -endif::VK_MVK_ios_surface[] - -ifdef::VK_MVK_macos_surface[] -include::VK_MVK_macos_surface.txt[] -endif::VK_MVK_macos_surface[] - -// :leveloffset: 1 - - -// == Nintendo `NN` Vendor Extensions -// -// :leveloffset: 2 - -ifdef::VK_NN_vi_surface[] -include::VK_NN_vi_surface.txt[] -endif::VK_NN_vi_surface[] - - -// == NVIDIA `NV` Vendor Extensions -// -// :leveloffset: 2 - -ifdef::VK_NV_clip_space_w_scaling[] -include::VK_NV_clip_space_w_scaling.txt[] -endif::VK_NV_clip_space_w_scaling[] - -ifdef::VK_NV_dedicated_allocation[] -include::VK_NV_dedicated_allocation.txt[] -endif::VK_NV_dedicated_allocation[] - -ifdef::VK_NV_external_memory_capabilities[] -include::VK_NV_external_memory_capabilities.txt[] -endif::VK_NV_external_memory_capabilities[] - -ifdef::VK_NV_external_memory[] -include::VK_NV_external_memory.txt[] -endif::VK_NV_external_memory[] - -ifdef::VK_NV_external_memory_win32[] -include::VK_NV_external_memory_win32.txt[] -endif::VK_NV_external_memory_win32[] - -ifdef::VK_NV_fill_rectangle[] -include::VK_NV_fill_rectangle.txt[] -endif::VK_NV_fill_rectangle[] - -ifdef::VK_NV_fragment_coverage_to_color[] -include::VK_NV_fragment_coverage_to_color.txt[] -endif::VK_NV_fragment_coverage_to_color[] - -ifdef::VK_NV_framebuffer_mixed_samples[] -include::VK_NV_framebuffer_mixed_samples.txt[] -endif::VK_NV_framebuffer_mixed_samples[] - -ifdef::VK_NV_geometry_shader_passthrough[] -include::VK_NV_geometry_shader_passthrough.txt[] -endif::VK_NV_geometry_shader_passthrough[] - -ifdef::VK_NV_glsl_shader[] -include::VK_NV_glsl_shader.txt[] -endif::VK_NV_glsl_shader[] - -ifdef::VK_NV_sample_mask_override_coverage[] -include::VK_NV_sample_mask_override_coverage.txt[] -endif::VK_NV_sample_mask_override_coverage[] - -ifdef::VK_NV_shader_subgroup_partitioned[] -include::VK_NV_shader_subgroup_partitioned.txt[] -endif::VK_NV_shader_subgroup_partitioned[] - -ifdef::VK_NV_viewport_array2[] -include::VK_NV_viewport_array2.txt[] -endif::VK_NV_viewport_array2[] - -ifdef::VK_NV_viewport_swizzle[] -include::VK_NV_viewport_swizzle.txt[] -endif::VK_NV_viewport_swizzle[] - -ifdef::VK_NV_win32_keyed_mutex[] -include::VK_NV_win32_keyed_mutex.txt[] -endif::VK_NV_win32_keyed_mutex[] - -// :leveloffset: 1 - - -// == NVIDIA `NVX` Vendor Extensions -// -// :leveloffset: 2 - -ifdef::VK_NVX_device_generated_commands[] -include::VK_NVX_device_generated_commands.txt[] -endif::VK_NVX_device_generated_commands[] - -ifdef::VK_NVX_multiview_per_view_attributes[] -include::VK_NVX_multiview_per_view_attributes.txt[] -endif::VK_NVX_multiview_per_view_attributes[] - -// :leveloffset: 1 +include::meta/current_extensions_appendix.txt[] +include::meta/deprecated_extensions_appendix.txt[] diff --git a/appendices/versions.txt b/appendices/versions.txt index 1109563f..00416d66 100644 --- a/appendices/versions.txt +++ b/appendices/versions.txt @@ -28,31 +28,10 @@ ifdef::VK_VERSION_1_1[] [[versions-1.1]] == Version 1.1 +[[versions-1.1-promotions]] Vulkan Version 1.1 _promoted_ a number of key extensions into the core API: - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> - * <> +include::meta/promoted_extensions_VK_VERSION_1_1.txt[] The only changes to the functionality added by these extensions were to `VK_KHR_shader_draw_parameters`, which had a @@ -62,6 +41,7 @@ support in the core API, and pname:variablePointersStorageBuffer>> from `VK_KHR_variable_pointers` was made optional. +[[versions-1.1-new-features]] Additionally, Vulkan 1.1 added support for <>, <>, and a new diff --git a/xml/extensionmetadocgenerator.py b/xml/extensionmetadocgenerator.py index 46cbe97a..d2603be5 100644 --- a/xml/extensionmetadocgenerator.py +++ b/xml/extensionmetadocgenerator.py @@ -14,8 +14,9 @@ # See the License for the specific language governing permissions and # limitations under the License. -import os,re,sys +import os,re,sys,functools from generator import * +from functools import total_ordering # ExtensionMetaDocGeneratorOptions - subclass of GeneratorOptions. class ExtensionMetaDocGeneratorOptions(GeneratorOptions): @@ -37,16 +38,236 @@ class ExtensionMetaDocGeneratorOptions(GeneratorOptions): addExtensions, removeExtensions, emitExtensions, sortProcedure) +@total_ordering +class Extension: + def __init__(self, + generator, # needed for logging + filename, + name, + number, + type, + requires, + requiresCore, + contact, + promotedTo, + deprecatedBy, + obsoletedBy, + revision ): + self.generator = generator + self.filename = filename + self.name = name + self.number = number + self.type = type + self.requires = requires + self.requiresCore = requiresCore + self.contact = contact + self.promotedTo = promotedTo + self.deprecatedBy = deprecatedBy + self.obsoletedBy = obsoletedBy + self.revision = revision + + self.deprecationType = None + self.supercedingVkVersion = None + self.supercedingExtension = None + + if self.promotedTo is not None and self.deprecatedBy is not None and self.obsoletedBy is not None: + self.generator.logMsg('warn', 'All \'promotedto\', \'deprecatedby\' and \'obsoletedby\' attributes used on extension ' + self.name + '! Ignoring \'promotedto\' and \'deprecatedby\'.') + elif self.promotedTo is not None and self.deprecatedBy is not None: + self.generator.logMsg('warn', 'Both \'promotedto\' and \'deprecatedby\' attributes used on extension ' + self.name + '! Ignoring \'deprecatedby\'.') + elif self.promotedTo is not None and self.obsoletedBy is not None: + self.generator.logMsg('warn', 'Both \'promotedto\' and \'obsoletedby\' attributes used on extension ' + self.name + '! Ignoring \'promotedto\'.') + elif self.deprecatedBy is not None and self.obsoletedBy is not None: + self.generator.logMsg('warn', 'Both \'deprecatedby\' and \'obsoletedby\' attributes used on extension ' + self.name + '! Ignoring \'deprecatedby\'.') + + superceededBy = None + if self.promotedTo is not None: + self.deprecationType = 'promotion' + superceededBy = promotedTo + elif self.deprecatedBy is not None: + self.deprecationType = 'deprecation' + superceededBy = deprecatedBy + elif self.obsoletedBy is not None: + self.deprecationType = 'obsoletion' + superceededBy = obsoletedBy + + if superceededBy is not None: + if superceededBy == '' and not self.deprecationType == 'promotion': + pass # supercedingVkVersion, supercedingExtension == None + elif superceededBy.startswith('VK_VERSION_'): + self.supercedingVkVersion = superceededBy + elif superceededBy.startswith('VK_'): + self.supercedingExtension = superceededBy + else: + self.generator.logMsg('error', 'Unrecognized ' + self.deprecationType + ' attribute value \'' + superceededBy + '\'!') + + def __str__(self): return self.name + + def __eq__(self, other): return self.name == other.name + def __ne__(self, other): return self.name != other.name + def __lt__(self, other): + me_is_KHR = self.name.startswith( 'VK_KHR' ) + me_is_EXT = self.name.startswith( 'VK_EXT' ) + he_is_KHR = other.name.startswith( 'VK_KHR' ) + he_is_EXT = other.name.startswith( 'VK_EXT' ) + + swap = False + if me_is_KHR and not he_is_KHR: + return not swap + elif he_is_KHR and not me_is_KHR: + return swap + elif me_is_EXT and not he_is_EXT: + return not swap + elif he_is_EXT and not me_is_EXT: + return swap + else: + return self.name < other.name + + def typeToStr(self): + if self.type == 'instance': + return 'Instance extension' + elif self.type == 'device': + return 'Device extension' + elif self.type != None: + self.generator.logMsg('warn', 'The type attribute of ' + self.name + ' extension is neither \'instance\' nor \'device\'. That is invalid (at the time this script was written).') + write(' ' + type.capitalize(), file=fp) + else: # should be unreachable + self.generator.logMsg('error', 'Logic error in typeToStr(): Missing type attribute!') + + def conditionalLinkCoreVk(self, vulkanVersion, linkSuffix): + versionMatch = re.match(r'VK_VERSION_(\d+)_(\d+)', vulkanVersion) + major = versionMatch.group(1) + minor = versionMatch.group(2) + + dottedVersion = major + '.' + minor + + doc = 'ifdef::' + vulkanVersion + '[]\n' + doc += ' <>\n' + doc += 'endif::' + vulkanVersion + '[]\n' + doc += 'ifndef::' + vulkanVersion + '[]\n' + doc += ' Vulkan ' + dottedVersion + '\n' + doc += 'endif::' + vulkanVersion + '[]\n' + + return doc + + def conditionalLinkExt(self, extName, indent = ' '): + doc = 'ifdef::' + extName + '[]\n' + doc += indent + '<<' + extName + '>>\n' + doc += 'endif::' + extName + '[]\n' + doc += 'ifndef::' + extName + '[]\n' + doc += indent + '`' + extName + '`\n' + doc += 'endif::' + extName + '[]\n' + + return doc + + def resolveDeprecationChain(self, extensionsList, succeededBy, file): + ext = next(x for x in extensionsList if x.name == succeededBy) + + if ext.deprecationType: + if ext.deprecationType == 'promotion': + if ext.supercedingVkVersion: + write(' ** Which in turn was _promoted_ to\n' + ext.conditionalLinkCoreVk(ext.supercedingVkVersion, '-promotions'), file=file) + else: # ext.supercedingExtension + write(' ** Which in turn was _promoted_ to extension\n' + ext.conditionalLinkExt(ext.supercedingExtension), file=file) + ext.resolveDeprecationChain(extensionsList, ext.supercedingExtension, file) + elif ext.deprecationType == 'deprecation': + if ext.supercedingVkVersion: + write(' ** Which in turn was _deprecated_ by\n' + ext.conditionalLinkCoreVk(ext.supercedingVkVersion, '-new-feature'), file=file) + elif ext.supercedingExtension: + write(' ** Which in turn was _deprecated_ by\n' + ext.conditionalLinkExt(ext.supercedingExtension) + ' extension', file=file) + ext.resolveDeprecationChain(extensionsList, ext.supercedingExtension, file) + else: + write(' ** Which in turn was _deprecated_ without replacement', file=file) + elif ext.deprecationType == 'obsoletion': + if ext.supercedingVkVersion: + write(' ** Which in turn was _obsoleted_ by\n' + ext.conditionalLinkCoreVk(ext.supercedingVkVersion, '-new-feature'), file=file) + elif ext.supercedingExtension: + write(' ** Which in turn was _obsoleted_ by\n' + ext.conditionalLinkExt(ext.supercedingExtension) + ' extension', file=file) + ext.resolveDeprecationChain(extensionsList, ext.supercedingExtension, file) + else: + write(' ** Which in turn was _obsoleted_ without replacement', file=file) + else: # should be unreachable + self.generator.logMsg('error', 'Logic error in resolveDeprecationChain(): deprecationType is neither \'promotion\', \'deprecation\' nor \'obsoletion\'!') + + + def makeMetafile(self, extensionsList): + fp = self.generator.newFile(self.filename) + + write('[[' + self.name + ']]', file=fp) + write('=== ' + self.name, file=fp) + write('', file=fp) + + write('*Name String*::', file=fp) + write(' `' + self.name + '`', file=fp) + + write('*Extension Type*::', file=fp) + write(' ' + self.typeToStr(), file=fp) + + write('*Registered Extension Number*::', file=fp) + write(' ' + self.number, file=fp) + + write('*Revision*::', file=fp) + write(' ' + self.revision, file=fp) + + # Only Vulkan extension dependencies are coded in XML, others are explicit + write('*Extension and Version Dependencies*::', file=fp) + write(' * Requires Vulkan ' + self.requiresCore, file=fp) + if self.requires: + for dep in self.requires.split(','): + write(' * Requires `<<' + dep + '>>`', file=fp) + + if self.deprecationType: + write('*Deprecation state*::', file=fp) + + if self.deprecationType == 'promotion': + if self.supercedingVkVersion: + write(' * _Promoted_ to\n' + self.conditionalLinkCoreVk(self.supercedingVkVersion, '-promotions'), file=fp) + else: # ext.supercedingExtension + write(' * _Promoted_ to\n' + self.conditionalLinkExt(self.supercedingExtension) + ' extension', file=fp) + self.resolveDeprecationChain(extensionsList, self.supercedingExtension, fp) + elif self.deprecationType == 'deprecation': + if self.supercedingVkVersion: + write(' * _Deprecated_ by\n' + self.conditionalLinkCoreVk(self.supercedingVkVersion, '-new-features'), file=fp) + elif self.supercedingExtension: + write(' * _Deprecated_ by\n' + self.conditionalLinkExt(self.supercedingExtension) + ' extension' , file=fp) + self.resolveDeprecationChain(extensionsList, self.supercedingExtension, fp) + else: + write(' * _Deprecated_ without replacement' , file=fp) + elif self.deprecationType == 'obsoletion': + if self.supercedingVkVersion: + write(' * _Obsoleted_ by\n' + self.conditionalLinkCoreVk(self.supercedingVkVersion, '-new-features'), file=fp) + elif self.supercedingExtension: + write(' * _Obsoleted_ by\n' + self.conditionalLinkExt(self.supercedingExtension) + ' extension' , file=fp) + self.resolveDeprecationChain(extensionsList, self.supercedingExtension, fp) + else: + # TODO: Does not make sense to retroactively ban use of extensions from 1.0. + # Needs some tweaks to the semantics and this message, when such extension(s) occur. + write(' * _Obsoleted_ without replacement' , file=fp) + else: # should be unreachable + self.generator.logMsg('error', 'Logic error in makeMetafile(): deprecationType is neither \'promotion\', \'deprecation\' nor \'obsoletion\'!') + + write('*Contact*::', file=fp) + contacts = self.contact.split(',') + for c in contacts: + write(' * ' + c, file=fp) + + fp.close() + + # ExtensionMetaDocOutputGenerator - subclass of OutputGenerator. # Generates AsciiDoc includes with metainformation for the Vulkan extension # appendices. The fields used from tags in vk.xml are: # -# name extension name string -# number extension number (optional) -# type 'instance' | 'device' (optional) -# requires list of comma-separate requires Vulkan extensions (optional) -# requiresCore required core version of Vulkan (optional) -# contact name and github login or email address (optional) +# name extension name string +# number extension number (optional) +# contact name and github login or email address (optional) +# type 'instance' | 'device' (optional) +# requires list of comma-separate requires Vulkan extensions (optional) +# requiresCore required core version of Vulkan (optional) +# promotedTo extension or Vulkan version it was promoted to +# deprecatedBy extension or Vulkan version which deprecated this extension, +# or empty string if deprecated without replacement +# obsoletedBy extension or Vulkan version which obsoleted this extension, +# or empty string if obsoleted without replacement # # ---- methods ---- # ExtensionMetaDocOutputGenerator(errFile, warnFile, diagFile) - args as for @@ -63,96 +284,193 @@ class ExtensionMetaDocOutputGenerator(OutputGenerator): warnFile = sys.stderr, diagFile = sys.stdout): OutputGenerator.__init__(self, errFile, warnFile, diagFile) - # + self.extensions = [] + + def newFile(self, filename): + self.logMsg('diag', '# Generating include file:', filename) + fp = open(filename, 'w', encoding='utf-8') + write('// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry', file=fp) + return fp + def beginFile(self, genOpts): OutputGenerator.beginFile(self, genOpts) + + self.directory = self.genOpts.directory + + # Create subdirectory, if needed + self.makeDir(self.directory) + + def conditionalExt(self, extName, content, ifdef = None, condition = None): + doc = '' + + innerdoc = 'ifdef::' + extName + '[]\n' + innerdoc += content + '\n' + innerdoc += 'endif::' + extName + '[]\n' + + if ifdef: + if ifdef == 'ifndef': + doc += 'ifndef::' + condition + '[]\n' + doc += innerdoc + doc += 'endif::' + condition + '[]\n' + elif ifdef == 'ifdef': + doc += 'ifdef::' + condition + '+' + extName + '[]\n' + doc += content + '\n' + doc += 'endif::' + condition + '+' + extName + '[]\n' + else: # should be unreachable + self.generator.logMsg('error', 'Logic error in conditionalExt(): ifdef is neither \'ifdef \' nor \'ifndef\'!') + else: + doc += innerdoc + + return doc + def endFile(self): + self.extensions.sort() + + for ext in self.extensions: + ext.makeMetafile(self.extensions) + + promotedExtensions = {} + for ext in self.extensions: + if ext.deprecationType == 'promotion' and ext.supercedingVkVersion: + promotedExtensions.setdefault(ext.supercedingVkVersion, []).append(ext) + + for coreVersion, extensions in promotedExtensions.items(): + promoted_extensions_fp = self.newFile(self.directory + '/promoted_extensions_' + coreVersion + '.txt') + + for ext in extensions: + indent = '' + write(' * {blank}\n+\n' + ext.conditionalLinkExt(ext.name, indent), file=promoted_extensions_fp) + + promoted_extensions_fp.close() + + current_extensions_appendix_fp = self.newFile(self.directory + '/current_extensions_appendix.txt') + deprecated_extensions_appendix_fp = self.newFile(self.directory + '/deprecated_extensions_appendix.txt') + current_extension_appendices_fp = self.newFile(self.directory + '/current_extension_appendices.txt') + current_extension_appendices_toc_fp = self.newFile(self.directory + '/current_extension_appendices_toc.txt') + deprecated_extension_appendices_fp = self.newFile(self.directory + '/deprecated_extension_appendices.txt') + deprecated_extension_appendices_toc_fp = self.newFile(self.directory + '/deprecated_extension_appendices_toc.txt') + deprecated_extensions_guard_macro_fp = self.newFile(self.directory + '/deprecated_extensions_guard_macro.txt') + + write('include::deprecated_extensions_guard_macro.txt[]', file=current_extensions_appendix_fp) + write('', file=current_extensions_appendix_fp) + write('ifndef::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp) + write('[[extension-appendices-list]]', file=current_extensions_appendix_fp) + write('== List of Extensions', file=current_extensions_appendix_fp) + write('endif::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp) + write('ifdef::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp) + write('[[extension-appendices-list]]', file=current_extensions_appendix_fp) + write('== List of Current Extensions', file=current_extensions_appendix_fp) + write('endif::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp) + write('', file=current_extensions_appendix_fp) + write('include::current_extension_appendices_toc.txt[]', file=current_extensions_appendix_fp) + write('<<<', file=current_extensions_appendix_fp) + write('include::current_extension_appendices.txt[]', file=current_extensions_appendix_fp) + + write('include::deprecated_extensions_guard_macro.txt[]', file=deprecated_extensions_appendix_fp) + write('', file=deprecated_extensions_appendix_fp) + write('ifdef::HAS_DEPRECATED_EXTENSIONS[]', file=deprecated_extensions_appendix_fp) + write('[[deprecated-extension-appendices-list]]', file=deprecated_extensions_appendix_fp) + write('== List of Deprecated Extensions', file=deprecated_extensions_appendix_fp) + write('include::deprecated_extension_appendices_toc.txt[]', file=deprecated_extensions_appendix_fp) + write('<<<', file=deprecated_extensions_appendix_fp) + write('include::deprecated_extension_appendices.txt[]', file=deprecated_extensions_appendix_fp) + write('endif::HAS_DEPRECATED_EXTENSIONS[]', file=deprecated_extensions_appendix_fp) + + # add include guard to allow multiple includes + write('ifndef::DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]', file=deprecated_extensions_guard_macro_fp) + write(':DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD:\n', file=deprecated_extensions_guard_macro_fp) + + for ext in self.extensions: + include = 'include::../' + ext.name + '.txt[]' + link = ' * <<' + ext.name + '>>' + + if ext.deprecationType is None: + write(self.conditionalExt(ext.name, include), file=current_extension_appendices_fp) + write(self.conditionalExt(ext.name, link), file=current_extension_appendices_toc_fp) + else: + condition = ext.supercedingVkVersion if ext.supercedingVkVersion else ext.supercedingExtension + + write(self.conditionalExt(ext.name, include, 'ifndef', condition), file=current_extension_appendices_fp) + write(self.conditionalExt(ext.name, link, 'ifndef', condition), file=current_extension_appendices_toc_fp) + + write(self.conditionalExt(ext.name, include, 'ifdef', condition), file=deprecated_extension_appendices_fp) + write(self.conditionalExt(ext.name, link, 'ifdef', condition), file=deprecated_extension_appendices_toc_fp) + + write(self.conditionalExt(ext.name, ':HAS_DEPRECATED_EXTENSIONS:', 'ifdef', condition), file=deprecated_extensions_guard_macro_fp) + + current_extensions_appendix_fp.close() + deprecated_extensions_appendix_fp.close() + current_extension_appendices_fp.close() + current_extension_appendices_toc_fp.close() + deprecated_extension_appendices_fp.close() + deprecated_extension_appendices_toc_fp.close() + + write('endif::DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]', file=deprecated_extensions_guard_macro_fp) + deprecated_extensions_guard_macro_fp.close() + OutputGenerator.endFile(self) + def beginFeature(self, interface, emit): # Start processing in superclass OutputGenerator.beginFeature(self, interface, emit) - # These attributes must exist - name = interface.get('name') - if interface.tag != 'extension': - self.logMsg('diag', - 'beginFeature: ignoring non-extension feature', - name) + self.logMsg('diag', 'beginFeature: ignoring non-extension feature', self.featureName) return + # These attributes must exist + name = self.featureName + number = self.getAttrib(interface, 'number') + type = self.getAttrib(interface, 'type') + revision = self.getSpecVersion(interface, name) + # These attributes are optional - number = self.getAttrib(interface, 'number', 'UNKNOWN') - type = self.getAttrib(interface, 'type', None) - requires = self.getAttrib(interface, 'requires', None) - requiresCore = self.getAttrib(interface, 'requiresCore', '1.0') - contact = self.getAttrib(interface, 'contact', 'UNKNOWN') - revision = self.getSpecVersion(interface, name, 'UNKNOWN') + OPTIONAL = False + requires = self.getAttrib(interface, 'requires', OPTIONAL) + requiresCore = self.getAttrib(interface, 'requiresCore', OPTIONAL, '1.0') + contact = self.getAttrib(interface, 'contact', OPTIONAL) + promotedTo = self.getAttrib(interface, 'promotedto', OPTIONAL) + deprecatedBy = self.getAttrib(interface, 'deprecatedby', OPTIONAL) + obsoletedBy = self.getAttrib(interface, 'obsoletedby', OPTIONAL) - # Create subdirectory, if needed - directory = self.genOpts.directory - self.makeDir(directory) + filename = self.directory + '/' + name + '.txt' - # Create file - filename = directory + '/' + name + '.txt' - self.logMsg('diag', '# Generating include file:', filename) - fp = open(filename, 'w', encoding='utf-8') + self.extensions.append( Extension(self, filename, name, number, type, requires, requiresCore, contact, promotedTo, deprecatedBy, obsoletedBy, revision) ) - # Asciidoc anchor - write('// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry', file=fp) - write('[[' + name + ']]', file=fp) - write('== ' + name, file=fp) - write('', file=fp) - - write('*Name String*::', file=fp) - write(' `' + name + '`', file=fp) - - write('*Extension Type*::', file=fp) - if type == 'instance': - write(' Instance extension', file=fp) - elif type == 'device': - write(' Device extension', file=fp) - elif type != None: - write(' UNRECOGNIZED extension type: ' + type, file=fp) - else: - self.logMsg('warn', - 'ExtensionMetaInformation::beginFeature:', - 'required type attribute missing for extension', - name) - write(' UNKNOWN extension type (*this should never happen*)', file=fp) - - write('*Registered Extension Number*::', file=fp) - write(' ' + number, file=fp) - - write('*Revision*::', file=fp) - write(' ' + revision, file=fp) - - # @@ Need to determine *Revision*:: number from enum attributes - - # Only Vulkan extension dependencies are coded in XML, others are explicit - write('*Extension and Version Dependencies*::', file=fp) - write(' - Requires Vulkan ' + requiresCore, file=fp) - if requires != None: - for dep in requires.split(','): - write(' - Requires `<<' + dep + '>>`', file=fp) - - write('*Contact*::', file=fp) - write(' - ' + contact, file=fp) - - fp.close() def endFeature(self): # Finish processing in superclass OutputGenerator.endFeature(self) - # + # Query an attribute from an element, or return a default value # elem - element to query # attribute - attribute name + # required - whether attribute must exist # default - default value if attribute not present - def getAttrib(self, elem, attribute, default=None): - if attribute in elem.keys(): - return elem.get(attribute) - else: - return default + def getAttrib(self, elem, attribute, required=True, default=None): + attrib = elem.get(attribute, default) + if required and (attrib is None): + name = elem.get('name', 'UNKNOWN') + self.logMsg('error', 'While processing \'' + self.featureName + ', <' + elem.tag + '> \'' + name + '\' does not contain required attribute \'' + attribute + '\'') + return attrib + + def content(tag, ET): + return tag.text + ''.join(ET.tostring(e) for e in tag) + + def numbersToWords(self, name): + whitelist = ['WIN32', 'INT16'] + + # temporarily replace whitelist items + for i, w in enumerate(whitelist): + name = re.sub(w, '{' + str(i) + '}', name) + + name = re.sub(r'(?<=[A-Z])(\d+)(?![A-Z])', '_\g<1>', name) + + # undo whitelist substitution + for i, w in enumerate(whitelist): + name = re.sub('\\{' + str(i) + '}', w, name) + + return name + # # Determine the extension revision from the EXTENSION_NAME_SPEC_VERSION # enumerant. @@ -162,24 +480,18 @@ class ExtensionMetaDocOutputGenerator(OutputGenerator): # default - default value if SPEC_VERSION token not present def getSpecVersion(self, elem, extname, default=None): # The literal enumerant name to match - enumName = extname.upper() + '_SPEC_VERSION' - # A possible revision number if no literal match is found - specVersion = 'UNKNOWN' + versioningEnumName = self.numbersToWords(extname.upper()) + '_SPEC_VERSION' - for enum in elem.findall('.//enum'): - thisName = enum.get('name') - thisValue = self.getAttrib(enum, 'value', 'UNKNOWN') - if thisName == enumName: - # Exact match - specVersion = thisValue - break - elif thisName[-13:] == '_SPEC_VERSION': - self.logMsg('diag', - 'Potential name mismatch between extension', - extname, 'and version token', thisName) - specVersion = thisValue - # Otherwise, ignore the enum + for enum in elem.findall('./require/enum'): + enumName = self.getAttrib(enum, 'name') + if enumName == versioningEnumName: + return self.getAttrib(enum, 'value') - if specVersion == 'UNKNOWN': - print('UNKNOWN SPEC_VERSION for', extname) - return specVersion + #if not found: + for enum in elem.findall('./require/enum'): + enumName = self.getAttrib(enum, 'name') + if enumName.find('SPEC_VERSION') != -1: + self.logMsg('warn', 'Missing ' + versioningEnumName + '! Potential misnamed candidate ' + enumName + '.') + return self.getAttrib(enum, 'value') + + self.logMsg('error', 'Missing ' + versioningEnumName + '!') diff --git a/xml/vk.xml b/xml/vk.xml index 5ae506e4..f4c6aebd 100644 --- a/xml/vk.xml +++ b/xml/vk.xml @@ -6828,7 +6828,7 @@ server. - + @@ -6916,7 +6916,7 @@ server. - + @@ -6952,7 +6952,7 @@ server. - + @@ -7000,7 +7000,7 @@ server. - + @@ -7014,7 +7014,7 @@ server. - + @@ -7128,7 +7128,7 @@ server. - + @@ -7155,7 +7155,7 @@ server. - + @@ -7167,7 +7167,7 @@ server. - + @@ -7177,7 +7177,7 @@ server. - + @@ -7188,7 +7188,7 @@ server. - + @@ -7196,7 +7196,7 @@ server. - + @@ -7227,7 +7227,7 @@ server. - + @@ -7306,7 +7306,7 @@ server. - + @@ -7342,7 +7342,7 @@ server. - + @@ -7354,7 +7354,7 @@ server. - + @@ -7367,7 +7367,7 @@ server. - + @@ -7400,7 +7400,7 @@ server. - + @@ -7452,7 +7452,7 @@ server. - + @@ -7476,7 +7476,7 @@ server. - + @@ -7541,7 +7541,7 @@ server. - + @@ -7559,7 +7559,7 @@ server. - + @@ -7865,7 +7865,7 @@ server. - + @@ -7888,7 +7888,7 @@ server. - + @@ -7931,7 +7931,7 @@ server. - + @@ -7976,7 +7976,7 @@ server. - + @@ -8044,7 +8044,7 @@ server. - + @@ -8115,7 +8115,7 @@ server. - + @@ -8210,7 +8210,7 @@ server. - + @@ -8218,7 +8218,7 @@ server. - + @@ -8355,7 +8355,7 @@ server. - + @@ -8438,7 +8438,7 @@ server. - + @@ -8537,7 +8537,7 @@ server. - +