diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 42d8e7c2..75ae9cad 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -18,7 +18,7 @@ spec-generate: # number of them. This is a slightly crude way of enforcing "don't add # errors" but simpler than the alternatives (running against master, # diff, etc) - - xml/check_spec_links.py -Werror + - xml/check_spec_links.py -Werror --ignore_count 0 artifacts: when: always paths: diff --git a/ChangeLog.txt b/ChangeLog.txt index a92b6313..a90178c6 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -8,6 +8,61 @@ public pull requests that have been accepted. ----------------------------------------------------- +Change log for January 13, 2019 Vulkan 1.1.98 spec update: + + * Update release number to 98. + +Public Issues: + + * Fix missing markup in flink:vkDestroyPipelineLayout valid usage + statement (pull request 882). + * Add missing contributors for `<>` (public + pull request 891). + +Internal Issues: + + * Detect nested bullet points in valid usage blocks and warn about them + during VUID assignment (internal issue 1382). + * Update the style guide to document the process for reserving new bits in + bitmask types (internal issue 1411). + * Clarify for slink:VkApplicationInfo::pname:apiVersion and in the + <> section when it is valid for an application to use a certain + version of Vulkan API functionality (for an instance and for a + device/physical device); and when the validation layers must generate an + error (internal issue 1412). + * Add optional <> (internal + issue 1480). + * Add missing `returnedonly` tags for a number of returned extension + structures that can be passed in pname:pNext chains (internal issue + 1515). + * Clean up and rearrange some spec language for + slink:VkRenderPassCreateInfo and slink:VkAttachmentReference.txt + (internal issue 1522). + * Correctly round the code:OpVectorTimesScalar and + code:OpMatrixTimesScalar SPIR-V operations in the <> table (internal merge request 2996). + * Work around cases in flink:vkCmdBeginTransformFeedbackEXT, + flink:vkCmdEndTransformFeedbackEXT, and + slink:VkPipelineCoverageModulationStateCreateInfoNV where an array + parameter is `optional` but the length is not in `vk.xml`. This is an + interim fix using `noautovalidity` + handcoded VU replacing those that + should be autogenerated (internal issue 2944 and + https://github.com/KhronosGroup/Vulkan-ValidationLayers/issues/480). + * Remove redundant capability validation of the code:float16 and code:int8 + SPIR-V capabilities from the <> + section, since they are already covered in the preceding table. + * Update check_spec_links script, including validation for reference page + open blocks. Fix errors identified by the script. + +----------------------------------------------------- + Change log for January 05, 2019 Vulkan 1.1.97 spec update: * Update release number to 97. diff --git a/Makefile b/Makefile index ff192e5f..2f7bd81e 100644 --- a/Makefile +++ b/Makefile @@ -115,7 +115,7 @@ VERBOSE = # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -PATCHVERSION = 97 +PATCHVERSION = 98 ifneq (,$(findstring VK_VERSION_1_1,$(VERSIONS))) SPECREVISION = 1.1.$(PATCHVERSION) else diff --git a/appendices/VK_AMD_gcn_shader.txt b/appendices/VK_AMD_gcn_shader.txt index 868ed814..ff406b13 100644 --- a/appendices/VK_AMD_gcn_shader.txt +++ b/appendices/VK_AMD_gcn_shader.txt @@ -12,7 +12,7 @@ include::meta/VK_AMD_gcn_shader.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_gcn_shader.html[+SPV_AMD_gcn_shader+] + * https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_gcn_shader.html[`SPV_AMD_gcn_shader`] ifdef::editing-notes[] [NOTE] diff --git a/appendices/VK_AMD_gpu_shader_half_float.txt b/appendices/VK_AMD_gpu_shader_half_float.txt index 3f9e9959..e0b81fc1 100644 --- a/appendices/VK_AMD_gpu_shader_half_float.txt +++ b/appendices/VK_AMD_gpu_shader_half_float.txt @@ -14,7 +14,7 @@ include::meta/VK_AMD_gpu_shader_half_float.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_gpu_shader_half_float.html[+SPV_AMD_gpu_shader_half_float+] + * https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_gpu_shader_half_float.html[`SPV_AMD_gpu_shader_half_float`] ifdef::editing-notes[] [NOTE] diff --git a/appendices/VK_AMD_gpu_shader_int16.txt b/appendices/VK_AMD_gpu_shader_int16.txt index 218c5584..0f1a2931 100644 --- a/appendices/VK_AMD_gpu_shader_int16.txt +++ b/appendices/VK_AMD_gpu_shader_int16.txt @@ -6,7 +6,7 @@ include::meta/VK_AMD_gpu_shader_int16.txt[] No known IP claims. *Interactions and External Dependencies*:: - Requires the - https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_gpu_shader_int16.html[+SPV_AMD_gpu_shader_int16+] + https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_gpu_shader_int16.html[`SPV_AMD_gpu_shader_int16`] SPIR-V extension. *Contributors*:: - Daniel Rakos, AMD @@ -18,7 +18,7 @@ include::meta/VK_AMD_gpu_shader_int16.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * +SPV_AMD_gpu_shader_int16+ + * `SPV_AMD_gpu_shader_int16` === Version History diff --git a/appendices/VK_AMD_shader_ballot.txt b/appendices/VK_AMD_shader_ballot.txt index aa79a604..43f47751 100644 --- a/appendices/VK_AMD_shader_ballot.txt +++ b/appendices/VK_AMD_shader_ballot.txt @@ -14,7 +14,7 @@ include::meta/VK_AMD_shader_ballot.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_shader_ballot.html[+SPV_AMD_shader_ballot+] + * https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_shader_ballot.html[`SPV_AMD_shader_ballot`] ifdef::editing-notes[] [NOTE] diff --git a/appendices/VK_AMD_shader_core_properties.txt b/appendices/VK_AMD_shader_core_properties.txt index e2289d09..c9251d40 100644 --- a/appendices/VK_AMD_shader_core_properties.txt +++ b/appendices/VK_AMD_shader_core_properties.txt @@ -9,7 +9,7 @@ include::meta/VK_AMD_shader_core_properties.txt[] - Matthaeus Chajdas, AMD This extension exposes shader core properties for a target physical device -through the VK_KHR_get_physical_device_properties2 extension. +through the `<>` extension. Please refer to the example below for proper usage. === New Object Types diff --git a/appendices/VK_AMD_shader_explicit_vertex_parameter.txt b/appendices/VK_AMD_shader_explicit_vertex_parameter.txt index 00e32749..7598266f 100644 --- a/appendices/VK_AMD_shader_explicit_vertex_parameter.txt +++ b/appendices/VK_AMD_shader_explicit_vertex_parameter.txt @@ -13,7 +13,7 @@ include::meta/VK_AMD_shader_explicit_vertex_parameter.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_shader_explicit_vertex_parameter.html[+SPV_AMD_shader_explicit_vertex_parameter+] + * https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_shader_explicit_vertex_parameter.html[`SPV_AMD_shader_explicit_vertex_parameter`] ifdef::editing-notes[] [NOTE] diff --git a/appendices/VK_AMD_shader_fragment_mask.txt b/appendices/VK_AMD_shader_fragment_mask.txt index 1dc22eea..2ad07e24 100644 --- a/appendices/VK_AMD_shader_fragment_mask.txt +++ b/appendices/VK_AMD_shader_fragment_mask.txt @@ -6,7 +6,7 @@ include::meta/VK_AMD_shader_fragment_mask.txt[] No known IP claims. *Dependencies*:: - Requires the - https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_shader_fragment_mask.html[+SPV_AMD_shader_fragment_mask+] + https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_shader_fragment_mask.html[`SPV_AMD_shader_fragment_mask`] SPIR-V extension. *Contributors*:: - Aaron Hagan, AMD diff --git a/appendices/VK_AMD_shader_image_load_store_lod.txt b/appendices/VK_AMD_shader_image_load_store_lod.txt index 9d3b8bb4..260135d3 100644 --- a/appendices/VK_AMD_shader_image_load_store_lod.txt +++ b/appendices/VK_AMD_shader_image_load_store_lod.txt @@ -4,10 +4,10 @@ include::meta/VK_AMD_shader_image_load_store_lod.txt[] 2017-08-21 *Interactions and External Dependencies*:: - This extension requires the - https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_shader_image_load_store_lod.html[+SPV_AMD_shader_image_load_store_lod+] + https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_shader_image_load_store_lod.html[`SPV_AMD_shader_image_load_store_lod`] SPIR-V extension. - This extension requires - https://www.khronos.org/registry/OpenGL/extensions/AMD/AMD_shader_image_load_store_lod.txt[+GL_AMD_shader_image_load_store_lod+] + https://www.khronos.org/registry/OpenGL/extensions/AMD/AMD_shader_image_load_store_lod.txt[`GL_AMD_shader_image_load_store_lod`] for GLSL-based source languages. *IP Status*:: No known IP claims. @@ -18,7 +18,7 @@ include::meta/VK_AMD_shader_image_load_store_lod.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_shader_image_load_store_lod.html[+SPV_AMD_shader_image_load_store_lod+] + * https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_shader_image_load_store_lod.html[`SPV_AMD_shader_image_load_store_lod`] === Version History diff --git a/appendices/VK_AMD_shader_trinary_minmax.txt b/appendices/VK_AMD_shader_trinary_minmax.txt index 77050d1f..5836708d 100644 --- a/appendices/VK_AMD_shader_trinary_minmax.txt +++ b/appendices/VK_AMD_shader_trinary_minmax.txt @@ -13,7 +13,7 @@ include::meta/VK_AMD_shader_trinary_minmax.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_shader_trinary_minmax.html[+SPV_AMD_shader_trinary_minmax+] + * https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_shader_trinary_minmax.html[`SPV_AMD_shader_trinary_minmax`] ifdef::editing-notes[] [NOTE] diff --git a/appendices/VK_AMD_texture_gather_bias_lod.txt b/appendices/VK_AMD_texture_gather_bias_lod.txt index 55d51bc2..bd739c41 100644 --- a/appendices/VK_AMD_texture_gather_bias_lod.txt +++ b/appendices/VK_AMD_texture_gather_bias_lod.txt @@ -6,7 +6,7 @@ include::meta/VK_AMD_texture_gather_bias_lod.txt[] No known IP claims. *Interactions and External Dependencies*:: - Requires the - https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_texture_gather_bias_lod.html[+SPV_AMD_texture_gather_bias_lod+] + https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_texture_gather_bias_lod.html[`SPV_AMD_texture_gather_bias_lod`] SPIR-V extension. *Contributors*:: - Dominik Witczak, AMD @@ -21,7 +21,7 @@ This extension adds two related features. Firstly, support for the following SPIR-V extension in Vulkan is added: - * +SPV_AMD_texture_gather_bias_lod+ + * `SPV_AMD_texture_gather_bias_lod` Secondly, the extension allows the application to query which formats can be used together with the new function prototypes introduced by the SPIR-V diff --git a/appendices/VK_ANDROID_external_memory_android_hardware_buffer.txt b/appendices/VK_ANDROID_external_memory_android_hardware_buffer.txt index 42e70e3e..7a120c4f 100644 --- a/appendices/VK_ANDROID_external_memory_android_hardware_buffer.txt +++ b/appendices/VK_ANDROID_external_memory_android_hardware_buffer.txt @@ -14,16 +14,16 @@ include::meta/VK_ANDROID_external_memory_android_hardware_buffer.txt[] - Matthew Netsch, Qualcomm - Andrew Garrard, Samsung -This extension enables an application to import Android code:AHardwareBuffer -objects created outside of the Vulkan device into Vulkan memory objects, -where they can: be bound to images and buffers. -It also allows exporting an code:AHardwareBuffer from a Vulkan memory object -for symmetry with other operating systems. -But since not all code:AHardwareBuffer usages and formats have Vulkan +This extension enables an application to import Android +dlink:AHardwareBuffer objects created outside of the Vulkan device into +Vulkan memory objects, where they can: be bound to images and buffers. +It also allows exporting an dlink:AHardwareBuffer from a Vulkan memory +object for symmetry with other operating systems. +But since not all dlink:AHardwareBuffer usages and formats have Vulkan equivalents, exporting from Vulkan provides strictly less functionality than -creating the code:AHardwareBuffer externally and importing it. +creating the dlink:AHardwareBuffer externally and importing it. -Some code:AHardwareBuffer images have implementation-defined _external +Some dlink:AHardwareBuffer images have implementation-defined _external formats_ that may: not correspond to Vulkan formats. Sampler Y'C~b~C~r~ conversion can: be used to sample from these images and convert them to a known color space. @@ -68,7 +68,7 @@ None. 1) Other external memory objects are represented as weakly-typed handles (e.g. Win32 code:HANDLE or POSIX file descriptor), and require a handle type parameter along with handles. -code:AHardwareBuffer is strongly typed, so naming the handle type is +dlink:AHardwareBuffer is strongly typed, so naming the handle type is redundant. Does symmetry justify adding handle type parameters/fields anyway? @@ -77,10 +77,10 @@ The handle type is already provided in places that treat external memory objects generically. In the places we would add it, the application code that would have to provide the handle type value is already dealing with -code:AHardwareBuffer-specific commands/structures; the extra symmetry would +dlink:AHardwareBuffer-specific commands/structures; the extra symmetry would not be enough to make that code generic. -2) The internal layout and therefore size of a code:AHardwareBuffer image +2) The internal layout and therefore size of a dlink:AHardwareBuffer image may depend on native usage flags that do not have corresponding Vulkan counterparts. Do we provide this info to flink:vkCreateImage somehow, or allow the @@ -90,7 +90,7 @@ approximate? *RESOLVED*: Allow the allocation size to be unspecified when allocating the memory. It has to work this way for exported image memory anyway, since -code:AHardwareBuffer allocation happens in flink:vkAllocateMemory, and +dlink:AHardwareBuffer allocation happens in flink:vkAllocateMemory, and internally is performed by a separate HAL, not the Vulkan implementation itself. There is a similar issue with flink:vkGetImageSubresourceLayout: the layout @@ -114,7 +114,7 @@ Implementations are encouraged to minimize differences as much as possible without causing compatibility problems for existing OpenGL ES applications or violating Vulkan requirements. -4) Should an code:AHardwareBuffer with code:AHARDWAREBUFFER_USAGE_CPU_* +4) Should an dlink:AHardwareBuffer with code:AHARDWAREBUFFER_USAGE_CPU_* usage be mappable in Vulkan? Should it be possible to export an code:AHardwareBuffers with such usage? @@ -132,11 +132,11 @@ view of the data and does not imply ownership (this means implementations must not internally call code:AHardwareBuffer_lock to implement flink:vkMapMemory, or assume the application has done so). Implementations are not required to support linear-tiled images backed by -Android hardware buffers, even if the code:AHardwareBuffer has CPU usage. +Android hardware buffers, even if the dlink:AHardwareBuffer has CPU usage. There is no reliable way to allocate memory in Vulkan that can be exported -to a code:AHardwareBuffer with CPU usage. +to a dlink:AHardwareBuffer with CPU usage. -5) Android may add new code:AHardwareBuffer formats and usage flags over +5) Android may add new dlink:AHardwareBuffer formats and usage flags over time. Can reference to them be added to this extension, or do they need a new extension? @@ -147,9 +147,9 @@ No new Vulkan features or implementation requirements can be added. The extension version number will be incremented when this additional documentation is added, but the version number does not indicate that an implementaiton supports Vulkan memory or resources that map to the new -code:AHardwareBuffer features: support for that must be queried with +dlink:AHardwareBuffer features: support for that must be queried with flink:vkGetPhysicalDeviceImageFormatProperties2 or is implied by -successfully allocating a code:AHardwareBuffer outside of Vulkan that uses +successfully allocating a dlink:AHardwareBuffer outside of Vulkan that uses the new feature and has a GPU usage flag. In essence, these are new features added to a new Android API level, rather diff --git a/appendices/VK_EXT_astc_decode_mode.txt b/appendices/VK_EXT_astc_decode_mode.txt index 0b0233cd..76beb01a 100644 --- a/appendices/VK_EXT_astc_decode_mode.txt +++ b/appendices/VK_EXT_astc_decode_mode.txt @@ -77,7 +77,8 @@ None. === Example -Create an image view that decodes to VK_FORMAT_R8G8B8A8_UNORM precision: +Create an image view that decodes to ename:VK_FORMAT_R8G8B8A8_UNORM +precision: [source,c++] ---------------------------------------- diff --git a/appendices/VK_EXT_buffer_device_address.txt b/appendices/VK_EXT_buffer_device_address.txt index 3946bc33..d55957f1 100644 --- a/appendices/VK_EXT_buffer_device_address.txt +++ b/appendices/VK_EXT_buffer_device_address.txt @@ -14,9 +14,9 @@ include::meta/VK_EXT_buffer_device_address.txt[] This extension allows the application to query a 64-bit buffer device address value for a buffer, which can be used to access the buffer memory via the code:PhysicalStorageBufferEXT storage class in the -https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GL_EXT_buffer_reference.txt[+GL_EXT_buffer_reference+] +https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference.txt[`GL_EXT_buffer_reference`] GLSL extension and -http://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/EXT/SPV_EXT_physical_storage_buffer.html[+SPV_EXT_physical_storage_buffer+] +http://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/EXT/SPV_EXT_physical_storage_buffer.html[`SPV_EXT_physical_storage_buffer`] SPIR-V extension. It also allows buffer device addresses to be provided by a trace replay diff --git a/appendices/VK_EXT_descriptor_indexing.txt b/appendices/VK_EXT_descriptor_indexing.txt index 9ef69a2b..5cdcd6d0 100644 --- a/appendices/VK_EXT_descriptor_indexing.txt +++ b/appendices/VK_EXT_descriptor_indexing.txt @@ -17,7 +17,7 @@ their resources, and selecting amongst those resources with dynamic There are feature enables and SPIR-V capabilities for non-uniform descriptor indexing in the shader, and non-uniform indexing in the shader requires use of a new code:NonUniformEXT decoration defined in the -+SPV_EXT_descriptor_indexing+ SPIR-V extension. +`SPV_EXT_descriptor_indexing` SPIR-V extension. There are descriptor set layout binding creation flags enabling several features: @@ -33,7 +33,7 @@ features: submission is executing. * The final binding in a descriptor set layout can have a variable size (and unsized arrays of resources are allowed in the - +GL_EXT_nonuniform_qualifier+ and +SPV_EXT_descriptor_indexing+ + `GL_EXT_nonuniform_qualifier` and `SPV_EXT_descriptor_indexing` extensions). Note that it is valid for multiple descriptor arrays in a shader to use the diff --git a/appendices/VK_EXT_external_memory_dma_buf.txt b/appendices/VK_EXT_external_memory_dma_buf.txt index 90c57cec..8dd61224 100644 --- a/appendices/VK_EXT_external_memory_dma_buf.txt +++ b/appendices/VK_EXT_external_memory_dma_buf.txt @@ -28,16 +28,16 @@ create slink:VkBuffer objects that can: be bound to that memory. produced image, specify the memory layout (such as row pitch and DRM format modifier) of the slink:VkImage? In other words, how does the application achieve behavior comparable to that provided by - https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt[EGL_EXT_image_dma_buf_import] + https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt[`EGL_EXT_image_dma_buf_import`] and - https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt[EGL_EXT_image_dma_buf_import_modifiers]? + https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt[`EGL_EXT_image_dma_buf_import_modifiers`]? + -- *RESOLVED*. Features comparable to those in -https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt[EGL_EXT_image_dma_buf_import] +https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt[`EGL_EXT_image_dma_buf_import`] and -https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt[EGL_EXT_image_dma_buf_import_modifiers] +https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt[`EGL_EXT_image_dma_buf_import_modifiers`] will be provided by an extension layered atop this one. -- diff --git a/appendices/VK_EXT_fragment_density_map.txt b/appendices/VK_EXT_fragment_density_map.txt index e6013ba8..d13ceed3 100644 --- a/appendices/VK_EXT_fragment_density_map.txt +++ b/appendices/VK_EXT_fragment_density_map.txt @@ -4,7 +4,7 @@ include::meta/VK_EXT_fragment_density_map.txt[] 2018-09-25 *Interactions and External Dependencies*:: - This extension requires the - https://www.khronos.org/registry/spir-v/extensions/EXT/SPV_EXT_fragment_invocation_density.html[+SPV_EXT_fragment_invocation_density+] + https://www.khronos.org/registry/spir-v/extensions/EXT/SPV_EXT_fragment_invocation_density.html[`SPV_EXT_fragment_invocation_density`] SPIR-V extension. *Contributors*:: - Matthew Netsch, Qualcomm Technologies, Inc. diff --git a/appendices/VK_EXT_image_drm_format_modifier.txt b/appendices/VK_EXT_image_drm_format_modifier.txt index 43e528f5..ce210452 100644 --- a/appendices/VK_EXT_image_drm_format_modifier.txt +++ b/appendices/VK_EXT_image_drm_format_modifier.txt @@ -309,7 +309,7 @@ Beginning in Linux 4.10, the kernel requires that the application provide the same DRM format _modifier_ for each plane. (See Linux commit https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=bae781b259269590109e8a4a8227331362b88212[bae781b259269590109e8a4a8227331362b88212]). -And GBM provides an entrypoint, ftext:gbm_bo_get_modifier, for querying the +And GBM provides an entrypoint, code:gbm_bo_get_modifier, for querying the _modifier_ of the image but does not provide one to query the modifier of individual planes. -- @@ -443,16 +443,16 @@ _requires_ the application to set pname:size to 0. ==== References . [[VK_EXT_image_drm_format_modifier-fn1]] - https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt[EGL_EXT_image_dma_buf_import] + https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt[`EGL_EXT_image_dma_buf_import`] . [[VK_EXT_image_drm_format_modifier-fn2]] - https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt[EGL_EXT_image_dma_buf_import_modifiers] + https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt[`EGL_EXT_image_dma_buf_import_modifiers`] . [[VK_EXT_image_drm_format_modifier-fn3]] - https://www.khronos.org/registry/EGL/extensions/MESA/EGL_MESA_image_dma_buf_export.txt[EGL_MESA_image_dma_buf_export] + https://www.khronos.org/registry/EGL/extensions/MESA/EGL_MESA_image_dma_buf_export.txt[`EGL_MESA_image_dma_buf_export`] . [[VK_EXT_image_drm_format_modifier-fn4]] - https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/drm/drm_mode.h?id=refs/tags/v4.10#n392[struct - drm_mode_fb_cmd2] + https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/drm/drm_mode.h?id=refs/tags/v4.10#n392[`struct + drm_mode_fb_cmd2`] . [[VK_EXT_image_drm_format_modifier-fn5]] - https://cgit.freedesktop.org/mesa/mesa/tree/src/gbm/main/gbm.h?id=refs/tags/mesa-18.0.0-rc1[gbm.h] + https://cgit.freedesktop.org/mesa/mesa/tree/src/gbm/main/gbm.h?id=refs/tags/mesa-18.0.0-rc1[`gbm.h`] ==== Version History diff --git a/appendices/VK_EXT_post_depth_coverage.txt b/appendices/VK_EXT_post_depth_coverage.txt index f99d2a14..da9bccae 100644 --- a/appendices/VK_EXT_post_depth_coverage.txt +++ b/appendices/VK_EXT_post_depth_coverage.txt @@ -4,19 +4,19 @@ include::meta/VK_EXT_post_depth_coverage.txt[] 2017-07-17 *Interactions and External Dependencies*:: - This extension requires the - https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_post_depth_coverage.html[+SPV_KHR_post_depth_coverage+] + https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_post_depth_coverage.html[`SPV_KHR_post_depth_coverage`] SPIR-V extension. - This extension requires - https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_post_depth_coverage.txt[+GL_ARB_post_depth_coverage+] + https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_post_depth_coverage.txt[`GL_ARB_post_depth_coverage`] or - https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_post_depth_coverage.txt[+GL_EXT_post_depth_coverage+] + https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_post_depth_coverage.txt[`GL_EXT_post_depth_coverage`] for GLSL-based source languages. *Contributors*:: - Jeff Bolz, NVIDIA This extension adds support for the following SPIR-V extension in Vulkan: - * +SPV_KHR_post_depth_coverage+ + * `SPV_KHR_post_depth_coverage` which allows the fragment shader to control whether values in the code:SampleMask built-in input variable reflect the coverage after the diff --git a/appendices/VK_EXT_shader_stencil_export.txt b/appendices/VK_EXT_shader_stencil_export.txt index e181e139..78e6e3c0 100644 --- a/appendices/VK_EXT_shader_stencil_export.txt +++ b/appendices/VK_EXT_shader_stencil_export.txt @@ -6,7 +6,7 @@ include::meta/VK_EXT_shader_stencil_export.txt[] No known IP claims. *Interactions and External Dependencies*:: - Requires the - https://www.khronos.org/registry/spir-v/extensions/EXT/SPV_EXT_shader_stencil_export.html[+SPV_EXT_shader_stencil_export+] + https://www.khronos.org/registry/spir-v/extensions/EXT/SPV_EXT_shader_stencil_export.html[`SPV_EXT_shader_stencil_export`] SPIR-V extension. *Contributors*:: - Dominik Witczak, AMD @@ -14,7 +14,7 @@ include::meta/VK_EXT_shader_stencil_export.txt[] - Rex Xu, AMD This extension adds support for the SPIR-V extension -+SPV_EXT_shader_stencil_export+, providing a mechanism whereby a shader may +`SPV_EXT_shader_stencil_export`, providing a mechanism whereby a shader may generate the stencil reference value per invocation. When stencil testing is enabled, this allows the test to be performed against the value generated in the shader. diff --git a/appendices/VK_EXT_shader_subgroup_ballot.txt b/appendices/VK_EXT_shader_subgroup_ballot.txt index 13dccbe4..a484f683 100644 --- a/appendices/VK_EXT_shader_subgroup_ballot.txt +++ b/appendices/VK_EXT_shader_subgroup_ballot.txt @@ -6,10 +6,10 @@ include::meta/VK_EXT_shader_subgroup_ballot.txt[] No known IP claims. *Interactions and External Dependencies*:: - This extension requires the - https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_shader_ballot.html[+SPV_KHR_shader_ballot+] + https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_shader_ballot.html[`SPV_KHR_shader_ballot`] SPIR-V extension. - This extension requires the - https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_shader_ballot.txt[+GL_ARB_shader_ballot+] + https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_shader_ballot.txt[`GL_ARB_shader_ballot`] extension for GLSL source languages. *Contributors*:: - Jeff Bolz, NVIDIA @@ -18,7 +18,7 @@ include::meta/VK_EXT_shader_subgroup_ballot.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * +SPV_KHR_shader_ballot+ + * `SPV_KHR_shader_ballot` This extension provides the ability for a group of invocations, which execute in parallel, to do limited forms of cross-invocation communication diff --git a/appendices/VK_EXT_shader_subgroup_vote.txt b/appendices/VK_EXT_shader_subgroup_vote.txt index 73f9cb51..796837cd 100644 --- a/appendices/VK_EXT_shader_subgroup_vote.txt +++ b/appendices/VK_EXT_shader_subgroup_vote.txt @@ -6,10 +6,10 @@ include::meta/VK_EXT_shader_subgroup_vote.txt[] No known IP claims. *Interactions and External Dependencies*:: - This extension requires the - https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_subgroup_vote.html[+SPV_KHR_subgroup_vote+] + https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_subgroup_vote.html[`SPV_KHR_subgroup_vote`] SPIR-V extension. - This extension requires the - https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_shader_group_vote.txt[+GL_ARB_shader_group_vote+] + https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_shader_group_vote.txt[`GL_ARB_shader_group_vote`] extension for GLSL source languages. *Contributors*:: - Neil Henning, Codeplay @@ -17,7 +17,7 @@ include::meta/VK_EXT_shader_subgroup_vote.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * +SPV_KHR_subgroup_vote+ + * `SPV_KHR_subgroup_vote` This extension provides new SPIR-V instructions: diff --git a/appendices/VK_EXT_shader_viewport_index_layer.txt b/appendices/VK_EXT_shader_viewport_index_layer.txt index d859fc75..c01f9d5a 100644 --- a/appendices/VK_EXT_shader_viewport_index_layer.txt +++ b/appendices/VK_EXT_shader_viewport_index_layer.txt @@ -4,14 +4,14 @@ include::meta/VK_EXT_shader_viewport_index_layer.txt[] 2017-08-08 *Interactions and External Dependencies*:: - This extension requires the - https://www.khronos.org/registry/spir-v/extensions/EXT/SPV_EXT_shader_viewport_index_layer.html[+SPV_EXT_shader_viewport_index_layer+] + https://www.khronos.org/registry/spir-v/extensions/EXT/SPV_EXT_shader_viewport_index_layer.html[`SPV_EXT_shader_viewport_index_layer`] SPIR-V extension. - This extension requires the - https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_shader_viewport_layer_array.txt[+GL_ARB_shader_viewport_layer_array+], - https://www.khronos.org/registry/OpenGL/extensions/AMD/AMD_vertex_shader_layer.txt[+GL_AMD_vertex_shader_layer+], - https://www.khronos.org/registry/OpenGL/extensions/AMD/AMD_vertex_shader_viewport_index.txt[+GL_AMD_vertex_shader_viewport_index+], + https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_shader_viewport_layer_array.txt[`GL_ARB_shader_viewport_layer_array`], + https://www.khronos.org/registry/OpenGL/extensions/AMD/AMD_vertex_shader_layer.txt[`GL_AMD_vertex_shader_layer`], + https://www.khronos.org/registry/OpenGL/extensions/AMD/AMD_vertex_shader_viewport_index.txt[`GL_AMD_vertex_shader_viewport_index`], or - https://www.khronos.org/registry/OpenGL/extensions/NV/NV_viewport_array2.txt[+GL_NV_viewport_array2+] + https://www.khronos.org/registry/OpenGL/extensions/NV/NV_viewport_array2.txt[`GL_NV_viewport_array2`] extensions for GLSL source languages. - This extension requires the pname:multiViewport feature. - This extension interacts with the pname:tessellationShader feature. @@ -23,7 +23,7 @@ include::meta/VK_EXT_shader_viewport_index_layer.txt[] - Slawomir Grajeswki, Intel This extension adds support for the code:ShaderViewportIndexLayerEXT -capability from the +SPV_EXT_shader_viewport_index_layer+ extension in +capability from the `SPV_EXT_shader_viewport_index_layer` extension in Vulkan. This extension allows variables decorated with the code:Layer and @@ -34,9 +34,9 @@ When using GLSL source-based shading languages, the code:gl_ViewportIndex and code:gl_Layer built-in variables map to the SPIR-V code:ViewportIndex and code:Layer built-in decorations, respectively. Behaviour of these variables is extended as described in the -+GL_ARB_shader_viewport_layer_array+ (or the precursor -+GL_AMD_vertex_shader_layer+, +GL_AMD_vertex_shader_viewport_index+, and -+GL_NV_viewport_array2 extensions+). +`GL_ARB_shader_viewport_layer_array` (or the precursor +`GL_AMD_vertex_shader_layer`, `GL_AMD_vertex_shader_viewport_index`, and +`GL_NV_viewport_array2` extensions). ifdef::VK_NV_viewport_array2[] [NOTE] diff --git a/appendices/VK_GOOGLE_decorate_string.txt b/appendices/VK_GOOGLE_decorate_string.txt index 75e39422..1113e7a3 100644 --- a/appendices/VK_GOOGLE_decorate_string.txt +++ b/appendices/VK_GOOGLE_decorate_string.txt @@ -6,7 +6,7 @@ include::meta/VK_GOOGLE_decorate_string.txt[] No known IP claims. *Interactions and External Dependencies*:: - Requires the - https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/GOOGLE/SPV_GOOGLE_decorate_string.asciidoc[+SPV_GOOGLE_decorate_string+] + https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/GOOGLE/SPV_GOOGLE_decorate_string.asciidoc[`SPV_GOOGLE_decorate_string`] SPIR-V extension. *Contributors*:: - Hai Nguyen, Google diff --git a/appendices/VK_GOOGLE_hlsl_functionality1.txt b/appendices/VK_GOOGLE_hlsl_functionality1.txt index 597d3d70..d05ef7c4 100644 --- a/appendices/VK_GOOGLE_hlsl_functionality1.txt +++ b/appendices/VK_GOOGLE_hlsl_functionality1.txt @@ -6,7 +6,7 @@ include::meta/VK_GOOGLE_hlsl_functionality1.txt[] No known IP claims. *Interactions and External Dependencies*:: - Requires the - https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/GOOGLE/SPV_GOOGLE_hlsl_functionality1.asciidoc[+SPV_GOOGLE_hlsl_functionality1+] + https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/GOOGLE/SPV_GOOGLE_hlsl_functionality1.asciidoc[`SPV_GOOGLE_hlsl_functionality1`] SPIR-V extension. *Contributors*:: - Hai Nguyen, Google diff --git a/appendices/VK_KHR_16bit_storage.txt b/appendices/VK_KHR_16bit_storage.txt index c9af3362..cd24003d 100644 --- a/appendices/VK_KHR_16bit_storage.txt +++ b/appendices/VK_KHR_16bit_storage.txt @@ -10,7 +10,7 @@ include::meta/VK_KHR_16bit_storage.txt[] No known IP claims. *Interactions and External Dependencies*:: - This extension requires - https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_16bit_storage.html[+SPV_KHR_16bit_storage+] + https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_16bit_storage.html[`SPV_KHR_16bit_storage`] - Promoted to Vulkan 1.1 Core *Contributors*:: - Alexander Galazin, ARM diff --git a/appendices/VK_KHR_8bit_storage.txt b/appendices/VK_KHR_8bit_storage.txt index eef7b970..eeec410b 100644 --- a/appendices/VK_KHR_8bit_storage.txt +++ b/appendices/VK_KHR_8bit_storage.txt @@ -10,7 +10,7 @@ include::meta/VK_KHR_8bit_storage.txt[] No known IP claims. *Interactions and External Dependencies*:: - This extension requires - https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_8bit_storage.html[+SPV_KHR_8bit_storage+] + https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_8bit_storage.html[`SPV_KHR_8bit_storage`] *Contributors*:: - Alexander Galazin, Arm diff --git a/appendices/VK_KHR_android_surface.txt b/appendices/VK_KHR_android_surface.txt index 9096fdc4..1e595076 100644 --- a/appendices/VK_KHR_android_surface.txt +++ b/appendices/VK_KHR_android_surface.txt @@ -28,10 +28,10 @@ include::meta/VK_KHR_android_surface.txt[] The `VK_KHR_android_surface` extension is an instance extension. It provides a mechanism to create a slink:VkSurfaceKHR object (defined by -the `<>` extension) that refers to an code:ANativeWindow, +the `<>` extension) that refers to an dlink:ANativeWindow, Android's native surface type. -The code:ANativeWindow represents the producer endpoint of any buffer queue, -regardless of consumer endpoint. +The dlink:ANativeWindow represents the producer endpoint of any buffer +queue, regardless of consumer endpoint. Common consumer endpoints for code:ANativeWindows are the system window compositor, video encoders, and application-specific compositors importing the images through a code:SurfaceTexture. diff --git a/appendices/VK_KHR_create_renderpass2.txt b/appendices/VK_KHR_create_renderpass2.txt index d5843c4d..f80036e8 100644 --- a/appendices/VK_KHR_create_renderpass2.txt +++ b/appendices/VK_KHR_create_renderpass2.txt @@ -1,4 +1,4 @@ -// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Copyright (c) 2016-2019 Khronos Group. This work is licensed under a // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ diff --git a/appendices/VK_KHR_draw_indirect_count.txt b/appendices/VK_KHR_draw_indirect_count.txt index 371251e9..47e8bfbb 100644 --- a/appendices/VK_KHR_draw_indirect_count.txt +++ b/appendices/VK_KHR_draw_indirect_count.txt @@ -1,4 +1,4 @@ -// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Copyright (c) 2016-2019 Khronos Group. This work is licensed under a // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ diff --git a/appendices/VK_KHR_get_display_properties2.txt b/appendices/VK_KHR_get_display_properties2.txt index 460e8ee7..88f063c7 100644 --- a/appendices/VK_KHR_get_display_properties2.txt +++ b/appendices/VK_KHR_get_display_properties2.txt @@ -55,24 +55,25 @@ None. 1) What should this extension be named? -*RESOLVED*: VK_KHR_get_display_properties2. +*RESOLVED*: `VK_KHR_get_display_properties2`. Other alternatives: - * VK_KHR_display2 - * One extension, combined with VK_KHR_surface_capabilites2. + * `VK_KHR_display2` + * One extension, combined with `VK_KHR_surface_capabilites2`. 2) Should extensible input structs be added for these new functions: *RESOLVED*: * flink:vkGetPhysicalDeviceDisplayProperties2KHR: No. - The only current input is a VkPhysicalDevice. + The only current input is a slink:VkPhysicalDevice. Other inputs wouldn't make sense. * flink:vkGetPhysicalDeviceDisplayPlaneProperties2KHR: No. - The only current input is a VkPhysicalDevice. + The only current input is a slink:VkPhysicalDevice. Other inputs wouldn't make sense. * flink:vkGetDisplayModeProperties2KHR: No. - The only curent inputs are a VkPhysicalDevice and a VkDisplayModeKHR. + The only current inputs are a slink:VkPhysicalDevice and a + slink:VkDisplayModeKHR. Other inputs wouldn't make sense. 3) Should additional display query functions be extended? diff --git a/appendices/VK_KHR_incremental_present.txt b/appendices/VK_KHR_incremental_present.txt index 3af2195b..28dfb1ae 100644 --- a/appendices/VK_KHR_incremental_present.txt +++ b/appendices/VK_KHR_incremental_present.txt @@ -27,7 +27,7 @@ small portion of the presentable images within a swapchain, since it enables the presentation engine to avoid wasting time presenting parts of the surface that haven't changed. -This extension is leveraged from the +EGL_KHR_swap_buffers_with_damage+ +This extension is leveraged from the `EGL_KHR_swap_buffers_with_damage` extension. === New Object Types diff --git a/appendices/VK_KHR_multiview.txt b/appendices/VK_KHR_multiview.txt index 04403f5f..2865a7aa 100644 --- a/appendices/VK_KHR_multiview.txt +++ b/appendices/VK_KHR_multiview.txt @@ -13,7 +13,7 @@ include::meta/VK_KHR_multiview.txt[] *Contributors*:: - Jeff Bolz, NVIDIA -This extension has the same goal as the OpenGL ES +GL_OVR_multiview+ +This extension has the same goal as the OpenGL ES `GL_OVR_multiview` extension - it enables rendering to multiple "`views`" by recording a single set of commands to be executed with slightly different behavior for each view. diff --git a/appendices/VK_KHR_shader_atomic_int64.txt b/appendices/VK_KHR_shader_atomic_int64.txt index 678eb0b3..0e2a812c 100644 --- a/appendices/VK_KHR_shader_atomic_int64.txt +++ b/appendices/VK_KHR_shader_atomic_int64.txt @@ -8,9 +8,9 @@ include::meta/VK_KHR_shader_atomic_int64.txt[] 2018-07-05 *Interactions and External Dependencies*:: - This extension requires the - https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_gpu_shader_int64.txt[+GL_ARB_gpu_shader_int64+] + https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_gpu_shader_int64.txt[`GL_ARB_gpu_shader_int64`] and - https://github.com/KhronosGroup/GLSL/tree/master/extensions/ext/GL_EXT_shader_atomic_int64.txt[+GL_EXT_shader_atomic_int64+] + https://github.com/KhronosGroup/GLSL/tree/master/extensions/ext/GL_EXT_shader_atomic_int64.txt[`GL_EXT_shader_atomic_int64`] extensions for GLSL source languages. *Contributors*:: - Aaron Hagan, AMD diff --git a/appendices/VK_KHR_shader_draw_parameters.txt b/appendices/VK_KHR_shader_draw_parameters.txt index acad3d0b..10124ba5 100644 --- a/appendices/VK_KHR_shader_draw_parameters.txt +++ b/appendices/VK_KHR_shader_draw_parameters.txt @@ -10,10 +10,10 @@ include::meta/VK_KHR_shader_draw_parameters.txt[] No known IP claims. *Interactions and External Dependencies*:: - Requires the - https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_shader_draw_parameters.html[+SPV_KHR_shader_draw_parameters+] + https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_shader_draw_parameters.html[`SPV_KHR_shader_draw_parameters`] SPIR-V extension. - Requires - https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_shader_draw_parameters.txt[+GL_ARB_shader_draw_parameters+] + https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_shader_draw_parameters.txt[`GL_ARB_shader_draw_parameters`] for GLSL source languages. - Promoted to Vulkan 1.1 Core *Contributors*:: @@ -26,7 +26,7 @@ include::meta/VK_KHR_shader_draw_parameters.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * +SPV_KHR_shader_draw_parameters+ + * `SPV_KHR_shader_draw_parameters` The extension provides access to three additional built-in shader variables in Vulkan: @@ -39,7 +39,7 @@ in Vulkan: being processed from an indirect draw call. When using GLSL source-based shader languages, the following variables from -+GL_ARB_shader_draw_parameters+ can map to these SPIR-V built-in +`GL_ARB_shader_draw_parameters` can map to these SPIR-V built-in decorations: * `in int gl_BaseInstanceARB;` -> code:BaseInstance, @@ -84,12 +84,12 @@ distinguish whether it's actually available or not. === Issues -1) Is this the same functionality as +GL_ARB_shader_draw_parameters+? +1) Is this the same functionality as `GL_ARB_shader_draw_parameters`? *RESOLVED*: It's actually a superset as it also adds in support for arrayed drawing commands. -In GL for +GL_ARB_shader_draw_parameters+, code:gl_BaseVertexARB holds the +In GL for `GL_ARB_shader_draw_parameters`, code:gl_BaseVertexARB holds the integer value passed to the parameter to the command that resulted in the current shader invocation. In the case where the command has no code:baseVertex parameter, the value of diff --git a/appendices/VK_KHR_storage_buffer_storage_class.txt b/appendices/VK_KHR_storage_buffer_storage_class.txt index 3d76e9c8..0cdb6596 100644 --- a/appendices/VK_KHR_storage_buffer_storage_class.txt +++ b/appendices/VK_KHR_storage_buffer_storage_class.txt @@ -10,7 +10,7 @@ include::meta/VK_KHR_storage_buffer_storage_class.txt[] No known IP claims. *Interactions and External Dependencies*:: - This extension requires the - https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_storage_buffer_storage_class.html[+SPV_KHR_storage_buffer_storage_class+] + https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_storage_buffer_storage_class.html[`SPV_KHR_storage_buffer_storage_class`] SPIR-V extension. - Promoted to Vulkan 1.1 Core *Contributors*:: @@ -19,7 +19,7 @@ include::meta/VK_KHR_storage_buffer_storage_class.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * +SPV_KHR_storage_buffer_storage_class+ + * `SPV_KHR_storage_buffer_storage_class` This extension provides a new SPIR-V code:StorageBuffer storage class. A code:Block-decorated object in this class is equivalent to a diff --git a/appendices/VK_KHR_variable_pointers.txt b/appendices/VK_KHR_variable_pointers.txt index 85b5f32d..e8f37433 100644 --- a/appendices/VK_KHR_variable_pointers.txt +++ b/appendices/VK_KHR_variable_pointers.txt @@ -10,7 +10,7 @@ include::meta/VK_KHR_variable_pointers.txt[] No known IP claims. *Interactions and External Dependencies*:: - Requires the - https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_variable_pointers.html[+SPV_KHR_variable_pointers+] + https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_variable_pointers.html[`SPV_KHR_variable_pointers`] SPIR-V extension. - Promoted to Vulkan 1.1 Core *Contributors*:: @@ -25,12 +25,12 @@ include::meta/VK_KHR_variable_pointers.txt[] - Jesse Hall, Google The `VK_KHR_variable_pointers` extension allows implementations to indicate -their level of support for the +SPV_KHR_variable_pointers+ SPIR-V extension. +their level of support for the `SPV_KHR_variable_pointers` SPIR-V extension. The SPIR-V extension allows shader modules to use invocation-private pointers into uniform and/or storage buffers, where the pointer values can be dynamic and non-uniform. -The +SPV_KHR_variable_pointers+ extension introduces two capabilities. +The `SPV_KHR_variable_pointers` extension introduces two capabilities. The first, code:VariablePointersStorageBuffer, must: be supported by all implementations of this extension. The second, code:VariablePointers, is optional. diff --git a/appendices/VK_KHR_vulkan_memory_model.txt b/appendices/VK_KHR_vulkan_memory_model.txt old mode 100644 new mode 100755 index cba861f7..9c01e162 --- a/appendices/VK_KHR_vulkan_memory_model.txt +++ b/appendices/VK_KHR_vulkan_memory_model.txt @@ -5,12 +5,12 @@ include::meta/VK_KHR_vulkan_memory_model.txt[] *Last Modified Date*:: - 2018-02-05 + 2018-12-10 *IP Status*:: No known IP claims. *Interactions and External Dependencies*:: - This extension requires - https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_vulkan_memory_model.html[+SPV_KHR_vulkan_memory_model+] + https://www.khronos.org/registry/spir-v/extensions/KHR/SPV_KHR_vulkan_memory_model.html[`SPV_KHR_vulkan_memory_model`] *Contributors*:: - Jeff Bolz, NVIDIA - Alan Baker, Google @@ -33,6 +33,15 @@ multiple shader invocations. * slink:VkPhysicalDeviceVulkanMemoryModelFeaturesKHR +[NOTE] +.Note +==== +Version 3 of the spec added a member +(pname:vulkanMemoryModelAvailabilityVisibilityChains) to +slink:VkPhysicalDeviceVulkanMemoryModelFeaturesKHR, which is an incompatible +change from version 2. +==== + === New SPIR-V Capabilities * <> diff --git a/appendices/VK_NVX_device_generated_commands.txt b/appendices/VK_NVX_device_generated_commands.txt index 667faae3..d5b4a708 100644 --- a/appendices/VK_NVX_device_generated_commands.txt +++ b/appendices/VK_NVX_device_generated_commands.txt @@ -288,7 +288,7 @@ The inputs are "`referenced`", and should not be modified after the call to flink:vkCmdProcessCommandsNVX and until after the rendering of the target command buffer is finished. -18) Why is this +NVX+ and not +NV+? +18) Why is this `NVX` and not `NV`? To allow early experimentation and feedback. We expect that a version with a refined design as multi-vendor variant will diff --git a/appendices/VK_NVX_multiview_per_view_attributes.txt b/appendices/VK_NVX_multiview_per_view_attributes.txt index cd8eb94f..89b88f76 100644 --- a/appendices/VK_NVX_multiview_per_view_attributes.txt +++ b/appendices/VK_NVX_multiview_per_view_attributes.txt @@ -6,9 +6,9 @@ include::meta/VK_NVX_multiview_per_view_attributes.txt[] No known IP claims. *Interactions and External Dependencies*:: - This extension requires the - https://www.khronos.org/registry/spir-v/extensions/NV/SPV_NVX_multiview_per_view_attributes.html[+SPV_NVX_multiview_per_view_attributes+] + https://www.khronos.org/registry/spir-v/extensions/NV/SPV_NVX_multiview_per_view_attributes.html[`SPV_NVX_multiview_per_view_attributes`] SPIR-V extension. - - This extension requires the +GL_NVX_multiview_per_view_attributes+ + - This extension requires the `GL_NVX_multiview_per_view_attributes` extension for GLSL source languages. - This extension interacts with `<>`. *Contributors*:: @@ -18,8 +18,8 @@ include::meta/VK_NVX_multiview_per_view_attributes.txt[] This extension adds a new way to write shaders to be used with multiview subpasses, where the attributes for all views are written out by a single invocation of the vertex processing stages. -Related SPIR-V and GLSL extensions +SPV_NVX_multiview_per_view_attributes+ -and +GL_NVX_multiview_per_view_attributes+ introduce per-view position and +Related SPIR-V and GLSL extensions `SPV_NVX_multiview_per_view_attributes` +and `GL_NVX_multiview_per_view_attributes` introduce per-view position and viewport mask attributes arrays, and this extension defines how those per-view attribute arrays are interpreted by Vulkan. Pipelines using per-view attributes may: only execute the vertex processing diff --git a/appendices/VK_NV_fragment_shader_barycentric.txt b/appendices/VK_NV_fragment_shader_barycentric.txt index 18c78e7e..474dbaf0 100644 --- a/appendices/VK_NV_fragment_shader_barycentric.txt +++ b/appendices/VK_NV_fragment_shader_barycentric.txt @@ -14,7 +14,7 @@ include::meta/VK_NV_fragment_shader_barycentric.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * +SPV_NV_fragment_shader_barycentric+ + * `SPV_NV_fragment_shader_barycentric` The extension provides access to three additional fragment shader variable decorations in SPIR-V: @@ -31,7 +31,7 @@ decorations in SPIR-V: the fragment produced using linear interpolation When using GLSL source-based shader languages, the following variables from -+GL_NV_fragment_shader_barycentric+ maps to these SPIR-V built-in +`GL_NV_fragment_shader_barycentric` maps to these SPIR-V built-in decorations: * `in vec3 gl_BaryCoordNV;` -> code:BaryCoordNV diff --git a/appendices/VK_NV_geometry_shader_passthrough.txt b/appendices/VK_NV_geometry_shader_passthrough.txt index 4e3b5e2f..f0d6b419 100644 --- a/appendices/VK_NV_geometry_shader_passthrough.txt +++ b/appendices/VK_NV_geometry_shader_passthrough.txt @@ -4,10 +4,10 @@ include::meta/VK_NV_geometry_shader_passthrough.txt[] 2017-02-15 *Interactions and External Dependencies*:: - This extension requires the - https://www.khronos.org/registry/spir-v/extensions/NV/SPV_NV_geometry_shader_passthrough.html[+SPV_NV_geometry_shader_passthrough+] + https://www.khronos.org/registry/spir-v/extensions/NV/SPV_NV_geometry_shader_passthrough.html[`SPV_NV_geometry_shader_passthrough`] SPIR-V extension. - This extension requires the - https://www.khronos.org/registry/OpenGL/extensions/NV/NV_geometry_shader_passthrough.txt[+GL_NV_geometry_shader_passthrough+] + https://www.khronos.org/registry/OpenGL/extensions/NV/NV_geometry_shader_passthrough.txt[`GL_NV_geometry_shader_passthrough`] extension for GLSL source languages. - This extension requires the pname:geometryShader feature. *Contributors*:: @@ -16,7 +16,7 @@ include::meta/VK_NV_geometry_shader_passthrough.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * +SPV_NV_geometry_shader_passthrough+ + * `SPV_NV_geometry_shader_passthrough` Geometry shaders provide the ability for applications to process each primitive sent through the graphics pipeline using a programmable shader. @@ -34,11 +34,11 @@ Adding this to a geometry shader input variable specifies that the values of this input are copied to the corresponding vertex of the output primitive. When using GLSL source-based shading languages, the code:passthrough layout -qualifier from +GL_NV_geometry_shader_passthrough+ maps to the +qualifier from `GL_NV_geometry_shader_passthrough` maps to the code:PassthroughNV decoration. To use the code:passthrough layout, in GLSL the -+GL_NV_geometry_shader_passthrough+ extension must be enabled. -Behaviour is described in the +GL_NV_geometry_shader_passthrough+ extension +`GL_NV_geometry_shader_passthrough` extension must be enabled. +Behaviour is described in the `GL_NV_geometry_shader_passthrough` extension specification. === New Object Types diff --git a/appendices/VK_NV_glsl_shader.txt b/appendices/VK_NV_glsl_shader.txt index 8bf30ba7..55a4e7ac 100644 --- a/appendices/VK_NV_glsl_shader.txt +++ b/appendices/VK_NV_glsl_shader.txt @@ -7,7 +7,7 @@ include::meta/VK_NV_glsl_shader.txt[] *Contributors*:: - Piers Daniell, NVIDIA -This extension allows GLSL shaders written to the +GL_KHR_vulkan_glsl+ +This extension allows GLSL shaders written to the `GL_KHR_vulkan_glsl` extension specification to be used instead of SPIR-V. The implementation will automatically detect whether the shader is SPIR-V or GLSL, and compile it appropriately. diff --git a/appendices/VK_NV_ray_tracing.txt b/appendices/VK_NV_ray_tracing.txt index 2d23dd19..c8b1d47d 100644 --- a/appendices/VK_NV_ray_tracing.txt +++ b/appendices/VK_NV_ray_tracing.txt @@ -5,10 +5,10 @@ include::meta/VK_NV_ray_tracing.txt[] *Interactions and External Dependencies*:: - This extension requires the - https://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/NV/SPV_NV_ray_tracing.html[+SPV_NV_ray_tracing+] + https://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/NV/SPV_NV_ray_tracing.html[`SPV_NV_ray_tracing`] SPIR-V extension. - This extension requires the - https://github.com/KhronosGroup/GLSL/blob/master/extensions/nv/GLSL_NV_ray_tracing.txt[+GL_NV_ray_tracing+] + https://github.com/KhronosGroup/GLSL/blob/master/extensions/nv/GLSL_NV_ray_tracing.txt[`GL_NV_ray_tracing`] extension for GLSL source languages. *Contributors*:: diff --git a/appendices/VK_NV_sample_mask_override_coverage.txt b/appendices/VK_NV_sample_mask_override_coverage.txt index db9500de..d8c1ab36 100644 --- a/appendices/VK_NV_sample_mask_override_coverage.txt +++ b/appendices/VK_NV_sample_mask_override_coverage.txt @@ -6,10 +6,10 @@ include::meta/VK_NV_sample_mask_override_coverage.txt[] No known IP claims. *Interactions and External Dependencies*:: - This extension requires the - https://www.khronos.org/registry/spir-v/extensions/NV/SPV_NV_sample_mask_override_coverage.html[+SPV_NV_sample_mask_override_coverage+] + https://www.khronos.org/registry/spir-v/extensions/NV/SPV_NV_sample_mask_override_coverage.html[`SPV_NV_sample_mask_override_coverage`] SPIR-V extension. - This extension requires the - https://www.khronos.org/registry/OpenGL/extensions/NV/NV_sample_mask_override_coverage.txt[+GL_NV_sample_mask_override_coverage+] + https://www.khronos.org/registry/OpenGL/extensions/NV/NV_sample_mask_override_coverage.txt[`GL_NV_sample_mask_override_coverage`] extension for GLSL source languages. *Contributors*:: - Daniel Koch, NVIDIA @@ -17,7 +17,7 @@ include::meta/VK_NV_sample_mask_override_coverage.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * +SPV_NV_sample_mask_override_coverage+ + * `SPV_NV_sample_mask_override_coverage` The extension provides access to the code:OverrideCoverageNV decoration under the code:SampleMaskOverrideCoverageNV capability. @@ -26,11 +26,11 @@ decoration allows the shader to modify the coverage mask and affect which samples are used to process the fragment. When using GLSL source-based shader languages, the code:override_coverage -layout qualifier from +GL_NV_sample_mask_override_coverage+ maps to the +layout qualifier from `GL_NV_sample_mask_override_coverage` maps to the code:OverrideCoverageNV decoration. To use the code:override_coverage layout qualifier in GLSL the -+GL_NV_sample_mask_override_coverage+ extension must be enabled. -Behavior is described in the +GL_NV_sample_mask_override_coverage+ extension +`GL_NV_sample_mask_override_coverage` extension must be enabled. +Behavior is described in the `GL_NV_sample_mask_override_coverage` extension spec. === New Object Types diff --git a/appendices/VK_NV_shader_subgroup_partitioned.txt b/appendices/VK_NV_shader_subgroup_partitioned.txt index 0aad6de5..e65d6145 100644 --- a/appendices/VK_NV_shader_subgroup_partitioned.txt +++ b/appendices/VK_NV_shader_subgroup_partitioned.txt @@ -7,9 +7,9 @@ include::meta/VK_NV_shader_subgroup_partitioned.txt[] This extension enables support for a new class of subgroup operations via the -https://github.com/KhronosGroup/GLSL/blob/master/extensions/nv/GL_NV_shader_subgroup_partitioned.txt[+GL_NV_shader_subgroup_partitioned+] +https://github.com/KhronosGroup/GLSL/blob/master/extensions/nv/GL_NV_shader_subgroup_partitioned.txt[`GL_NV_shader_subgroup_partitioned`] GLSL extension and -http://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/NV/SPV_NV_shader_subgroup_partitioned.html[+SPV_NV_shader_subgroup_partitioned+] +http://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/NV/SPV_NV_shader_subgroup_partitioned.html[`SPV_NV_shader_subgroup_partitioned`] SPIR-V extension. Support for these new operations is advertised via the ename:VK_SUBGROUP_FEATURE_PARTITIONED_BIT_NV bit. diff --git a/appendices/VK_NV_shading_rate_image.txt b/appendices/VK_NV_shading_rate_image.txt index 7faa74aa..acda26ee 100644 --- a/appendices/VK_NV_shading_rate_image.txt +++ b/appendices/VK_NV_shading_rate_image.txt @@ -32,7 +32,7 @@ implementation reads a texel in the bound shading rate image and looks up the fetched value in a palette to determine a base shading rate. In addition to the API support controlling rasterization, this extension -also adds Vulkan support for the +SPV_NV_shading_rate+ extension to SPIR-V. +also adds Vulkan support for the `SPV_NV_shading_rate` extension to SPIR-V. That extension provides two fragment shader variable decorations that allow fragment shaders to determine the shading rate used for processing the fragment: @@ -45,7 +45,7 @@ fragment: When using SPIR-V in conjunction with the OpenGL Shading Language (GLSL), the fragment shader capabilities are provided by the -+GL_NV_shading_rate_image+ language extension and correspond to the built-in +`GL_NV_shading_rate_image` language extension and correspond to the built-in variables code:gl_FragmentSizeNV and code:gl_InvocationsPerPixelNV, respectively. diff --git a/appendices/VK_NV_viewport_array2.txt b/appendices/VK_NV_viewport_array2.txt index 8a9e8cad..ad3f9093 100644 --- a/appendices/VK_NV_viewport_array2.txt +++ b/appendices/VK_NV_viewport_array2.txt @@ -4,10 +4,10 @@ include::meta/VK_NV_viewport_array2.txt[] 2017-02-15 *Interactions and External Dependencies*:: - This extension requires the - https://www.khronos.org/registry/spir-v/extensions/NV/SPV_NV_viewport_array2.html[+SPV_NV_viewport_array2+] + https://www.khronos.org/registry/spir-v/extensions/NV/SPV_NV_viewport_array2.html[`SPV_NV_viewport_array2`] SPIR-V extension. - This extension requires the - https://www.khronos.org/registry/OpenGL/extensions/NV/NV_viewport_array2.txt[+GL_NV_viewport_array2+] + https://www.khronos.org/registry/OpenGL/extensions/NV/NV_viewport_array2.txt[`GL_NV_viewport_array2`] extension for GLSL source languages. - This extension requires the pname:geometryShader and pname:multiViewport features. @@ -18,7 +18,7 @@ include::meta/VK_NV_viewport_array2.txt[] This extension adds support for the following SPIR-V extension in Vulkan: - * +SPV_NV_viewport_array2+ + * `SPV_NV_viewport_array2` which allows a single primitive to be broadcast to multiple viewports and/or multiple layers. @@ -42,9 +42,9 @@ code:ShaderViewportMaskNV capability. When using GLSL source-based shading languages, the code:gl_ViewportMask[] built-in output variable and code:viewport_relative layout qualifier from -+GL_NV_viewport_array2+ map to the code:ViewportMaskNV and +`GL_NV_viewport_array2` map to the code:ViewportMaskNV and code:ViewportRelativeNV decorations, respectively. -Behaviour is described in the +GL_NV_viewport_array2+ extension +Behaviour is described in the `GL_NV_viewport_array2` extension specificiation. ifdef::VK_EXT_shader_viewport_index_layer[] diff --git a/appendices/compressedtex.txt b/appendices/compressedtex.txt index 0c17954c..a7db4d38 100644 --- a/appendices/compressedtex.txt +++ b/appendices/compressedtex.txt @@ -130,7 +130,7 @@ below. .Mapping of Vulkan ASTC decoding format to ASTC decoding modes [width="75%",options="header",cols="75%,25%"] |==== -| VkFormat ^| Decoding mode +| elink:VkFormat ^| Decoding mode | ename:VK_FORMAT_R16G16B16A16_SFLOAT ^| decode_float16 | ename:VK_FORMAT_R8G8B8A8_UNORM ^| decode_unorm8 | ename:VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 ^| decode_rgb9e5 diff --git a/appendices/memorymodel.txt b/appendices/memorymodel.txt old mode 100644 new mode 100755 index ee7ecf40..b3bedf6f --- a/appendices/memorymodel.txt +++ b/appendices/memorymodel.txt @@ -33,8 +33,8 @@ A memory operation must: not affect memory at a memory location not within its set of memory locations. Memory locations for buffers and images are explicitly allocated in -VkDeviceMemory objects, and are implicitly allocated for SPIR-V variables in -each shader invocation. +slink:VkDeviceMemory objects, and are implicitly allocated for SPIR-V +variables in each shader invocation. [[memory-model-allocation]] == Allocation @@ -413,7 +413,7 @@ NOTE: This covers all Vulkan synchronization primitives, including device operations executing before a synchronization primitive is signaled, wait operations happening before subsequent device operations, signal operations happening before host operations that wait on them, and host operations -happening before vkQueueSubmit. +happening before flink:vkQueueSubmit. The list is spread throughout the synchronization chapter, and is not repeated here. @@ -514,9 +514,9 @@ The memory domains defined in Vulkan include: corresponding to the code:Subgroup scope. NOTE: These do not correspond to storage classes or device-local and -host-local VkDeviceMemory allocations, rather they indicate whether a write -can be made visible only to agents in the same subgroup, same workgroup, in -any shader invocation, or anywhere on the device, or host. +host-local slink:VkDeviceMemory allocations, rather they indicate whether a +write can be made visible only to agents in the same subgroup, same +workgroup, in any shader invocation, or anywhere on the device, or host. The shader, queue family instance, workgroup instance, and subgroup instance domains are only used for shader-based availability/visibility operatons, in other cases writes can be made available from/visible to the shader via the @@ -569,6 +569,32 @@ other non-atomic memory accesses for the purpose of <>, meaning they can be ordered by release-acquire sequences or memory barriers. +An _availability chain_ is a sequence of availability operations of +increasing scope where element N+1 of the chain is performed in the same +scope instance as the destination of element N and element N happens-before +element N+1. +An example is an availability operation with destination scope of the +workgroup instance domain that happens before an availability operation to +the shader domain performed by an invocation in the same workgroup. +An availability chain AVC that happens-after W and that includes (A,R,L) in +the source scope makes (W,L) _available_ to the memory domains in its final +destination scope. +An availability chain with a single element is just the availability +operation. + +Similarly, a _visibility chain_ is a sequence of visibility operations of +decreasing scope where element N of the chain is performed in the same scope +instance as the source of element N+1 and element N happens-before element +N+1. +An example is a visibility operation with source scope of the shader domain +that happens before a visibility operation with source scope of the +workgroup instance domain performance by an invocation in the same +workgroup. +A visibility chain VISC that happens-after AVC (or DOM) and for which (W,L) +is available in any domain in the source scope makes (W,L) _visible_ to all +(agent,reference,L) tuples included in its final destination scope. +A visibility chain with a single element is just the visibility operation. + [[memory-model-vulkan-availability-visibility]] == Availability, Visibility, and Domain Operations @@ -702,13 +728,16 @@ the following is true: * If R~X~ == R~Y~ and A~X~ and A~Y~ access a common memory domain D (e.g. are in the same workgroup instance if D is the workgroup instance domain), and both X and Y are non-private: - ** X is a write, Y is a write, AV(A~X~,R~X~,D,L) is an availability - operation making (X,L) available to domain D, and - X->^rcpo^AV(A~X~,R~X~,D,L)->Y - ** X is a write, Y is a read, AV(A~X~,R~X~,D,L) is an availability - operation making (X,L) available to domain D, VIS(A~Y~,R~Y~,D,L) is a - visibility operation making writes to L available in domain D visible - to Y, and X->^rcpo^AV(A~X~,R~X~,D,L)->VIS(A~Y~,R~Y~,D,L)->^rcpo^Y + ** X is a write, Y is a write, AVC(A~X~,R~X~,D,L) is an availability chain + making (X,L) available to domain D, and X->^rcpo^AVC(A~X~,R~X~,D,L)->Y + ** X is a write, Y is a read, AVC(A~X~,R~X~,D,L) is an availability chain + making (X,L) available to domain D, VISC(A~Y~,R~Y~,D,L) is a visibility + chain making writes to L available in domain D visible to Y, and + X->^rcpo^AVC(A~X~,R~X~,D,L)->VISC(A~Y~,R~Y~,D,L)->^rcpo^Y + ** If + slink:VkPhysicalDeviceVulkanMemoryModelFeaturesKHR::pname:vulkanMemoryModelAvailabilityVisibilityChains + is ename:VK_FALSE, then AVC and VISC must: each only have a single + element in the chain, in each sub-bullet above. * Let D~X~ and D~Y~ each be either the device domain or the host domain, depending on whether A~X~ and A~Y~ execute on the device or host: @@ -791,12 +820,13 @@ being read. [[memory-model-deallocation]] == Deallocation -A call to vkFreeMemory must: happen-after all memory operations on all -memory locations in that VkDeviceMemory object. +A call to flink:vkFreeMemory must: happen-after all memory operations on all +memory locations in that slink:VkDeviceMemory object. NOTE: Normally, device memory operations in a given queue are synchronized -with vkFreeMemory by having a host thread wait on a fence signalled by that -queue, and the wait happens-before the call to vkFreeMemory on the host. +with flink:vkFreeMemory by having a host thread wait on a fence signalled by +that queue, and the wait happens-before the call to flink:vkFreeMemory on +the host. The deallocation of SPIR-V variables is managed by the system and happens-after all operations on those variables. diff --git a/appendices/spirvenv.txt b/appendices/spirvenv.txt index f6fcdf0a..08960ef2 100644 --- a/appendices/spirvenv.txt +++ b/appendices/spirvenv.txt @@ -327,11 +327,6 @@ The application can: pass a SPIR-V module to flink:vkCreateShaderModule that uses the `SPV_KHR_shader_draw_parameters` SPIR-V extension. endif::VK_VERSION_1_1,VK_KHR_shader_draw_parameters[] -ifdef::VK_KHR_shader_float16_int8[] -The application can: pass a SPIR-V module to flink:vkCreateShaderModule that -uses the code:Float16 or the code:Int8 SPIR-V capabilities. -endif::VK_KHR_shader_float16_int8[] - ifdef::VK_KHR_8bit_storage[] The application can: pass a SPIR-V module to flink:vkCreateShaderModule that uses the `SPV_KHR_8bit_storage` SPIR-V extension. @@ -1095,7 +1090,7 @@ are required: to be at least as follows: 2+| Correctly rounded. | code:OpFSub 2+| Correctly rounded. -| code:OpFMul +| code:OpFMul, code:OpVectorTimesScalar, code:OpMatrixTimesScalar 2+| Correctly rounded. | code:OpDot(x, y) 2+| Inherited from latexmath:[\sum_{i = 0}^{n - 1} x_{i} \times y_{i}]. @@ -1243,17 +1238,17 @@ at least as follows, unless decorated with RelaxedPrecision: .Precision of core SPIR-V Instructions [options="header"] |==== -| Instruction | Precision -| code:OpFAdd | Correctly rounded. -| code:OpFSub | Correctly rounded. -| code:OpFMul | Correctly rounded. -| code:OpFOrdEqual, code:OpFUnordEqual | Correct result. -| code:OpFOrdLessThan, code:OpFUnordLessThan | Correct result. -| code:OpFOrdGreaterThan, code:OpFUnordGreaterThan | Correct result. -| code:OpFOrdLessThanEqual, code:OpFUnordLessThanEqual | Correct result. -| code:OpFOrdGreaterThanEqual, code:OpFUnordGreaterThanEqual| Correct result. -| code:OpFDiv | 2.5 ULP for b in the range [2^-126^, 2^126^]. -| conversions between types | Correctly rounded. +| Instruction | Precision +| code:OpFAdd | Correctly rounded. +| code:OpFSub | Correctly rounded. +| code:OpFMul, code:OpVectorTimesScalar, code:OpMatrixTimesScalar | Correctly rounded. +| code:OpFOrdEqual, code:OpFUnordEqual | Correct result. +| code:OpFOrdLessThan, code:OpFUnordLessThan | Correct result. +| code:OpFOrdGreaterThan, code:OpFUnordGreaterThan | Correct result. +| code:OpFOrdLessThanEqual, code:OpFUnordLessThanEqual | Correct result. +| code:OpFOrdGreaterThanEqual, code:OpFUnordGreaterThanEqual | Correct result. +| code:OpFDiv | 2.5 ULP for b in the range [2^-126^, 2^126^]. +| conversions between types | Correctly rounded. |==== .Precision of GLSL.std.450 Instructions diff --git a/chapters/VK_KHR_android_surface/platformCreateSurface_android.txt b/chapters/VK_KHR_android_surface/platformCreateSurface_android.txt index 14fea16b..a67248d1 100644 --- a/chapters/VK_KHR_android_surface/platformCreateSurface_android.txt +++ b/chapters/VK_KHR_android_surface/platformCreateSurface_android.txt @@ -24,9 +24,9 @@ include::../../api/protos/vkCreateAndroidSurfaceKHR.txt[] created surface object is returned. During the lifetime of a surface created using a particular -code:ANativeWindow handle any attempts to create another surface for the -same code:ANativeWindow and any attempts to connect to the same -code:ANativeWindow through other platform mechanisms will fail. +dlink:ANativeWindow handle any attempts to create another surface for the +same dlink:ANativeWindow and any attempts to connect to the same +dlink:ANativeWindow through other platform mechanisms will fail. [NOTE] .Note @@ -38,7 +38,7 @@ code:EGLSurface simultaneously. ==== If successful, fname:vkCreateAndroidSurfaceKHR increments the -code:ANativeWindow's reference count, and fname:vkDestroySurfaceKHR will +dlink:ANativeWindow's reference count, and fname:vkDestroySurfaceKHR will decrement it. On Android, when a swapchain's pname:imageExtent does not match the @@ -62,13 +62,13 @@ include::../../api/structs/VkAndroidSurfaceCreateInfoKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:flags is reserved for future use. - * pname:window is a pointer to the code:ANativeWindow to associate the + * pname:window is a pointer to the dlink:ANativeWindow to associate the surface with. .Valid Usage **** * [[VUID-VkAndroidSurfaceCreateInfoKHR-window-01248]] - pname:window must: point to a valid Android code:ANativeWindow. + pname:window must: point to a valid Android dlink:ANativeWindow. **** include::../../validity/structs/VkAndroidSurfaceCreateInfoKHR.txt[] @@ -77,9 +77,9 @@ include::../../validity/structs/VkAndroidSurfaceCreateInfoKHR.txt[] [open,refpage='ANativeWindow',desc='Android native window type',type='defines'] -- To remove an unnecessary compile-time dependency, an incomplete type -definition of code:ANativeWindow is provided in the Vulkan headers: +definition of dlink:ANativeWindow is provided in the Vulkan headers: include::../../api/defines/ANativeWindow.txt[] -The actual code:ANativeWindow type is defined in Android NDK headers. +The actual dlink:ANativeWindow type is defined in Android NDK headers. -- diff --git a/chapters/VK_NV_external_memory_win32/import_memory_win32.txt b/chapters/VK_NV_external_memory_win32/import_memory_win32.txt index e4059128..d2c3f33d 100644 --- a/chapters/VK_NV_external_memory_win32/import_memory_win32.txt +++ b/chapters/VK_NV_external_memory_win32/import_memory_win32.txt @@ -48,8 +48,8 @@ include::../../api/enums/VkExternalMemoryHandleTypeFlagBitsNV.txt[] duplicated from such a handle using `DuplicateHandle()`. * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_BIT_NV specifies a valid NT handle to memory returned by - `IDXGIResource1::ftext:CreateSharedHandle()`, or a handle duplicated - from such a handle using `DuplicateHandle()`. + `IDXGIResource1::CreateSharedHandle`, or a handle duplicated from such a + handle using `DuplicateHandle()`. * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_KMT_BIT_NV specifies a handle to memory returned by `IDXGIResource::GetSharedHandle()`. diff --git a/chapters/clears.txt b/chapters/clears.txt index 8f586bb5..953b045b 100644 --- a/chapters/clears.txt +++ b/chapters/clears.txt @@ -255,9 +255,9 @@ regardless if the pixels lie outside of the clear region. Clears may: have a different set of supported fragment areas than draws. endif::VK_EXT_fragment_density_map[] -Unlike other <>, vkCmdClearAttachments executes as a -drawing command, rather than a transfer command, with writes performed by it -executing in <>. +Unlike other <>, flink:vkCmdClearAttachments executes +as a drawing command, rather than a transfer command, with writes performed +by it executing in <>. Clears to color attachments are executed as color attachment writes, by the ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage. Clears to depth/stencil attachments are executed as <>` extension, call +flink:vkGetPhysicalDeviceFeatures2KHR with a sname:VkPhysicalDeviceFloat16Int8FeaturesKHR structure in the pname:pNext chain. The sname:VkPhysicalDeviceFloat16Int8FeaturesKHR structure can: also be in @@ -1414,7 +1415,7 @@ structure describe the following features: be used. * [[features-features-runtimeDescriptorArray]] pname:runtimeDescriptorArray indicates whether the implementation - supports the SPIR-V +RuntimeDescriptorArrayEXT+ capability. + supports the SPIR-V code:RuntimeDescriptorArrayEXT capability. If this feature is not enabled, descriptors must: not be declared in runtime arrays. @@ -1547,6 +1548,10 @@ include::../api/structs/VkPhysicalDeviceVulkanMemoryModelFeaturesKHR.txt[] Model can use code:Device scope synchronization. This also indicates whether shader modules can: declare the code:VulkanMemoryModelDeviceScopeKHR capability. + * [[features-features-vulkanMemoryModelAvailabilityVisibilityChains]] + pname:vulkanMemoryModelAvailabilityVisibilityChains indicates whether + the Vulkan Memory Model can use <> with more than one element. include::../validity/structs/VkPhysicalDeviceVulkanMemoryModelFeaturesKHR.txt[] -- @@ -8259,8 +8264,8 @@ endif::VK_KHR_external_memory_capabilities[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT specifies a POSIX file descriptor handle that has only limited valid usage outside of Vulkan and other compatible APIs. - It must: be compatible with the POSIX system calls ftext:dup, - ftext:dup2, ftext:close, and the non-standard system call ftext:dup3. + It must: be compatible with the POSIX system calls code:dup, code:dup2, + code:close, and the non-standard system call code:dup3. Additionally, it must: be transportable over a socket using an code:SCM_RIGHTS control message. It owns a reference to the underlying memory resource represented by its @@ -8268,9 +8273,9 @@ endif::VK_KHR_external_memory_capabilities[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT specifies an NT handle that has only limited valid usage outside of Vulkan and other compatible APIs. - It must: be compatible with the functions ftext:DuplicateHandle, - ftext:CloseHandle, ftext:CompareObjectHandles, - ftext:GetHandleInformation, and ftext:SetHandleInformation. + It must: be compatible with the functions code:DuplicateHandle, + code:CloseHandle, code:CompareObjectHandles, code:GetHandleInformation, + and code:SetHandleInformation. It owns a reference to the underlying memory resource represented by its Vulkan memory object. * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT specifies a @@ -8317,7 +8322,7 @@ ifdef::VK_EXT_external_memory_dma_buf[] endif::VK_EXT_external_memory_dma_buf[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID - specifies an code:AHardwareBuffer object defined by the Android NDK. + specifies an dlink:AHardwareBuffer object defined by the Android NDK. See <> for more details of this handle type. endif::VK_ANDROID_external_memory_android_hardware_buffer[] diff --git a/chapters/fundamentals.txt b/chapters/fundamentals.txt index 8d341e01..36aadb3c 100644 --- a/chapters/fundamentals.txt +++ b/chapters/fundamentals.txt @@ -1036,23 +1036,26 @@ ifdef::VK_VERSION_1_1[] Instance-level functionality or behavior added by a <> of the API must: not be used unless it is supported by the -instance as determined by flink:vkEnumerateInstanceVersion. +instance as determined by flink:vkEnumerateInstanceVersion and the specified +version of slink:VkApplicationInfo::pname:apiVersion. endif::VK_VERSION_1_1[] Physical-device-level functionality or behavior added by a <> of the API must: not be used unless it is supported by the -physical device as determined by flink:vkGetPhysicalDeviceProperties. +physical device as determined by +slink:VkPhysicalDeviceProperties::pname:apiVersion and the specified version +of slink:VkApplicationInfo::pname:apiVersion. Device-level functionality or behavior added by a <> of the API must: not be used unless it is supported by the device -as determined by flink:vkGetPhysicalDeviceProperties. - +as determined by slink:VkPhysicalDeviceProperties::pname:apiVersion and the +specified version of slink:VkApplicationInfo::pname:apiVersion. [[fundamentals-returncodes]] === Return Codes -[open,refpage='VkResult',desc='Vulkan command return codes',type='enums',xrefs='TBD'] +[open,refpage='VkResult',desc='Vulkan command return codes',type='enums'] -- While the core Vulkan API is not designed to capture incorrect usage, some diff --git a/chapters/initialization.txt b/chapters/initialization.txt index d2a2cad8..ce305fd6 100644 --- a/chapters/initialization.txt +++ b/chapters/initialization.txt @@ -354,6 +354,39 @@ Otherwise, the application can: call flink:vkEnumerateInstanceVersion to determine the version of Vulkan. ==== +ifdef::VK_VERSION_1_1[] +As long as the instance supports at least Vulkan 1.1, an application can: +use different versions of Vulkan with an instance than it does with a device +or physical device. + +[NOTE] +.Note +==== + +The Khronos validation layers will treat pname:apiVersion as the highest API +version the application targets, and will validate API usage against the +minimum of that version and the implementation version (instance or device, +depending on context). +If an application tries to use functionality from a greater version than +this, a validation error will be triggered. + +For example, if the instance supports Vulkan 1.1 and three physical devices +support Vulkan 1.0, Vulkan 1.1, and a hypothetical Vulkan 1.2, respectively, +and if the application sets pname:apiVersion to 1.2, the application can: +use the following versions of Vulkan: + + * Vulkan 1.0 can: be used with the instance and with all physical devices. + * Vulkan 1.1 can: be used with the instance and with the physical devices + that support Vulkan 1.1 and Vulkan 1.2. + * Vulkan 1.2 can: be used with the physical device that supports Vulkan + 1.2. + +If we modify the above example so that the application sets pname:apiVersion +to 1.1, then the application must: not use Vulkan 1.2 functionality on the +physical device that supports Vulkan 1.2. +==== +endif::VK_VERSION_1_1[] + Implicit layers must: be disabled if they do not support a version at least as high as pname:apiVersion. See the <>) that are statically used by the shader entry points for the -pipeline. +storage class of +ifdef::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] +code:StorageBuffer, +endif::VK_VERSION_1_1,VK_KHR_storage_buffer_storage_class[] +code:Uniform or code:UniformConstant (including the variables in the +<>) that are +statically used by the shader entry points for the pipeline. These variables must: have code:DescriptorSet and code:Binding decorations specified, which are assigned and matched with the diff --git a/chapters/memory.txt b/chapters/memory.txt index 2e0c0033..448c6f2a 100644 --- a/chapters/memory.txt +++ b/chapters/memory.txt @@ -1171,7 +1171,7 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] Android hardware buffer, and the pname:pNext chain includes an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not dlink:VK_NULL_HANDLE, the Android hardware buffer's - code:AHardwareBuffer::code:usage must: include at least one of + dlink:AHardwareBuffer::code:usage must: include at least one of code:AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT or code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE. * [[VUID-VkMemoryAllocateInfo-pNext-02387]] @@ -1195,7 +1195,7 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] Android hardware buffer, and the pname:pNext chain includes an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not dlink:VK_NULL_HANDLE, and the Android hardware buffer's - code:AHardwareBuffer::code:usage includes + dlink:AHardwareBuffer::code:usage includes code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the pname:image must: have a complete mipmap chain. * [[VUID-VkMemoryAllocateInfo-pNext-02586]] @@ -1203,7 +1203,7 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] Android hardware buffer, and the pname:pNext chain includes an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not dlink:VK_NULL_HANDLE, and the Android hardware buffer's - code:AHardwareBuffer::code:usage does not include + dlink:AHardwareBuffer::code:usage does not include code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the pname:image must: have exactly one mipmap level. * [[VUID-VkMemoryAllocateInfo-pNext-02390]] @@ -2250,7 +2250,7 @@ sname:VkAndroidHardwareBufferFormatPropertiesANDROID are only suggestions. Applications should: treat these values as sensible defaults to use in the absence of more reliable information obtained through some other means. If the underlying physical device is also usable via OpenGL ES with the -https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt[+GL_OES_EGL_image_external+] +https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt[`GL_OES_EGL_image_external`] extension, the implementation should: suggest values that will produce similar sampled values as would be obtained by sampling the same external image via code:samplerExternalOES in OpenGL ES using equivalent sampler @@ -2260,7 +2260,7 @@ parameters. .Note ==== Since -https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt[+GL_OES_EGL_image_external+] +https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt[`GL_OES_EGL_image_external`] does not require the same sampling and conversion calculations as Vulkan does, achieving identical results between APIs may: not be possible on some implementations. @@ -2871,7 +2871,7 @@ ifdef::VK_KHR_external_memory_capabilities+VK_ANDROID_external_memory_android_ha [[memory-external-android-hardware-buffer]] ==== Android Hardware Buffer -Android's NDK defines code:AHardwareBuffer objects, which represent device +Android's NDK defines dlink:AHardwareBuffer objects, which represent device memory that is shareable across processes and that can: be accessed by a variety of media APIs and the hardware used to implement them. These Android hardware buffer objects may: be imported into @@ -2880,18 +2880,18 @@ slink:VkDeviceMemory objects for access via Vulkan, or exported from Vulkan. [open,refpage='AHardwareBuffer',desc='Android hardware buffer type',type='defines'] -- To remove an unnecessary compile-time dependency, an incomplete type -definition of code:AHardwareBuffer is provided in the Vulkan headers: +definition of dlink:AHardwareBuffer is provided in the Vulkan headers: include::../api/defines/AHardwareBuffer.txt[] -The actual code:AHardwareBuffer type is defined in Android NDK headers. +The actual dlink:AHardwareBuffer type is defined in Android NDK headers. -- [NOTE] .Note ==== -The NDK format, usage, and size/dimensions of an code:AHardwareBuffer object -can be obtained with the code:AHardwareBuffer_describe function. +The NDK format, usage, and size/dimensions of an dlink:AHardwareBuffer +object can be obtained with the code:AHardwareBuffer_describe function. While Android hardware buffers can be imported to or exported from Vulkan without using that function, valid usage and implementation behavior is defined in terms of the code:AHardwareBuffer_Desc properties it returns. @@ -2901,7 +2901,7 @@ Android hardware buffer objects are reference-counted using Android NDK functions outside of the scope of this specification. A slink:VkDeviceMemory imported from an Android hardware buffer or that can: be exported to an Android hardware buffer must: acquire a reference to its -code:AHardwareBuffer object, and must: release this reference when the +dlink:AHardwareBuffer object, and must: release this reference when the device memory is freed. During the host execution of a Vulkan command that has an Android hardware buffer as a parameter (including indirect parameters via pname:pNext @@ -3000,7 +3000,7 @@ sname:VkExternalMemoryImageCreateInfo::pname:handleTypes that includes ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID. When creating an image that will be bound to an imported Android hardware buffer, the image creation parameters must: be equivalent to the -code:AHardwareBuffer properties as described by the valid usage of +dlink:AHardwareBuffer properties as described by the valid usage of slink:VkMemoryAllocateInfo. Similarly, device memory allocated for a dedicated image must: not be exported to an Android hardware buffer until it has been bound to that @@ -3113,7 +3113,7 @@ code:width; code:height and code:layers are both `1`. Unlike images, buffer resources backed by Android hardware buffers do not require dedicated allocations. -Exported code:AHardwareBuffer objects that do not have dedicated images +Exported dlink:AHardwareBuffer objects that do not have dedicated images must: have a format of code:AHARDWAREBUFFER_FORMAT_BLOB, usage must: include code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER, code:width must: equal the device memory allocation size, and code:height and code:layers must: be `1`. diff --git a/chapters/renderpass.txt b/chapters/renderpass.txt index 8099a684..352d2091 100644 --- a/chapters/renderpass.txt +++ b/chapters/renderpass.txt @@ -144,25 +144,18 @@ include::../api/structs/VkRenderPassCreateInfo.txt[] * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:flags is reserved for future use. * pname:attachmentCount is the number of attachments used by this render - pass, or zero indicating no attachments. - Attachments are referred to by zero-based indices in the range - [0,pname:attachmentCount). - * pname:pAttachments points to an array of pname:attachmentCount number of - slink:VkAttachmentDescription structures describing properties of the - attachments, or `NULL` if pname:attachmentCount is zero. - * pname:subpassCount is the number of subpasses to create for this render pass. - Subpasses are referred to by zero-based indices in the range - [0,pname:subpassCount). - A render pass must: have at least one subpass. - * pname:pSubpasses points to an array of pname:subpassCount number of - slink:VkSubpassDescription structures describing properties of the - subpasses. - * pname:dependencyCount is the number of dependencies between pairs of - subpasses, or zero indicating no dependencies. - * pname:pDependencies points to an array of pname:dependencyCount number - of slink:VkSubpassDependency structures describing dependencies between - pairs of subpasses, or `NULL` if pname:dependencyCount is zero. + * pname:pAttachments points to an array of pname:attachmentCount + slink:VkAttachmentDescription structures describing the attachments used + by the render pass. + * pname:subpassCount is the number of subpasses to create. + * pname:pSubpasses points to an array of pname:subpassCount + slink:VkSubpassDescription structures describing each subpass. + * pname:dependencyCount is the number of memory dependencies between pairs + of subpasses. + * pname:pDependencies points to an array of pname:dependencyCount + slink:VkSubpassDependency structures describing dependencies between + pairs of subpasses. [NOTE] .Note @@ -542,8 +535,6 @@ include::../api/structs/VkAttachmentDescription.txt[] be in when a render pass instance begins. * pname:finalLayout is the layout the attachment image subresource will be transitioned to when a render pass instance ends. - During a render pass instance, an attachment can: use a different layout - in each subpass, if desired. [[renderpass-load-store-ops]] If the attachment uses a color format, then pname:loadOp and pname:storeOp @@ -1087,11 +1078,10 @@ The sname:VkAttachmentReference structure is defined as: include::../api/structs/VkAttachmentReference.txt[] - * pname:attachment is the index of the attachment of the render pass, and - corresponds to the index of the corresponding element in the - pname:pAttachments array of the sname:VkRenderPassCreateInfo structure. - If any color or depth/stencil attachments are - ename:VK_ATTACHMENT_UNUSED, then no writes occur for those attachments. + * pname:attachment is either an integer value identifying an attachment at + the corresponding index in + slink:VkRenderPassCreateInfo::pname:pAttachments, or + ename:VK_ATTACHMENT_UNUSED to signify that this attachment is not used. * pname:layout is a elink:VkImageLayout value specifying the layout the attachment uses during the subpass. @@ -3211,4 +3201,3 @@ include::../validity/structs/VkSubpassEndInfoKHR.txt[] -- endif::VK_KHR_create_renderpass2[] - diff --git a/chapters/shaders.txt b/chapters/shaders.txt index 8f88694d..5bcc525c 100644 --- a/chapters/shaders.txt +++ b/chapters/shaders.txt @@ -122,7 +122,7 @@ ifdef::VK_NV_glsl_shader[] * [[VUID-VkShaderModuleCreateInfo-pCode-01377]] pname:pCode must: point to either valid SPIR-V code, formatted and packed as described by the <> - or valid GLSL code which must: be written to the +GL_KHR_vulkan_glsl+ + or valid GLSL code which must: be written to the `GL_KHR_vulkan_glsl` extension specification * [[VUID-VkShaderModuleCreateInfo-pCode-01378]] If pname:pCode points to SPIR-V code, that code must: adhere to the @@ -131,7 +131,7 @@ ifdef::VK_NV_glsl_shader[] <> appendix * [[VUID-VkShaderModuleCreateInfo-pCode-01379]] If pname:pCode points to GLSL code, it must: be valid GLSL code written - to the +GL_KHR_vulkan_glsl+ GLSL extension specification + to the `GL_KHR_vulkan_glsl` GLSL extension specification endif::VK_NV_glsl_shader[] * [[VUID-VkShaderModuleCreateInfo-pCode-01089]] pname:pCode must: declare the code:Shader capability for SPIR-V code @@ -1209,7 +1209,7 @@ pname:pDataSize. include::../validity/protos/vkGetValidationCacheDataEXT.txt[] -- -[open,refpage='VkValidationCacheHeaderVersionEXT',desc='Encode validation cache version',type='enums',xrefs='vkCreateValdiationCacheEXT vkGetValidationCacheDataEXT'] +[open,refpage='VkValidationCacheHeaderVersionEXT',desc='Encode validation cache version',type='enums',xrefs='vkCreateValidationCacheEXT vkGetValidationCacheDataEXT'] -- Possible values of the second group of four bytes in the header returned by flink:vkGetValidationCacheDataEXT, encoding the validation cache version, diff --git a/chapters/synchronization.txt b/chapters/synchronization.txt index 0516e25c..bd104cb0 100644 --- a/chapters/synchronization.txt +++ b/chapters/synchronization.txt @@ -368,9 +368,9 @@ ifdef::VK_NV_ray_tracing[] * ename:VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_NV specifies the execution of the ray tracing shader stages. * ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_NV specifies - the execution of vkCmdBuildAccelerationStructureNV, - vkCmdCopyAccelerationStructureNV, and - vkCmdWriteAccelerationStructuresPropertiesNV. + the execution of flink:vkCmdBuildAccelerationStructureNV, + flink:vkCmdCopyAccelerationStructureNV, and + flink:vkCmdWriteAccelerationStructuresPropertiesNV. endif::VK_NV_ray_tracing[] * ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT specifies the execution of all graphics pipeline stages, and is equivalent to the logical OR of: @@ -1947,7 +1947,7 @@ include::../api/structs/VkImportFenceWin32HandleInfoKHR.txt[] The handle types supported by pname:handleType are: [[synchronization-fence-handletypes-win32]] -.Handle Types Supported by VkImportFenceWin32HandleInfoKHR +.Handle Types Supported by slink:VkImportFenceWin32HandleInfoKHR [width="80%",options="header"] |==== | Handle Type | Transference | Permanence Supported @@ -2038,7 +2038,7 @@ include::../api/structs/VkImportFenceFdInfoKHR.txt[] The handle types supported by pname:handleType are: [[synchronization-fence-handletypes-fd]] -.Handle Types Supported by VkImportFenceFdInfoKHR +.Handle Types Supported by slink:VkImportFenceFdInfoKHR [width="80%",options="header"] |==== | Handle Type | Transference | Permanence Supported @@ -2854,7 +2854,7 @@ include::../api/structs/VkImportSemaphoreWin32HandleInfoKHR.txt[] The handle types supported by pname:handleType are: [[synchronization-semaphore-handletypes-win32]] -.Handle Types Supported by VkImportSemaphoreWin32HandleInfoKHR +.Handle Types Supported by slink:VkImportSemaphoreWin32HandleInfoKHR [width="80%",options="header"] |==== | Handle Type | Transference | Permanence Supported @@ -2952,7 +2952,7 @@ include::../api/structs/VkImportSemaphoreFdInfoKHR.txt[] The handle types supported by pname:handleType are: [[synchronization-semaphore-handletypes-fd]] -.Handle Types Supported by VkImportSemaphoreFdInfoKHR +.Handle Types Supported by slink:VkImportSemaphoreFdInfoKHR [width="80%",options="header"] |==== | Handle Type | Transference | Permanence Supported diff --git a/chapters/vertexpostproc.txt b/chapters/vertexpostproc.txt index d0f2f9a3..26f1aa57 100644 --- a/chapters/vertexpostproc.txt +++ b/chapters/vertexpostproc.txt @@ -265,6 +265,11 @@ feedback buffer will not be captured. The sum of pname:firstCounterBuffer and pname:counterBufferCount must: be less than or equal to sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBuffers + * [[VUID-vkCmdBeginTransformFeedbackEXT-counterBufferCount-02607]] + If pname:counterBufferCount is not `0`, and pname:pCounterBuffers is not + `NULL`, pname:pCounterBuffers must: be a valid pointer to an array of + pname:counterBufferCount sname:VkBuffer handles that are either valid or + dlink:VK_NULL_HANDLE * [[VUID-vkCmdBeginTransformFeedbackEXT-pCounterBufferOffsets-02370]] For each buffer handle in the array, if it is not dlink:VK_NULL_HANDLE it must: reference a buffer large enough to hold 4 bytes at the @@ -334,6 +339,11 @@ include::../api/protos/vkCmdEndTransformFeedbackEXT.txt[] The sum of pname:firstCounterBuffer and pname:counterBufferCount must: be less than or equal to sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBuffers + * [[VUID-vkCmdEndTransformFeedbackEXT-counterBufferCount-02608]] + If pname:counterBufferCount is not `0`, and pname:pCounterBuffers is not + `NULL`, pname:pCounterBuffers must: be a valid pointer to an array of + pname:counterBufferCount sname:VkBuffer handles that are either valid or + dlink:VK_NULL_HANDLE * [[VUID-vkCmdEndTransformFeedbackEXT-pCounterBufferOffsets-02378]] For each buffer handle in the array, if it is not dlink:VK_NULL_HANDLE it must: reference a buffer large enough to hold 4 bytes at the diff --git a/include/vulkan/vulkan_core.h b/include/vulkan/vulkan_core.h index caeecd9b..e0349bdc 100644 --- a/include/vulkan/vulkan_core.h +++ b/include/vulkan/vulkan_core.h @@ -43,7 +43,7 @@ extern "C" { #define VK_VERSION_MINOR(version) (((uint32_t)(version) >> 12) & 0x3ff) #define VK_VERSION_PATCH(version) ((uint32_t)(version) & 0xfff) // Version of this file -#define VK_HEADER_VERSION 97 +#define VK_HEADER_VERSION 98 #define VK_NULL_HANDLE 0 @@ -6244,7 +6244,7 @@ typedef struct VkPhysicalDeviceDepthStencilResolvePropertiesKHR { #define VK_KHR_vulkan_memory_model 1 -#define VK_KHR_VULKAN_MEMORY_MODEL_SPEC_VERSION 2 +#define VK_KHR_VULKAN_MEMORY_MODEL_SPEC_VERSION 3 #define VK_KHR_VULKAN_MEMORY_MODEL_EXTENSION_NAME "VK_KHR_vulkan_memory_model" typedef struct VkPhysicalDeviceVulkanMemoryModelFeaturesKHR { @@ -6252,6 +6252,7 @@ typedef struct VkPhysicalDeviceVulkanMemoryModelFeaturesKHR { void* pNext; VkBool32 vulkanMemoryModel; VkBool32 vulkanMemoryModelDeviceScope; + VkBool32 vulkanMemoryModelAvailabilityVisibilityChains; } VkPhysicalDeviceVulkanMemoryModelFeaturesKHR; diff --git a/reflow.py b/reflow.py index ed93a1df..6af76562 100755 --- a/reflow.py +++ b/reflow.py @@ -335,53 +335,60 @@ class ReflowState: # Emit a paragraph, possibly reflowing it depending on the block # context. Reset the paragraph accumulator. def emitPara(self): - global vuPat + global vuPat, nestedVuPat if self.para != []: - if (self.vuStack[-1] and - self.nextvu != None and - self.vuPrefix not in self.para[0]): + if self.vuStack[-1] and self.nextvu != None: # If: # - this paragraph is in a Valid Usage block, # - VUID tags are being assigned, - # - a tag is not already present, and - # - the paragraph is a properly marked-up list item - # Then add a VUID tag starting with the next free ID. + # Try to assign VUIDs - # Split the first line after the bullet point - matches = vuPat.search(self.para[0]) - if matches != None: - logDiag('findRefs: Matched vuPat on line:', self.para[0], end='') - head = matches.group('head') - tail = matches.group('tail') - - # Use the first pname: statement in the paragraph as - # the parameter name in the VUID tag. This won't always - # be correct, but should be highly reliable. - for vuLine in self.para: - matches = pnamePat.search(vuLine) - if matches != None: - break + if nestedVuPat.search(self.para[0]): + # Check for nested bullet points. These should not be + # assigned VUIDs, nor present at all, because they break + # the VU extractor. + logWarn(self.filename + ': Invalid nested bullet point in VU block:', self.para[0]) + elif self.vuPrefix not in self.para[0]: + # If: + # - a tag is not already present, and + # - the paragraph is a properly marked-up list item + # Then add a VUID tag starting with the next free ID. + # Split the first line after the bullet point + matches = vuPat.search(self.para[0]) if matches != None: - paramName = matches.group('param') - else: - paramName = 'None' - logWarn(self.filename, - 'No param name found for VUID tag on line:', - self.para[0]) + logDiag('findRefs: Matched vuPat on line:', self.para[0], end='') + head = matches.group('head') + tail = matches.group('tail') - newline = (head + ' [[' + - self.vuFormat.format(self.vuPrefix, - self.apiName, - paramName, - self.nextvu) + ']] ' + tail) + # Use the first pname: statement in the paragraph as + # the parameter name in the VUID tag. This won't always + # be correct, but should be highly reliable. + for vuLine in self.para: + matches = pnamePat.search(vuLine) + if matches != None: + break - logDiag('Assigning', self.vuPrefix, self.apiName, self.nextvu, - ' on line:', self.para[0], '->', newline, 'END') + if matches != None: + paramName = matches.group('param') + else: + paramName = 'None' + logWarn(self.filename, + 'No param name found for VUID tag on line:', + self.para[0]) - self.para[0] = newline - self.nextvu = self.nextvu + 1 + newline = (head + ' [[' + + self.vuFormat.format(self.vuPrefix, + self.apiName, + paramName, + self.nextvu) + ']] ' + tail) + + logDiag('Assigning', self.vuPrefix, self.apiName, self.nextvu, + ' on line:', self.para[0], '->', newline, 'END') + + self.para[0] = newline + self.nextvu = self.nextvu + 1 # else: # There are only a few cases of this, and they're all # legitimate. Leave detecting this case to another tool @@ -612,7 +619,9 @@ def reflowAllAdocFiles(folder_to_reflow, args): # the trailing newline. global vuPat vuPat = re.compile('^(?P [*]+)( *)(?P.*)', re.DOTALL) - +# Pattern matching leading nested bullet points +global nestedVuPat +nestedVuPat = re.compile('^ \*\*') if __name__ == '__main__': parser = argparse.ArgumentParser() diff --git a/reflow_count.py b/reflow_count.py index 7baefae3..5e8f1a7e 100644 --- a/reflow_count.py +++ b/reflow_count.py @@ -1,2 +1,2 @@ # The value to start tagging VU statements at, unless overridden by -nextvu -startVUID = 2607 +startVUID = 2609 diff --git a/style/extensions.txt b/style/extensions.txt index a244600d..f6cb1027 100644 --- a/style/extensions.txt +++ b/style/extensions.txt @@ -753,9 +753,32 @@ For core Vulkan API and KHR extension bitmask types, reservations must be approved by a vote of the Vulkan Working Group. For EXT and vendor extension bitmask types, reservations must be approved by the listed contact of the extension. -Bits are not reserved, and must not be used in a published implementation or -specification until the reservation is merged into -<> by the registry maintainer. +Bits are reserved in the same fashion as extension numbers, by creating a +dummy reservation for each bit in the disabled XML `` block for +that extension in the `master` branch. +Once the extension is ready to be merged into `master`, the `` +block is updated with the actual name. +An example reservation for a disabled extension is: + +[source,xml] +---- + + + +---- + +[NOTE] +.Note +==== +Because of the way in which extension bitmask values are assigned inside the +XML `` tag, it is not always obvious what the next free bit in a +bitmask type is, or when a collision occurs. +The most straightforward way to determine the next free bit for a given +bitmask type is to look at the declaration of that type in the generated +header files. +When generating the headers, the script will raise warnings about "`Two +enums found with the same value`" that will help identify this problem. +==== == Required Extension Tokens diff --git a/styleguide.txt b/styleguide.txt index f9fe8d4a..c2cd5e7b 100644 --- a/styleguide.txt +++ b/styleguide.txt @@ -150,6 +150,8 @@ include::style/vuid.txt[] = Revision History +* 2019-01-06 - Add details on <> (internal issue 1411). * 2018-11-19 - Add details to the <> section including the new "`Description`" section, and other standard parts of extension appendices. diff --git a/xml/check_spec_links.py b/xml/check_spec_links.py index 4d3960d4..8ce6f39e 100755 --- a/xml/check_spec_links.py +++ b/xml/check_spec_links.py @@ -1,6 +1,6 @@ #!/usr/bin/python3 # -# Copyright (c) 2018 Collabora, Ltd. +# Copyright (c) 2018-2019 Collabora, Ltd. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -47,8 +47,7 @@ ENTITIES_WITHOUT_VALIDITY = set( SYSTEM_TYPES = set(['void', 'char', 'float', 'size_t', 'uintptr_t', 'int8_t', 'uint8_t', 'int32_t', 'uint32_t', - 'int64_t', 'uint64_t', 'ANativeWindow', 'AHardwareBuffer']) - + 'int64_t', 'uint64_t']) PLATFORM_REQUIRES = 'vk_platform' @@ -64,6 +63,17 @@ INCLUDE = re.compile( r'include::(?P((../){1,4}|\{INCS-VAR\}/))(?P[\w]+)/(?P\w+)/(?P[^./]+).txt[[][]]') ANCHOR = re.compile(r'\[\[(?P[^\]]+)\]\]') +BRACKETS = re.compile(r'\[(?P.*)\]') + + +def makeRefPageRE(field_name): + return re.compile(r",{}='(?P[^']*)'".format(field_name)) + + +REF_PAGE_TAGS = { + field: makeRefPageRE(field) for field in ['refpage', 'desc', 'xrefs', 'type'] +} + MEMBER_REFERENCE = re.compile( r'\b(?P(?P[fs](text|link)):(?P[\w*]+))(?P::)(?P(?Ppname:?)(?P[\w]+))\b' ) @@ -191,7 +201,7 @@ def shouldEntityBeText(entity, subscript): EntityData = namedtuple( - 'EntityData', ['entity', 'macro', 'elem', 'filename', 'category']) + 'EntityData', ['entity', 'macro', 'elem', 'filename', 'category', 'directory']) def entityToDict(data): @@ -242,6 +252,12 @@ class MessageId(Enum): MISSING_API_INCLUDE = 16 MISUSED_TEXT = 17 EXTENSION = 18 + REFPAGE_TAG = 19 + REFPAGE_MISSING_DESC = 20 + REFPAGE_XREFS = 21 + REFPAGE_XREFS_COMMA = 22 + REFPAGE_TYPE = 23 + REFPAGE_NAME = 24 def __str__(self): return self.name.lower() @@ -290,6 +306,18 @@ class MessageId(Enum): return "a *text: macro is found but not expected" elif self == MessageId.EXTENSION: return "an extension name is incorrectly marked" + elif self == MessageId.REFPAGE_TAG: + return "a refpage tag is missing an expected field" + elif self == MessageId.REFPAGE_MISSING_DESC: + return "a refpage tag has an empty description" + elif self == MessageId.REFPAGE_XREFS: + return "an unrecognized entity is mentioned in xrefs of a refpage tag" + elif self == MessageId.REFPAGE_XREFS_COMMA: + return "a comma was founds in xrefs of a refpage tag, which is space-delimited" + elif self == MessageId.REFPAGE_TYPE: + return "a refpage tag has an incorrect type field" + elif self == MessageId.REFPAGE_NAME: + return "a refpage tag has an unrecognized entity name in its refpage field" @classmethod def default_set(self): @@ -514,12 +542,14 @@ class MacroCheckerFile(object): self.diag(MessageType.ERROR, message_id, messageLines, group, replacement, context, fix, see_also) - def storeMessageContext(self, group=None): + def storeMessageContext(self, group=None, match=None): """Create message context from corresponding instance variables.""" + if match is None: + match = self.match return MessageContext(filename=self.filename, lineNum=self.lineNum, line=self.line, - match=self.match, + match=match, group=group) def makeFix(self, newMacro=None, newEntity=None, data=None): @@ -791,6 +821,123 @@ class MacroCheckerFile(object): else: include_dict[entity] = [self.storeMessageContext()] + def checkRefPageXref(self, referenced_entity, line_context): + data = self.checker.findEntity(referenced_entity) + if data: + # This is OK + return + context = line_context + match = re.search(r'\b{}\b'.format(referenced_entity), self.line) + if match: + context = self.storeMessageContext( + group=None, match=match) + msg = [ + "Found reference page markup, with an unrecognized entity listed: {}".format(referenced_entity)] + + see_also = None + dataArray = self.checker.findEntityCaseInsensitive( + referenced_entity) + + if dataArray: + # We might have found the goof... + + if len(dataArray) == 1: + # Yep, found the goof - incorrect entity capitalization + data = dataArray[0] + new_entity = data.entity + self.error(MessageId.REFPAGE_XREFS, msg + ['Apparently matching entity in category {} found by searching case-insensitively.'.format(data.category)], + replacement=new_entity, + fix=(referenced_entity, new_entity), + context=context) + return + + # Ugh, more than one resolution + msg.append( + 'More than one apparent match found by searching case-insensitively, cannot auto-fix.') + see_also = dataArray[:] + + # Multiple or no resolutions found + self.error(MessageId.REFPAGE_XREFS, + msg, + see_also=see_also, + context=context) + + def checkRefPageXrefs(self, xrefs_match): + text = xrefs_match.group('text') + context = self.storeMessageContext(group='text', match=xrefs_match) + if ',' in text: + self.error(MessageId.REFPAGE_XREFS_COMMA, + "Found reference page markup, with an unexpected comma in the (space-delimited) field xrefs='{}'".format( + text), + context=context) + return + + refs = text.split() + # Don't do this if we found a comma, since that's a clearer error message + for entity in refs: + self.checkRefPageXref(entity, context) + + def checkRefPage(self): + line = self.line + + # Should always be found + self.match = BRACKETS.match(line) + + data = None + directory = None + refpage = REF_PAGE_TAGS['refpage'].search(line) + if refpage: + text = refpage.group('text') + data = self.checker.findEntity(text) + if data: + directory = data.directory + else: + # TODO suggest fixes here if applicable + context = self.storeMessageContext( + group='text', match=refpage) + self.error(MessageId.REFPAGE_NAME, + "Found reference page markup, but refpage='{}' does not refer to a recognized entity".format( + text), + context=context) + + else: + self.error(MessageId.REFPAGE_TAG, + "Found apparent reference page markup, but missing refpage='...'", + group=None) + + desc = REF_PAGE_TAGS['desc'].search(line) + if desc: + text = desc.group('text') + if not text: + context = self.storeMessageContext(group=None, match=desc) + self.warning(MessageId.REFPAGE_MISSING_DESC, + "Found reference page markup, but desc='' is empty", + context=context) + else: + self.error(MessageId.REFPAGE_TAG, + "Found apparent reference page markup, but missing desc='...'", + group=None) + + ref_type = REF_PAGE_TAGS['type'].search(line) + if ref_type: + text = ref_type.group('text') + if directory and not text == directory: + context = self.storeMessageContext( + group='text', match=ref_type) + self.error(MessageId.REFPAGE_TYPE, + "Found reference page markup, but type='{}' is not the expected value '{}'".format( + text, directory), + context=context) + else: + self.error(MessageId.REFPAGE_TAG, + "Found apparent reference page markup, but missing type='...'", + group=None) + + xrefs = REF_PAGE_TAGS['xrefs'].search(line) + if xrefs: + # This field is optional + self.checkRefPageXrefs(xrefs) + def processLine(self, lineNum, line): self.lineNum = lineNum self.line = line @@ -821,8 +968,9 @@ class MacroCheckerFile(object): ### # Detect [open, lines for manpages - # TODO: Verify these (and use for pname context) instead of skipping them. - if line.startswith('[open,refpage='): + # TODO: Use these for pname context too. + if line.startswith('[open,'): + self.checkRefPage() return ### @@ -1190,7 +1338,8 @@ class MacroChecker(object): macro=macro, elem=elem, filename=filename, - category=category + category=category, + directory=directory ) if entityName in self.byEntity: # skip @@ -1319,7 +1468,7 @@ class MacroChecker(object): def processString(self, s): """For testing purposes""" - filename = "string{}".format(len(self.files)) + filename = "string{}: {}".format(len(self.files), s) class StringStreamMaker(object): def __init__(self, string): @@ -1938,17 +2087,17 @@ if __name__ == '__main__': disable_arg = message_id.disable_arg() disable_args.append((message_id, disable_arg)) if message_id in enabled_messages: - parser.add_argument('-' + enable_arg, action="store_true", + parser.add_argument('-' + disable_arg, action="store_true", help="Disable message category {}: {}".format(str(message_id), message_id.desc())) - # Don't show the disable flag in help since it's disabled by default - parser.add_argument('-' + disable_arg, action="store_true", - help=argparse.SUPPRESS) - else: - parser.add_argument('-' + disable_arg, action="store_true", - help="Enable message category {}: {}".format(str(message_id), message_id.desc())) # Don't show the enable flag in help since it's enabled by default parser.add_argument('-' + enable_arg, action="store_true", help=argparse.SUPPRESS) + else: + parser.add_argument('-' + enable_arg, action="store_true", + help="Enable message category {}: {}".format(str(message_id), message_id.desc())) + # Don't show the disable flag in help since it's disabled by default + parser.add_argument('-' + disable_arg, action="store_true", + help=argparse.SUPPRESS) args = parser.parse_args() @@ -1994,13 +2143,22 @@ if __name__ == '__main__': numErrors = checker.numErrors() check_includes = args.include_warn - check_broken = True - if args.file and args.include_warn: - print('Note: forcing --include_warn off because only checking supplied files.') - printer.outputResults(checker, broken_links=(not args.file), - missing_includes=(args.include_warn and not args.file)) + check_broken = not args.file - if args.include_error and not args.file: + if args.file and check_includes: + print('Note: forcing --include_warn off because only checking supplied files.') + check_includes = False + + printer.outputResults(checker, broken_links=(not args.file), + missing_includes=check_includes) + + if check_broken: + numErrors += len(checker.getBrokenLinks()) + + if args.file and args.include_error: + print('Note: forcing --include_error off because only checking supplied files.') + args.include_error = False + if args.include_error: numErrors += len(checker.getMissingUnreferencedApiIncludes()) printer.close() diff --git a/xml/test_check_spec_links.py b/xml/test_check_spec_links.py index bb494dcf..1e71f286 100644 --- a/xml/test_check_spec_links.py +++ b/xml/test_check_spec_links.py @@ -1,6 +1,6 @@ #!/usr/bin/python3 # -# Copyright (c) 2018 Collabora, Ltd. +# Copyright (c) 2018-2019 Collabora, Ltd. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -18,28 +18,38 @@ # # Purpose: This file contains tests for check_spec_links.py -from check_spec_links import MacroChecker, MessageId, shouldEntityBeText +from check_spec_links import MacroChecker, MessageId, shouldEntityBeText, ConsolePrinter import pytest class CheckerWrapper(object): + """Little wrapper object for a MacroChecker. + + Intended for use in making test assertions shorter and easier to read.""" + def __init__(self): self.ckr = MacroChecker(set([])) def enabled(self, enabled_messages): + """Updates the checker's enable message type set, from an iterable""" self.ckr.enabled_messages = set(enabled_messages) return self def check(self, string): - return self.ckr.processString(string + '\n') + """Checks a string (as if it were a file), outputs the results to the console, then returns the MacroFileChecker""" + f = self.ckr.processString(string + '\n') + ConsolePrinter().output(f) + return f @pytest.fixture def ckr(): + """Fixture - add an arg named ckr to your test function to automatically get one passed to you.""" return CheckerWrapper() def replacement(ckr): + """Returns the replacement text associated with the first message of a file checker""" assert(len(ckr.messages) == 1) from pprint import pprint pprint(ckr.messages[0].script_location) @@ -49,9 +59,12 @@ def replacement(ckr): def test_missing_macro(ckr): + """Verify correct functioning of MessageId.MISSING_MACRO""" ckr.enabled([MessageId.MISSING_MACRO]) + # This should have a missing macro warning assert(ckr.check('with vkFreeMemory by').numDiagnostics() == 1) + # These 3 should not have a missing macro warning because of their context (in a link) assert(not ckr.check('<>').messages) assert(not ckr.check( @@ -64,6 +77,8 @@ def test_entity_detection(ckr): assert(ckr.check('flink:abcd').numDiagnostics() == 1) # Should just give BAD_ENTITY (an error), not MISSING_TEXT (a warning). + # Verifying that wrapping in asterisks (for formatting) doesn't get picked up as + # an asterisk in the entity name (a placeholder). ckr.enabled( [MessageId.MISSING_TEXT, MessageId.BAD_ENTITY]) assert(ckr.check('*flink:abcd*').numErrors() == 1) @@ -71,7 +86,10 @@ def test_entity_detection(ckr): def test_wrong_macro(ckr): ckr.enabled([MessageId.WRONG_MACRO]) + # Should error - this ought to be code:uint32_t assert(ckr.check('basetype:uint32_t').numErrors() == 1) + + # This shouldn't error assert(ckr.check('code:uint32_t').numErrors() == 0) @@ -83,15 +101,28 @@ def test_legacy(ckr): def test_should_entity_be_text(): + # These 5 are all examples of patterns that would merit usage of a ptext/etext/etc + # macro, for various reasons: + + # has variable in subscript assert(shouldEntityBeText('pBuffers[i]', '[i]')) - assert(shouldEntityBeText('maxPerStage*', None)) assert(shouldEntityBeText('VK_MEMORY_PLANE_[X]', '[X]')) + + # has asterisk + assert(shouldEntityBeText('maxPerStage*', None)) + + # double-underscores make italicized placeholders + # (triple are double-underscores delimited by underscores...) assert(shouldEntityBeText('VK_MEMORY_PLANE[__x__]', '[__x__]')) assert(shouldEntityBeText('VK_MEMORY_PLANE___i___BIT_EXT', None)) + + # This shouldn't be a *text: macro because it only has single underscores assert(False == shouldEntityBeText('VK_MEMORY_PLANE_i_BIT_EXT', None)) def test_misused_text(ckr): + # Tests the same patterns as test_should_entity_be_text(), + # but in a whole checker ckr.enabled([MessageId.MISUSED_TEXT]) assert(ckr.check('etext:VK_MEMORY_PLANE_').numDiagnostics() == 0) @@ -102,32 +133,125 @@ def test_misused_text(ckr): # Should be OK, since __i__ is a placeholder here assert(ckr.check('etext:VK_MEMORY_PLANE___i___BIT_EXT').numDiagnostics() == 0) + # This shouldn't be a *text: macro because it only has single underscores + assert(ckr.check('VK_MEMORY_PLANE_i_BIT_EXT').numDiagnostics() == 0) def test_extension(ckr): ckr.enabled(set(MessageId)) - expected_replacement = '`<>`' + # Check formatting of extension names: + # the following is the canonical way to refer to an extension + # (link wrapped in backticks) + expected_replacement='`<>`' + + # Extension name mentioned without any markup, should be added assert(ckr.check('asdf VK_NV_mesh_shader asdf').messages) assert(replacement(ckr.check('asdf VK_NV_mesh_shader asdf')) == expected_replacement) + # Extension name mentioned without any markup and wrong case, + # should be added and have case fixed assert(ckr.check('asdf VK_NV_MESH_SHADER asdf').messages) assert(replacement(ckr.check('asdf VK_NV_MESH_SHADER asdf')) == expected_replacement) + # Extension name using wrong/old macro: ename isn't for extensions. assert(ckr.check('asdf ename:VK_NV_mesh_shader asdf').messages) assert(replacement(ckr.check('asdf ename:VK_NV_mesh_shader asdf')) == expected_replacement) + # Extension name using wrong macro: elink isn't for extensions. assert(ckr.check('asdf elink:VK_NV_mesh_shader asdf').messages) assert(replacement(ckr.check('asdf elink:VK_NV_mesh_shader asdf')) == expected_replacement) + # Extension name using wrong macro and wrong case: should have markup and case fixed assert(ckr.check('asdf elink:VK_NV_MESH_SHADER asdf').messages) assert(replacement(ckr.check('asdf elink:VK_NV_MESH_SHADER asdf')) == expected_replacement) + # This shouldn't cause errors because this is how we want it to look. assert(not ckr.check('asdf `<>` asdf').messages) + + # This doesn't (shouldn't?) cause errors because just backticks on their own + # "escape" names from the "missing markup" tests. assert(not ckr.check('asdf `VK_NV_mesh_shader` asdf').messages) # TODO can we auto-correct this to add the backticks? + # Doesn't error now, but would be nice if it did... assert(not ckr.check('asdf <> asdf').messages) + + +def test_refpage_tag(ckr): + ckr.enabled([MessageId.REFPAGE_TAG]) + + # Should error: missing refpage='' field + assert(ckr.check("[open,desc='',type='',xrefs='']").numErrors() == 1) + # Should error: missing desc='' field + assert(ckr.check("[open,refpage='',type='',xrefs='']").numErrors() == 1) + # Should error: missing type='' field + assert(ckr.check("[open,refpage='',desc='',xrefs='']").numErrors() == 1) + + # Should not error: missing xrefs field is optional + assert(not ckr.check("[open,refpage='',desc='',type='']").messages) + + +def test_refpage_name(ckr): + ckr.enabled([MessageId.REFPAGE_NAME]) + # Should not error: vkCreateInstance actually exists. + assert(ckr.check( + "[open,refpage='vkCreateInstance',desc='',type='']").numDiagnostics() == 0) + + # Should error: vkBogus does not exist. + assert( + ckr.check("[open,refpage='vkBogus',desc='',type='']").numDiagnostics() == 1) + + +def test_refpage_missing_desc(ckr): + ckr.enabled([MessageId.REFPAGE_MISSING_DESC]) + # Should not warn: non-empty description actually exists. + assert(ckr.check( + "[open,refpage='',desc='non-empty description',type='']").numDiagnostics() == 0) + + # Should warn: desc field is empty. + assert( + ckr.check("[open,refpage='',desc='',type='']").numDiagnostics() == 1) + + +def test_refpage_type(ckr): + ckr.enabled([MessageId.REFPAGE_TYPE]) + # Should not error: this is of type 'protos'. + assert(not ckr.check( + "[open,refpage='vkCreateInstance',desc='',type='protos']").messages) + + # Should error: this is of type 'protos', not 'structs'. + assert( + ckr.check("[open,refpage='vkCreateInstance',desc='',type='structs']").messages) + + +def test_refpage_xrefs(ckr): + ckr.enabled([MessageId.REFPAGE_XREFS]) + # Should not error: VkInstanceCreateInfo is a valid entity to have an xref to. + assert(not ckr.check( + "[open,refpage='vkCreateInstance',desc='',type='protos',xrefs='VkInstanceCreateInfo']").messages) + + # case difference: + # should error but offer a replacement. + assert(ckr.check( + "[open,refpage='vkCreateInstance',desc='',type='protos',xrefs='vkInstanceCreateInfo']").numDiagnostics() == 1) + assert(replacement(ckr.check("[open,refpage='vkCreateInstance',desc='',type='protos',xrefs='vkInstanceCreateInfo']")) + == 'VkInstanceCreateInfo') + + # Should error: not a valid entity. + assert(ckr.check( + "[open,refpage='xrCreateInstance',desc='',type='protos',xrefs='xrBogus']").numDiagnostics() == 1) + + +def test_refpage_xrefs_comma(ckr): + ckr.enabled([MessageId.REFPAGE_XREFS_COMMA]) + # Should not error: no commas in the xrefs field + assert(not ckr.check( + "[open,refpage='vkCreateInstance',desc='',type='protos',xrefs='VkInstanceCreateInfo']").messages) + # Should error: commas shouldn't be there since it's space-delimited + + assert(ckr.check( + "[open,refpage='vkCreateInstance',desc='',type='protos',xrefs='VkInstanceCreateInfo,']").numDiagnostics() == 1) diff --git a/xml/vk.xml b/xml/vk.xml old mode 100644 new mode 100755 index 18e4d029..9f7a73be --- a/xml/vk.xml +++ b/xml/vk.xml @@ -146,7 +146,7 @@ server. // Vulkan 1.1 version number #define VK_API_VERSION_1_1 VK_MAKE_VERSION(1, 1, 0)// Patch version should always be set to 0 // Version of this file -#define VK_HEADER_VERSION 97 +#define VK_HEADER_VERSION 98 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; @@ -1985,7 +1985,7 @@ server. VkImageTiling tiling - + VkStructureType sType void* pNext uint32_t maxPushDescriptors @@ -2541,7 +2541,7 @@ server. uint32_t viewportCount const VkViewportSwizzleNV* pViewportSwizzles - + VkStructureType sType void* pNext uint32_t maxDiscardRectanglesmax number of active discard rectangles @@ -2762,7 +2762,7 @@ server. void* pNext VkBool32 protectedMemory - + VkStructureType sType void* pNext VkBool32 protectedNoFault @@ -2894,7 +2894,7 @@ server. VkPipelineCoverageModulationStateCreateFlagsNV flags VkCoverageModulationModeNV coverageModulationMode VkBool32 coverageModulationTableEnable - uint32_t coverageModulationTableCount + uint32_t coverageModulationTableCount const float* pCoverageModulationTable @@ -2939,7 +2939,7 @@ server. VkBool32 shaderFloat16 VkBool32 shaderInt8 - + VkStructureType sType void* pNext VkBool32 separateDenormSettings @@ -3040,17 +3040,17 @@ server. VkExternalMemoryHandleTypeFlagBits handleType void* pHostPointer - + VkStructureType sType void* pNext uint32_t memoryTypeBits - + VkStructureType sType void* pNext VkDeviceSize minImportedHostPointerAlignment - + VkStructureType sType void* pNextPointer to next structure float primitiveOverestimationSizeThe size in pixels the primitive is enlarged at each edge during conservative rasterization @@ -3240,7 +3240,7 @@ server. uint32_t vertexBindingDivisorCount const VkVertexInputBindingDivisorDescriptionEXT* pVertexBindingDivisors - + VkStructureType sType void* pNext uint32_t maxVertexAttribDivisormax value of vertex attribute divisor @@ -3314,6 +3314,7 @@ server. void* pNext VkBool32 vulkanMemoryModel VkBool32 vulkanMemoryModelDeviceScope + VkBool32 vulkanMemoryModelAvailabilityVisibilityChains VkStructureType sType @@ -3479,7 +3480,7 @@ server. VkBool32 taskShader VkBool32 meshShader - + VkStructureType sType void* pNext uint32_t maxDrawMeshTasksCount @@ -3592,7 +3593,7 @@ server. VkAccelerationStructureMemoryRequirementsTypeNV type VkAccelerationStructureNV accelerationStructure - + VkStructureType sType void* pNext uint32_t shaderGroupHandleSize @@ -3604,7 +3605,7 @@ server. uint64_t maxTriangleCount uint32_t maxDescriptorSetAccelerationStructures - + VkStructureType sType void* pNext uint32_t drmFormatModifierCount @@ -6898,16 +6899,16 @@ server. void vkCmdBeginTransformFeedbackEXT VkCommandBuffer commandBuffer uint32_t firstCounterBuffer - uint32_t counterBufferCount - const VkBuffer* pCounterBuffers + uint32_t counterBufferCount + const VkBuffer* pCounterBuffers const VkDeviceSize* pCounterBufferOffsets void vkCmdEndTransformFeedbackEXT VkCommandBuffer commandBuffer uint32_t firstCounterBuffer - uint32_t counterBufferCount - const VkBuffer* pCounterBuffers + uint32_t counterBufferCount + const VkBuffer* pCounterBuffers const VkDeviceSize* pCounterBufferOffsets @@ -10088,7 +10089,7 @@ server. - + @@ -10366,5 +10367,11 @@ server. + + + + + +