From 911a7646949e661b24ad6111479029ed9e841284 Mon Sep 17 00:00:00 2001 From: Jon Leech <oddhack@sonic.net> Date: Sun, 7 Oct 2018 06:10:21 -0700 Subject: [PATCH] Change log for October 7, 2018 Vulkan 1.1.87 spec update: * Update release number to 87. Public Issues: * Merge flink:vkCmdPipelineBarrier self-dependency barrier VUs referring to the same subpass dependency (public pull request 756). * Describe default value of `"optional"` attribute in the registry schema document (public issue 769) * Fix links in <<VK_NVX_raytracing>> extension (public pull request 805). * Mark the <<VK_KHR_mir_surface>> extension obsolete (see public issue 814 - does not close this, however). * Fix missing endif in Image Creation block (public issue 817). Internal Issues: * Clarify that the compressed texture formats corresponding to <<features-features-textureCompressionETC2>>, <<features-features-textureCompressionASTC_LDR>>, and <<features-features-textureCompressionBC>> is not contingent on the feature bits, and may be supported even if the features are not enabled (internal issue 663). * Clarify that code:FragStencilRefEXT is output only in the <<interfaces-builtin-variables, Built-In Variables>> section (internal issue 1173). * Identify and correct many overly-aggressive uses of "`undefined`", and narrow them down, where straightforward to do so. Mark such resolved uses of "`undefined`" with the custom undefined: macro. Add a new <<writing-undefined, Describing Undefined Behavior>> section (internal issue 1267). * Don't require code:inline_uniform_block descriptors to be populated before use in the flink:vkAllocateDescriptorSets section (internal issue 1380). * Allow suppressing inline SVG images by controlling this with an attribute set in the Makefile, rather than the explicit [%inline] directive (internal issue 1391). * Mark 'Khronos' as a registered trademark in several places, now that it is one. * Fix typo in the <<VK_KHR_shader_atomic_int64>> appendix using the GLSL naming of the compare exchange op when referring to the SPIR-V op. * Specify in the flink:vkGetPhysicalDeviceQueueFamilyProperties section that all implementations must support at least one queue family, and that every queue family must contain at least one queue. * Make slink:VkPipelineDynamicStateCreateInfo::pname:dynamicStateCount, slink:VkSampleLocationsInfoEXT::pname:sampleLocationsPerPixel, and slink:VkSampleLocationsInfoEXT::pname:sampleLocationsCount optional, to fix bogus implicit valid usage checks that were causing failures in the conformance tests. * Fix vendor tag in reserved extension 237 constants. Does not affect anything since it's just a placeholder, but this should avoid further comments. * Minor markup fixes in some extension appendices. New Extensions: * `<<VK_FUCHSIA_imagepipe_surface>>` --- ChangeLog.txt | 62 ++- Makefile | 8 +- appendices/VK_EXT_debug_utils.txt | 9 +- .../VK_EXT_depth_range_unrestricted.txt | 11 +- appendices/VK_EXT_external_memory_host.txt | 4 +- .../VK_EXT_image_drm_format_modifier.txt | 444 +++++++++--------- appendices/VK_FUCHSIA_imagepipe_surface.txt | 49 ++ appendices/VK_KHR_external_semaphore.txt | 2 +- appendices/VK_KHR_shader_atomic_int64.txt | 4 +- appendices/VK_KHR_swapchain.txt | 4 +- appendices/VK_KHR_win32_surface.txt | 2 +- .../VK_NV_representative_fragment_test.txt | 11 +- appendices/VK_NV_shader_image_footprint.txt | 5 +- appendices/VK_NV_viewport_swizzle.txt | 60 ++- appendices/boilerplate.txt | 2 +- appendices/glossary.txt | 20 +- appendices/spirvenv.txt | 9 +- .../advanced_blend.txt | 2 +- chapters/VK_EXT_debug_report.txt | 4 +- chapters/VK_EXT_debug_utils.txt | 2 +- .../platformCreateSurface_imagepipe.txt | 53 +++ .../platformQuerySupport_imagepipe.txt | 12 + chapters/VK_KHR_surface/wsi.txt | 8 + chapters/VK_KHR_swapchain/wsi.txt | 29 +- .../platformCreateSurface_wayland.txt | 4 +- .../platformCreateSurface_vi.txt | 4 +- .../generation.txt | 4 +- chapters/clears.txt | 2 +- chapters/cmdbuffers.txt | 13 +- chapters/copies.txt | 19 +- chapters/descriptorsets.txt | 22 +- chapters/devsandqueues.txt | 24 +- chapters/drawing.txt | 38 +- chapters/features.txt | 27 +- chapters/fragops.txt | 4 +- chapters/fundamentals.txt | 14 +- chapters/initialization.txt | 16 +- chapters/interfaces.txt | 32 +- chapters/introduction.txt | 4 +- chapters/memory.txt | 23 +- chapters/pipelines.txt | 19 +- chapters/primsrast.txt | 11 +- chapters/queries.txt | 12 +- chapters/renderpass.txt | 22 +- chapters/resources.txt | 50 +- chapters/shaders.txt | 32 +- chapters/sparsemem.txt | 35 +- chapters/synchronization.txt | 27 +- chapters/tessellation.txt | 12 +- chapters/textures.txt | 51 +- chapters/vertexpostproc.txt | 14 +- config/makeSubmit.py | 1 + config/vulkan-macros.rb | 1 + config/vulkan-macros/extension.rb | 10 + copyright-spec.txt | 25 +- include/vulkan/vulkan.h | 4 + include/vulkan/vulkan_core.h | 3 +- include/vulkan/vulkan_fuchsia.h | 58 +++ reflow_count.py | 2 +- registry.txt | 19 +- style/markup.txt | 11 +- style/writing.txt | 22 + styleguide.txt | 9 +- vkspec.txt | 4 +- xml/Makefile | 1 + xml/genvk.py | 1 + xml/vk.xml | 47 +- 67 files changed, 959 insertions(+), 610 deletions(-) create mode 100644 appendices/VK_FUCHSIA_imagepipe_surface.txt create mode 100644 chapters/VK_FUCHSIA_imagepipe_surface/platformCreateSurface_imagepipe.txt create mode 100644 chapters/VK_FUCHSIA_imagepipe_surface/platformQuerySupport_imagepipe.txt create mode 100644 include/vulkan/vulkan_fuchsia.h diff --git a/ChangeLog.txt b/ChangeLog.txt index c5e101a9..d65e614d 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -8,6 +8,66 @@ public pull requests that have been accepted. ----------------------------------------------------- +Change log for October 7, 2018 Vulkan 1.1.87 spec update: + + * Update release number to 87. + +Public Issues: + + * Merge flink:vkCmdPipelineBarrier self-dependency barrier VUs referring + to the same subpass dependency (public pull request 756). + * Describe default value of `"optional"` attribute in the registry schema + document (public issue 769) + * Fix links in <<VK_NVX_raytracing>> extension (public pull request 805). + * Mark the <<VK_KHR_mir_surface>> extension obsolete (see public issue 814 + - does not close this, however). + * Fix missing endif in Image Creation block (public issue 817). + +Internal Issues: + + * Clarify that the compressed texture formats corresponding to + <<features-features-textureCompressionETC2>>, + <<features-features-textureCompressionASTC_LDR>>, and + <<features-features-textureCompressionBC>> is not contingent on the + feature bits, and may be supported even if the features are not enabled + (internal issue 663). + * Clarify that code:FragStencilRefEXT is output only in the + <<interfaces-builtin-variables, Built-In Variables>> section (internal + issue 1173). + * Identify and correct many overly-aggressive uses of "`undefined`", and + narrow them down, where straightforward to do so. Mark such resolved + uses of "`undefined`" with the custom undefined: macro. Add a new + <<writing-undefined, Describing Undefined Behavior>> section (internal + issue 1267). + * Don't require code:inline_uniform_block descriptors to be populated + before use in the flink:vkAllocateDescriptorSets section (internal issue + 1380). + * Allow suppressing inline SVG images by controlling this with an + attribute set in the Makefile, rather than the explicit [%inline] + directive (internal issue 1391). + * Mark 'Khronos' as a registered trademark in several places, now that it + is one. + * Fix typo in the <<VK_KHR_shader_atomic_int64>> appendix using the GLSL + naming of the compare exchange op when referring to the SPIR-V op. + * Specify in the flink:vkGetPhysicalDeviceQueueFamilyProperties section + that all implementations must support at least one queue family, and + that every queue family must contain at least one queue. + * Make slink:VkPipelineDynamicStateCreateInfo::pname:dynamicStateCount, + slink:VkSampleLocationsInfoEXT::pname:sampleLocationsPerPixel, and + slink:VkSampleLocationsInfoEXT::pname:sampleLocationsCount optional, to + fix bogus implicit valid usage checks that were causing failures in the + conformance tests. + * Fix vendor tag in reserved extension 237 constants. Does not affect + anything since it's just a placeholder, but this should avoid further + comments. + * Minor markup fixes in some extension appendices. + +New Extensions: + + * `<<VK_FUCHSIA_imagepipe_surface>>` + +----------------------------------------------------- + Change log for September 29, 2018 Vulkan 1.1.86 spec update: * Update release number to 86. @@ -2536,7 +2596,7 @@ Internal Issues: Other Issues: - * Vulkan(R) is now a registered trademark symbol, and this is reflected in + * Vulkan is now a registered trademark symbol, and this is reflected in documents and copyright statements. ----------------------------------------------------- diff --git a/Makefile b/Makefile index 2881e254..9f7fe771 100644 --- a/Makefile +++ b/Makefile @@ -46,6 +46,11 @@ EXTOPTIONS := $(foreach ext,$(EXTS),-extension $(ext)) # normally used when building with extensions included. APITITLE = +# IMAGEOPTS is normally set to generate inline SVG images, but can be +# overridden to an empty string, since the inline option doesn't work +# well with our HTML diffs. +IMAGEOPTS = inline + # The default 'all' target builds the following sub-targets: # html - HTML single-page API specification # pdf - PDF single-page API specification @@ -107,7 +112,7 @@ VERBOSE = # EXTRAATTRIBS sets additional attributes, if passed to make # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -PATCHVERSION = 86 +PATCHVERSION = 87 ifneq (,$(findstring VK_VERSION_1_1,$(VERSIONS))) SPECREVISION = 1.1.$(PATCHVERSION) else @@ -132,6 +137,7 @@ ATTRIBOPTS = -a revnumber="$(SPECREVISION)" \ -a revremark="$(SPECREMARK)" \ -a apititle="$(APITITLE)" \ -a stem=latexmath \ + -a imageopts="$(IMAGEOPTS)" \ $(VERSIONATTRIBS) \ $(EXTATTRIBS) \ $(EXTRAATTRIBS) diff --git a/appendices/VK_EXT_debug_utils.txt b/appendices/VK_EXT_debug_utils.txt index 067feb4c..dc22c1bb 100644 --- a/appendices/VK_EXT_debug_utils.txt +++ b/appendices/VK_EXT_debug_utils.txt @@ -325,7 +325,7 @@ submitted. 1) Should we just name this extension `VK_EXT_debug_report2` -**RESOLVED**: No. +*RESOLVED*: No. There is enough additional changes to the structures to break backwards compatibility. So, a new name was decided that would not indicate any interaction with the @@ -333,7 +333,7 @@ previous extension. 2) Will validation layers immediately support all the new features. -**RESOLVED**: Not immediately. +*RESOLVED*: Not immediately. As one can imagine, there is a lot of work involved with converting the validation layer logging over to the new functionality. Basic logging, as seen in the origin @@ -347,7 +347,7 @@ exposed. 3) If the validation layers won't expose the new functionality immediately, then what's the point of this extension? -**RESOLVED**: We needed a replacement for +*RESOLVED*: We needed a replacement for <<VK_EXT_debug_report,VK_EXT_debug_report>> because the elink:VkDebugReportObjectTypeEXT enumeration will no longer be updated and any new objects will need to be debugged using the new functionality @@ -358,8 +358,7 @@ is an instance extension providing the callback functionality, and another device extension providing the general debug marker and annotation functionality)? -**RESOLVED**: No, the functionality for this extension is too closely -related. +*RESOLVED*: No, the functionality for this extension is too closely related. If we did split up the extension, where would the structures and enums live, and how would you define that the device behavior in the instance extension is really only valid if the device extension is enabled, and the diff --git a/appendices/VK_EXT_depth_range_unrestricted.txt b/appendices/VK_EXT_depth_range_unrestricted.txt index e762b296..fb3d1481 100644 --- a/appendices/VK_EXT_depth_range_unrestricted.txt +++ b/appendices/VK_EXT_depth_range_unrestricted.txt @@ -16,26 +16,32 @@ Finally it removes the restriction on the pname:depth value in slink:VkClearDepthStencilValue. === New Object Types + None. === New Enum Constants + None. === New Enums + None. === New Structures + None. === New Functions + None. === Issues + 1) How do slink:VkViewport pname:minDepth and pname:maxDepth values outside of the `0.0` to `1.0` range interact with <<vertexpostproc-clipping,Primitive Clipping>>? -**RESOLVED**: The behavior described in <<vertexpostproc-clipping,Primitive +*RESOLVED*: The behavior described in <<vertexpostproc-clipping,Primitive Clipping>> still applies. If depth clamping is disabled the depth values are still clipped to [eq]#0 {leq} z~c~ {leq} w~c~# before the viewport transform. @@ -47,9 +53,10 @@ the `0.0` to `1.0` range. 2) What happens if a resulting depth fragment is outside of the `0.0` to `1.0` range and the depth buffer is fixed-point rather than floating-point? -**RESOLVED**: The supported range of a fixed-point depth buffer is `0.0` to +*RESOLVED*: The supported range of a fixed-point depth buffer is `0.0` to `1.0` and depth fragments are clamped to this range. === Version History + * Revision 1, 2017-06-22 (Piers Daniell) - Internal revisions diff --git a/appendices/VK_EXT_external_memory_host.txt b/appendices/VK_EXT_external_memory_host.txt index e1f8a18b..343ea523 100644 --- a/appendices/VK_EXT_external_memory_host.txt +++ b/appendices/VK_EXT_external_memory_host.txt @@ -65,7 +65,7 @@ However, usual synchronization requirements apply. RESOLVED: No, it violates valid usage conditions. Using the memory object imported from a host allocation that's already freed -thus results in undefined behavior. +thus results in undefined: behavior. 4) Is flink:vkMapMemory expected to return the same host address which was specified when importing it to the memory object? @@ -89,7 +89,7 @@ physical device? RESOLVED: No, at least not guaranteed by this extension. Some platforms do not allow locking the same physical pages for device -access multiple times, so attempting to do it may result in undefined +access multiple times, so attempting to do it may result in undefined: behavior. 7) Does this extension support exporting the new handle type? diff --git a/appendices/VK_EXT_image_drm_format_modifier.txt b/appendices/VK_EXT_image_drm_format_modifier.txt index 383f2ee9..179d0ed5 100644 --- a/appendices/VK_EXT_image_drm_format_modifier.txt +++ b/appendices/VK_EXT_image_drm_format_modifier.txt @@ -21,115 +21,115 @@ include::meta/VK_EXT_image_drm_format_modifier.txt[] ==== Summary -This extension provides the ability to use _DRM format modifiers_ with images, -enabling Vulkan to better integrate with the Linux ecosystem of graphics, -video, and display APIs. +This extension provides the ability to use _DRM format modifiers_ with +images, enabling Vulkan to better integrate with the Linux ecosystem of +graphics, video, and display APIs. Its functionality closely overlaps with `EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn2,2>>^ and `EGL_MESA_image_dma_buf_export`^<<VK_EXT_image_drm_format_modifier-fn3,3>>^. -Unlike the EGL extensions, this extension does not require the use of -a specific handle type (such as a dma_buf) for external memory -and provides more explicit control of image creation. +Unlike the EGL extensions, this extension does not require the use of a +specific handle type (such as a dma_buf) for external memory and provides +more explicit control of image creation. ==== Introduction to DRM Format Modifiers -A _DRM format modifier_ is a 64-bit, vendor-prefixed, semi-opaque unsigned integer. -Most _modifiers_ represent a concrete, vendor-specific tiling format for images. -Some exceptions are etext:DRM_FORMAT_MOD_LINEAR (which is not vendor-specific); -etext:DRM_FORMAT_MOD_NONE (which is an alias of etext:DRM_FORMAT_MOD_LINEAR due -to historical accident); -and etext:DRM_FORMAT_MOD_INVALID (which does not represent a tiling format). +A _DRM format modifier_ is a 64-bit, vendor-prefixed, semi-opaque unsigned +integer. +Most _modifiers_ represent a concrete, vendor-specific tiling format for +images. +Some exceptions are etext:DRM_FORMAT_MOD_LINEAR (which is not +vendor-specific); etext:DRM_FORMAT_MOD_NONE (which is an alias of +etext:DRM_FORMAT_MOD_LINEAR due to historical accident); and +etext:DRM_FORMAT_MOD_INVALID (which does not represent a tiling format). The _modifier's_ vendor prefix consists of the 8 most signficant bits. The canonical list of _modifiers_ and vendor prefixes is found in https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/drm/drm_fourcc.h[`drm_fourcc.h`] in the Linux kernel source. The other dominant source of _modifiers_ are vendor kernel trees. -One goal of _modifiers_ in the Linux ecosystem -is to enumerate for each vendor a reasonably sized set of tiling formats that -are appropriate for images shared -across processes, APIs, and/or devices, -where each participating component may possibly be from different vendors. -A non-goal is to enumerate all tiling formats supported -by all vendors. Some tiling formats used internally by vendors are -inappropriate for sharing; no _modifiers_ should be assigned to such tiling -formats. +One goal of _modifiers_ in the Linux ecosystem is to enumerate for each +vendor a reasonably sized set of tiling formats that are appropriate for +images shared across processes, APIs, and/or devices, where each +participating component may possibly be from different vendors. +A non-goal is to enumerate all tiling formats supported by all vendors. +Some tiling formats used internally by vendors are inappropriate for +sharing; no _modifiers_ should be assigned to such tiling formats. Modifier values typically do not _describe_ memory layouts. More precisely, a _modifier_'s lower 56 bits usually have no structure. -Instead, modifiers _name_ memory layouts; -they name a small set of vendor-preferred layouts for image sharing. +Instead, modifiers _name_ memory layouts; they name a small set of +vendor-preferred layouts for image sharing. As a consequence, in each vendor namespace the modifier values are often sequentially allocated starting at 1. -Each _modifier_ is usually supported by a single vendor -and its name matches the pattern `{VENDOR}_FORMAT_MOD_*` -or `DRM_FORMAT_MOD_{VENDOR}_*`. -Examples are -etext:I915_FORMAT_MOD_X_TILED and +Each _modifier_ is usually supported by a single vendor and its name matches +the pattern `{VENDOR}_FORMAT_MOD_*` or `DRM_FORMAT_MOD_{VENDOR}_*`. +Examples are etext:I915_FORMAT_MOD_X_TILED and etext:DRM_FORMAT_MOD_BROADCOM_VC4_T_TILED. -An exception is etext:DRM_FORMAT_MOD_LINEAR, -which is supported by most vendors. +An exception is etext:DRM_FORMAT_MOD_LINEAR, which is supported by most +vendors. -Many APIs in Linux use _modifiers_ to negotiate and specify the -memory layout of shared images. For example, a Wayland compositor and Wayland -client may, by relaying _modifiers_ over the Wayland protocol -`zwp_linux_dmabuf_v1`, negotiate a vendor-specific tiling format for a shared -stext:wl_buffer. The client may allocate the underlying memory for the -stext:wl_buffer with GBM, providing the chosen _modifier_ to -fname:gbm_bo_create_with_modifiers. The client may then import the stext:wl_buffer -into Vulkan for producing image content, providing the resource's -dma_buf to slink:VkImportMemoryFdInfo and -its _modifier_ to slink:VkImageDrmFormatModifierExplicitCreateInfoEXT. +Many APIs in Linux use _modifiers_ to negotiate and specify the memory +layout of shared images. +For example, a Wayland compositor and Wayland client may, by relaying +_modifiers_ over the Wayland protocol `zwp_linux_dmabuf_v1`, negotiate a +vendor-specific tiling format for a shared stext:wl_buffer. +The client may allocate the underlying memory for the stext:wl_buffer with +GBM, providing the chosen _modifier_ to fname:gbm_bo_create_with_modifiers. +The client may then import the stext:wl_buffer into Vulkan for producing +image content, providing the resource's dma_buf to +slink:VkImportMemoryFdInfo and its _modifier_ to +slink:VkImageDrmFormatModifierExplicitCreateInfoEXT. The compositor may then import the stext:wl_buffer into OpenGL for sampling, -providing the resource's dma_buf and _modifier_ to -fname:eglCreateImage. -The compositor may also bypass OpenGL and submit the stext:wl_buffer directly -to the kernel's display API, providing the dma_buf and _modifier_ through -stext:drm_mode_fb_cmd2. +providing the resource's dma_buf and _modifier_ to fname:eglCreateImage. +The compositor may also bypass OpenGL and submit the stext:wl_buffer +directly to the kernel's display API, providing the dma_buf and _modifier_ +through stext:drm_mode_fb_cmd2. ==== Format Translation -_Modifier_-capable APIs often pair _modifiers_ with DRM formats, -which are defined in +_Modifier_-capable APIs often pair _modifiers_ with DRM formats, which are +defined in https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/drm/drm_fourcc.h[`drm_fourcc.h`]. -However, `VK_EXT_image_drm_format_modifier` uses elink:VkFormat instead of DRM formats. -The application must convert between elink:VkFormat and DRM format -when it sends or receives a DRM format to or from an external API. +However, `VK_EXT_image_drm_format_modifier` uses elink:VkFormat instead of +DRM formats. +The application must convert between elink:VkFormat and DRM format when it +sends or receives a DRM format to or from an external API. The mapping from elink:VkFormat to DRM format is lossy. -Therefore, when receiving a DRM format from an external API, -often the application must use information from the external API -to accurately map the DRM format to a elink:VkFormat. -For example, DRM formats do not distinguish between RGB and sRGB -(as of 2018-03-28); -external information is required to identify the image's colorspace. +Therefore, when receiving a DRM format from an external API, often the +application must use information from the external API to accurately map the +DRM format to a elink:VkFormat. +For example, DRM formats do not distinguish between RGB and sRGB (as of +2018-03-28); external information is required to identify the image's +colorspace. The mapping between elink:VkFormat and DRM format is also incomplete. -For some DRM formats there exist no corresponding Vulkan format, -and for some Vulkan formats there exist no corresponding DRM format. +For some DRM formats there exist no corresponding Vulkan format, and for +some Vulkan formats there exist no corresponding DRM format. ==== Usage Patterns Three primary usage patterns are intended for this extension: - * *Negotiation.* - The application negotiates with _modifier_-aware, external components to - determine sets of image creation parameters supported among all components. + * *Negotiation.* The application negotiates with _modifier_-aware, + external components to determine sets of image creation parameters + supported among all components. + -- In the Linux ecosystem, the negotiation usually assumes the image is a 2D, single-sampled, non-mipmapped, non-array image; this extension permits that -assumption but does not require it. The result of the negotiation usually -resembles a set of tuples such as _(drmFormat, drmFormatModifier)_, -where each participating component supports all tuples in the set. +assumption but does not require it. +The result of the negotiation usually resembles a set of tuples such as +_(drmFormat, drmFormatModifier)_, where each participating component +supports all tuples in the set. -Many details of this negotiation—such as the protocol used during negotiation, -the set of image creation parameters expressable in the protocol, and how the -protocol chooses which process and which API will create the image—are outside -the scope of this specification. +Many details of this negotiation—such as the protocol used during +negotiation, the set of image creation parameters expressable in the +protocol, and how the protocol chooses which process and which API will +create the image—are outside the scope of this specification. In this extension, flink:vkGetPhysicalDeviceFormatProperties2 with slink:VkDrmFormatModifierPropertiesListEXT serves a primary role during the @@ -137,87 +137,91 @@ negotiation, and flink:vkGetPhysicalDeviceImageFormatProperties2 with slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT serves a secondary role. -- - * *Import.* - The application imports an image with a _modifier_. + * *Import.* The application imports an image with a _modifier_. + -- In this pattern, the application receives from an external source the image's memory and its creation parameters, which are often the result of -the negotiation described above. Some image creation parameters are -implicitly defined by the external source; for example, -ename:VK_IMAGE_TYPE_2D is often assumed. Some image creation parameters are -usually explicit, such as the image's pname:format, -pname:drmFormatModifier, and pname:extent; and each plane's pname:offset -and pname:rowPitch. +the negotiation described above. +Some image creation parameters are implicitly defined by the external +source; for example, ename:VK_IMAGE_TYPE_2D is often assumed. +Some image creation parameters are usually explicit, such as the image's +pname:format, pname:drmFormatModifier, and pname:extent; and each plane's +pname:offset and pname:rowPitch. -Before creating the image, the application first verifies that the physical device -supports the received creation parameters by querying +Before creating the image, the application first verifies that the physical +device supports the received creation parameters by querying flink:vkGetPhysicalDeviceFormatProperties2 with slink:VkDrmFormatModifierPropertiesListEXT and flink:vkGetPhysicalDeviceImageFormatProperties2 with -slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT. Then the application creates -the image by chaining slink:VkImageDrmFormatModifierExplicitCreateInfoEXT -and slink:VkExternalMemoryImageCreateInfo onto slink:VkImageCreateInfo. +slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT. +Then the application creates the image by chaining +slink:VkImageDrmFormatModifierExplicitCreateInfoEXT and +slink:VkExternalMemoryImageCreateInfo onto slink:VkImageCreateInfo. -- * *Export.* The application creates an image and allocates its memory. Then the application exports to _modifier_-aware consumers the image's memory handles; its creation parameters; its _modifier_; and the - <<VkSubresourceLayout,pname:offset>>, <<VkSubresourceLayout,pname:size>>, - and <<VkSubresourceLayout,pname:rowPitch>> of each _memory plane_. + <<VkSubresourceLayout,pname:offset>>, + <<VkSubresourceLayout,pname:size>>, and + <<VkSubresourceLayout,pname:rowPitch>> of each _memory plane_. + -- -In this pattern, the Vulkan device is the authority for the image; it is -the allocator of the image's memory and the decider of the image's creation -parameters. When choosing the image's creation parameters, the application -usually chooses a tuple _(format, drmFormatModifier)_ -from the result of the negotiation described above. -The negotiation's result often contains multiple tuples -that share the same format but differ in their _modifier_. In this case, the -application should defer the choice of the image's _modifier_ to the Vulkan -implementation by providing all such _modifiers_ to +In this pattern, the Vulkan device is the authority for the image; it is the +allocator of the image's memory and the decider of the image's creation +parameters. +When choosing the image's creation parameters, the application usually +chooses a tuple _(format, drmFormatModifier)_ from the result of the +negotiation described above. +The negotiation's result often contains multiple tuples that share the same +format but differ in their _modifier_. +In this case, the application should defer the choice of the image's +_modifier_ to the Vulkan implementation by providing all such _modifiers_ to slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers; and the implementation should choose from pname:pDrmFormatModifiers the optimal _modifier_ in consideration with the other image parameters. The application creates the image by chaining slink:VkImageDrmFormatModifierListCreateInfoEXT and -slink:VkExternalMemoryImageCreateInfo onto slink:VkImageCreateInfo. The -protocol and APIs by which the application will share the image with external -consumers will likely determine the value of -slink:VkExternalMemoryImageCreateInfo::pname:handleTypes. The -implementation chooses for the image an optimal _modifier_ from +slink:VkExternalMemoryImageCreateInfo onto slink:VkImageCreateInfo. +The protocol and APIs by which the application will share the image with +external consumers will likely determine the value of +slink:VkExternalMemoryImageCreateInfo::pname:handleTypes. +The implementation chooses for the image an optimal _modifier_ from slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers. The application then queries the implementation-chosen _modifier_ with flink:vkGetImageDrmFormatModifierPropertiesEXT, and queries the memory layout of each plane with flink:vkGetImageSubresourceLayout. -The application then allocates the image's memory with slink:VkMemoryAllocateInfo, -adding chained extension structures for external memory; binds it to the -image; and exports the memory, for example, with flink:vkGetMemoryFd. +The application then allocates the image's memory with +slink:VkMemoryAllocateInfo, adding chained extension structures for external +memory; binds it to the image; and exports the memory, for example, with +flink:vkGetMemoryFd. -Finally, the application sends the image's creation parameters, its _modifier_, -its per-plane memory layout, and the exported memory handle to the -external consumers. The details of how the application transmits this -information to external consumers is outside the scope of this specification. +Finally, the application sends the image's creation parameters, its +_modifier_, its per-plane memory layout, and the exported memory handle to +the external consumers. +The details of how the application transmits this information to external +consumers is outside the scope of this specification. -- ==== Prior Art Extension `EGL_EXT_image_dma_buf_import`^<<VK_EXT_image_drm_format_modifier-fn1,1>>^ -introduced the ability to create an stext:EGLImage by importing for each plane -a dma_buf, offset, and row pitch. +introduced the ability to create an stext:EGLImage by importing for each +plane a dma_buf, offset, and row pitch. Later, extension `EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn2,2>>^ introduced the ability to query which combination of formats and _modifiers_ -the implementation supports and to specify _modifiers_ during creation of the -stext:EGLImage. +the implementation supports and to specify _modifiers_ during creation of +the stext:EGLImage. Extension -`EGL_MESA_image_dma_buf_export`^<<VK_EXT_image_drm_format_modifier-fn3,3>>^ is -the inverse of `EGL_EXT_image_dma_buf_import_modifiers`. +`EGL_MESA_image_dma_buf_export`^<<VK_EXT_image_drm_format_modifier-fn3,3>>^ +is the inverse of `EGL_EXT_image_dma_buf_import_modifiers`. The Linux kernel modesetting API (KMS), when configuring the display's framebuffer with `struct @@ -225,11 +229,11 @@ drm_mode_fb_cmd2`^<<VK_EXT_image_drm_format_modifier-fn4,4>>^, allows one to specify the frambuffer's _modifier_ as well as a per-plane memory handle, offset, and row pitch. -GBM, a graphics buffer manager for Linux, allows creation of a `gbm_bo` (that -is, a graphics _buffer object_) by importing data similar to that in +GBM, a graphics buffer manager for Linux, allows creation of a `gbm_bo` +(that is, a graphics _buffer object_) by importing data similar to that in `EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn1,1>>^; -and symmetrically allows exporting the same data from the `gbm_bo`. See the -references to _modifier_ and _plane_ in +and symmetrically allows exporting the same data from the `gbm_bo`. +See the references to _modifier_ and _plane_ in `gbm.h`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^. @@ -287,147 +291,167 @@ None. === Issues -1. Should this extension define a single DRM format modifier per +1) Should this extension define a single DRM format modifier per sname:VkImage? Or define one per plane? + -- -*RESOLVED.* -There exists a single DRM format modifier per sname:VkImage. +*RESOLVED*: There exists a single DRM format modifier per sname:VkImage. -*DISCUSSION.* -Prior art, such as +*DISCUSSION*: Prior art, such as `EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn2,2>>^, `struct drm_mode_fb_cmd2`^<<VK_EXT_image_drm_format_modifier-fn4,4>>^, and -`struct gbm_import_fd_modifier_data`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^, +`struct +gbm_import_fd_modifier_data`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^, allows defining one _modifier_ per plane. -However, developers of the GBM and kernel APIs concede it was a mistake. 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]). +However, developers of the GBM and kernel APIs concede it was a mistake. +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 _modifier_ of the image but does not provide one to query the modifier of individual planes. -- -2. When creating an image with slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, - which is typically used when _importing_ an image, - should the application explicitly provide the size of each plane? +2) When creating an image with + slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, which is typically + used when _importing_ an image, should the application explicitly provide + the size of each plane? + -- -*RESOLVED.* No. The application must: not provide the size. To enforce this, -the API requires that +*RESOLVED*: No. +The application must: not provide the size. +To enforce this, the API requires that slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:pPlaneLayouts::<<VkSubresourceLayout,pname:size>> must: be 0. -*DISCUSSION.* -Prior art, such as +*DISCUSSION*: Prior art, such as `EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn2,2>>^, `struct drm_mode_fb_cmd2`^<<VK_EXT_image_drm_format_modifier-fn4,4>>^, and -`struct gbm_import_fd_modifier_data`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^, omits -from the API the size of each plane. Instead, the APIs infer each plane's size -from the import parameters, which include the image's pixel format and -a dma_buf, offset, and row pitch for each plane. +`struct +gbm_import_fd_modifier_data`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^, +omits from the API the size of each plane. +Instead, the APIs infer each plane's size from the import parameters, which +include the image's pixel format and a dma_buf, offset, and row pitch for +each plane. -However, Vulkan differs from EGL and GBM with regards to image -creation in the following ways: +However, Vulkan differs from EGL and GBM with regards to image creation in +the following ways: .Differences in Image Creation - - *Undedicated allocation by default.* - When importing or exporting a set of dma_bufs as an stext:EGLImage or - stext:gbm_bo, common practice mandates that each dma_buf's memory be - dedicated (in the sense of `VK_KHR_dedicated_allocation`) to the image - (though not necessarily dedicated to a single plane). In particular, - neither the GBM documentation nor the EGL extension specifications explicitly - state this requirement, but in light of common practice this is likely due to - under-specification rather than intentional omission. In contrast, - `VK_EXT_image_drm_format_modifier` permits, but does not require, the - implementation to require dedicated allocations for images created with - ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. + - *Undedicated allocation by default.* When importing or exporting a set + of dma_bufs as an stext:EGLImage or stext:gbm_bo, common practice + mandates that each dma_buf's memory be dedicated (in the sense of + `VK_KHR_dedicated_allocation`) to the image (though not necessarily + dedicated to a single plane). + In particular, neither the GBM documentation nor the EGL extension + specifications explicitly state this requirement, but in light of common + practice this is likely due to under-specification rather than + intentional omission. + In contrast, `VK_EXT_image_drm_format_modifier` permits, but does not + require, the implementation to require dedicated allocations for images + created with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. - - *Separation of image creation and memory allocation.* - When importing a set of dma_bufs as an stext:EGLImage or stext:gbm_bo, EGL - and GBM create the image resource and bind it to memory (the dma_bufs) - simultaneously. This allows EGL and GBM to query each dma_buf's size during - image creation. In Vulkan, image creation and memory allocation are - independent unless a dedicated allocation is used (as in - `VK_KHR_dedicated_allocation`). Therefore, without requiring dedicated - allocation, Vulkan cannot query the size of each dma_buf (or other external - handle) when calculating the image's memory layout. Even if dedication - allocation were required, Vulkan cannot calculate the image's memory layout - until after the image is bound to its dma_ufs. + - *Separation of image creation and memory allocation.* When importing a + set of dma_bufs as an stext:EGLImage or stext:gbm_bo, EGL and GBM create + the image resource and bind it to memory (the dma_bufs) simultaneously. + This allows EGL and GBM to query each dma_buf's size during image + creation. + In Vulkan, image creation and memory allocation are independent unless a + dedicated allocation is used (as in `VK_KHR_dedicated_allocation`). + Therefore, without requiring dedicated allocation, Vulkan cannot query + the size of each dma_buf (or other external handle) when calculating the + image's memory layout. + Even if dedication allocation were required, Vulkan cannot calculate the + image's memory layout until after the image is bound to its dma_ufs. The above differences complicate the potential inference of plane size in -Vulkan. Consider the following problematic cases: +Vulkan. +Consider the following problematic cases: .Problematic Plane Size Calculations - - *Padding.* Some plane of the image may require implementation-dependent padding. + - *Padding.* Some plane of the image may require implementation-dependent + padding. - - *Metadata.* For some _modifiers_, the image may have a metadata plane which - requires a non-trivial calculation to determine its size. + - *Metadata.* For some _modifiers_, the image may have a metadata plane + which requires a non-trivial calculation to determine its size. - *Mipmapped, array, and 3D images.* The implementation may support ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT for images whose - pname:mipLevels, pname:arrayLayers, or pname:depth is greater than 1. For - such images with certain _modifiers_, the calculation of each plane's size - may be non-trivial. + pname:mipLevels, pname:arrayLayers, or pname:depth is greater than 1. + For such images with certain _modifiers_, the calculation of each + plane's size may be non-trivial. -However, an application-provided plane size solves none of the above problems. +However, an application-provided plane size solves none of the above +problems. -For simplicity, consider an external image with a single memory plane. The -implementation is obviously capable calculating the image's size when its -tiling is ename:VK_IMAGE_TILING_OPTIMAL. Likewise, any reasonable -implementation is capable of calculating the image's size when its tiling uses -a supported _modifier_. +For simplicity, consider an external image with a single memory plane. +The implementation is obviously capable calculating the image's size when +its tiling is ename:VK_IMAGE_TILING_OPTIMAL. +Likewise, any reasonable implementation is capable of calculating the +image's size when its tiling uses a supported _modifier_. Suppose that the external image's size is smaller than the -implementation-calculated size. If the application provided the external -image's size to slink:vkCreateImage, the implementation would observe the -mismatched size and recognize its inability to comprehend the external image's -layout (unless the implementation used the application-provided size to select -a refinement of the tiling layout indicated by the _modifier_, which is -strongly discouraged). The implementation would observe the conflict, and -reject image creation with -ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT. On the other -hand, if the application did not provide the external image's size to -slink:vkCreateImage, then the application would observe after +implementation-calculated size. +If the application provided the external image's size to +slink:vkCreateImage, the implementation would observe the mismatched size +and recognize its inability to comprehend the external image's layout +(unless the implementation used the application-provided size to select a +refinement of the tiling layout indicated by the _modifier_, which is +strongly discouraged). +The implementation would observe the conflict, and reject image creation +with ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT. +On the other hand, if the application did not provide the external image's +size to slink:vkCreateImage, then the application would observe after calling flink:vkGetImageMemoryRequirements that the external image's size is -less than the size required by the implementation. The application would -observe the conflict and refuse to bind the sname:VkImage to the external -memory. In both cases, the result is explicit failure. +less than the size required by the implementation. +The application would observe the conflict and refuse to bind the +sname:VkImage to the external memory. +In both cases, the result is explicit failure. Suppose that the external image's size is larger than the -implementation-calculated size. If the application provided the external -image's size to slink:vkCreateImage, for reasons similar to above the -implementation would observe the mismatched size and recognize its inability to -comprehend the image data residing in the extra size. The implementation, -however, must assume that image data resides in the entire size provided by the -application. The implementation would observe the conflict and reject image -creation with ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT. On -the other hand, if the application did not provide the external image's size to -flink:vkCreateImage, then the application would observe after calling -flink:vkGetImageMemoryRequirements that the external image's size is larger -than the implementation-usable size. The application would observe the -conflict and refuse to bind the sname:VkImage to the external memory. In both -cases, the result is explicit failure. +implementation-calculated size. +If the application provided the external image's size to +slink:vkCreateImage, for reasons similar to above the implementation would +observe the mismatched size and recognize its inability to comprehend the +image data residing in the extra size. +The implementation, however, must assume that image data resides in the +entire size provided by the application. +The implementation would observe the conflict and reject image creation with +ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT. +On the other hand, if the application did not provide the external image's +size to flink:vkCreateImage, then the application would observe after +calling flink:vkGetImageMemoryRequirements that the external image's size is +larger than the implementation-usable size. +The application would observe the conflict and refuse to bind the +sname:VkImage to the external memory. +In both cases, the result is explicit failure. -Therefore, an application-provided size provides no benefit, and this extension -should not require it. This decision renders -slink:VkSubresourceLayout::pname:size an unused field during image creation, -and thus introduces a risk that implementations may require applications to -submit sideband creation parameters in the unused field. To prevent -implementations from relying on sideband data, this extension _requires_ the -application to set pname:size to 0. +Therefore, an application-provided size provides no benefit, and this +extension should not require it. +This decision renders slink:VkSubresourceLayout::pname:size an unused field +during image creation, and thus introduces a risk that implementations may +require applications to submit sideband creation parameters in the unused +field. +To prevent implementations from relying on sideband data, this extension +_requires_ the application to set pname:size to 0. -- ==== References -1. [[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] -2. [[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] -3. [[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] -4. [[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] -5. [[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] + . [[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] + . [[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] + . [[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] + . [[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] + . [[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] ==== Version History diff --git a/appendices/VK_FUCHSIA_imagepipe_surface.txt b/appendices/VK_FUCHSIA_imagepipe_surface.txt new file mode 100644 index 00000000..63b92d38 --- /dev/null +++ b/appendices/VK_FUCHSIA_imagepipe_surface.txt @@ -0,0 +1,49 @@ +// Copyright (c) 2014-2018 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ + +include::meta/VK_FUCHSIA_imagepipe_surface.txt[] + +*Last Modified Date*:: + 2018-07-27 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Craig Stout, Google + - Ian Elliott, Google + - Jesse Hall, Google + +The `VK_FUCHSIA_imagepipe_surface` extension is an instance extension. +It provides a mechanism to create a slink:VkSurfaceKHR object (defined by +the `<<VK_KHR_surface>>` extension) that refers to a Fuchsia +code:imagePipeHandle. + +=== New Object Types + +None + +=== New Enum Constants + + * Extending elink:VkStructureType: + ** ename:VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA + +=== New Enums + +None + +=== New Structures + + * slink:VkImagePipeSurfaceCreateInfoFUCHSIA + +=== New Functions + + * flink:vkCreateImagePipeSurfaceFUCHSIA + +=== Issues + +None + +=== Version History + + * Revision 1, 2018-07-27 (Craig Stout) + - Initial draft. diff --git a/appendices/VK_KHR_external_semaphore.txt b/appendices/VK_KHR_external_semaphore.txt index 3037eeab..05455b52 100644 --- a/appendices/VK_KHR_external_semaphore.txt +++ b/appendices/VK_KHR_external_semaphore.txt @@ -61,7 +61,7 @@ on imported semaphores that are in an invalid state? *RESOLVED*: Yes. Normally, validating such state would be the responsibility of the -application, and the implementation would be free to enter an undefined +application, and the implementation would be free to enter an undefined: state if valid usage rules were violated. However, this could cause security concerns when using imported semaphores, as it would require the importing application to trust the exporting diff --git a/appendices/VK_KHR_shader_atomic_int64.txt b/appendices/VK_KHR_shader_atomic_int64.txt index 4c0d4b67..d999c168 100644 --- a/appendices/VK_KHR_shader_atomic_int64.txt +++ b/appendices/VK_KHR_shader_atomic_int64.txt @@ -4,7 +4,7 @@ include::meta/VK_KHR_shader_atomic_int64.txt[] -*Last Modified Data*:: +*Last Modified Date*:: 2018-07-05 *Interactions and External Dependencies*:: - This extension requires the @@ -23,7 +23,7 @@ which allows a shader to contain 64-bit atomic operations on signed and unsigned integers. The supported operations include OpAtomicMin, OpAtomicMax, OpAtomicAnd, OpAtomicOr, OpAtomicXor, OpAtomicAdd, OpAtomicExchange, and -OpAtomicCompSwap. +OpAtomicCompareExchange. === New Enum Constants diff --git a/appendices/VK_KHR_swapchain.txt b/appendices/VK_KHR_swapchain.txt index 8bc007ab..bb4f35d9 100644 --- a/appendices/VK_KHR_swapchain.txt +++ b/appendices/VK_KHR_swapchain.txt @@ -273,7 +273,7 @@ limits out via trial/failure iterations. 15) Should there be a special value for slink:VkSurfaceCapabilitiesKHR::pname:currentExtent to indicate the size of -the platform surface is undefined? +the platform surface is undefined:? *RESOLVED*: Yes. On some platforms (Wayland, for example), the surface size is defined by the @@ -321,7 +321,7 @@ necessary to express lack of support for no mirroring. To allow this, the etext:MIRROR_NONE enum must occupy a bit in the flags. Since etext:MIRROR_NONE must be a bit in the bitmask rather than a bitmask with no values set, allowing more than one bit to be set in the bitmask -would make it possible to describe undefined transforms such as +would make it possible to describe undefined: transforms such as etext:VK_MIRROR_NONE_BIT | etext:VK_MIRROR_HORIZONTAL_BIT, or a transform that includes both "`no mirroring`" and "`horizontal mirroring`" simultaneously. diff --git a/appendices/VK_KHR_win32_surface.txt b/appendices/VK_KHR_win32_surface.txt index a6cb9250..1be0f4af 100644 --- a/appendices/VK_KHR_win32_surface.txt +++ b/appendices/VK_KHR_win32_surface.txt @@ -72,7 +72,7 @@ these uses interfere with each other? *RESOLVED*: Yes. -Uses of a window object by multiple graphics APIs results in undefined +Uses of a window object by multiple graphics APIs results in undefined: behavior. Such behavior may succeed when using one Vulkan implementation but fail when using a different Vulkan implementation. diff --git a/appendices/VK_NV_representative_fragment_test.txt b/appendices/VK_NV_representative_fragment_test.txt index 98b1899f..5a77fe32 100644 --- a/appendices/VK_NV_representative_fragment_test.txt +++ b/appendices/VK_NV_representative_fragment_test.txt @@ -67,7 +67,7 @@ None. (1) Is the representative fragment test guaranteed to have any effect? -**RESOLVED**: No. +*RESOLVED*: No. As specified, we only guarantee that each primitive with at least one fragment that passes prior tests will have one fragment passing the representative fragment tests. @@ -83,7 +83,7 @@ images, with no writes to color or depth buffers. (2) Will the set of fragments that pass the representative fragment test be repeatable if you draw the same scene over and over again? -**RESOLVED**: No. +*RESOLVED*: No. The set of fragments that pass the representative fragment test is implementation-dependent and may vary due to the timing of operations performed by the GPU. @@ -91,8 +91,8 @@ performed by the GPU. (3) What happens if you enable the representative fragment test with writes to color and/or depth render targets enabled? -**RESOLVED**: If writes to the color or depth buffer are enabled, they will -be performed for any fragments that survive the relevant tests. +*RESOLVED*: If writes to the color or depth buffer are enabled, they will be +performed for any fragments that survive the relevant tests. Any fragments that fail the representative fragment test will not update color buffers. For the use cases intended for this feature, we don't expect color or depth @@ -101,7 +101,7 @@ writes to be enabled. (4) How do derivatives and automatic texture level of detail computations work with the representative fragment test enabled? -**RESOLVED**: If a fragment shader uses derivative functions or texture +*RESOLVED*: If a fragment shader uses derivative functions or texture lookups using automatic level of detail computation, derivatives will be computed identically whether or not the representative fragment test is enabled. @@ -112,6 +112,5 @@ derivatives in the fragment shader. * Revision 2, 2018-09-13 (pbrown) - Add issues. - * Revision 1, 2018-08-22 (Kedarnath Thangudu) - Internal Revisions diff --git a/appendices/VK_NV_shader_image_footprint.txt b/appendices/VK_NV_shader_image_footprint.txt index cdcd8bd9..850effeb 100644 --- a/appendices/VK_NV_shader_image_footprint.txt +++ b/appendices/VK_NV_shader_image_footprint.txt @@ -172,9 +172,8 @@ corresponding footprint texel. (2) What should an application do to ensure maximum performance when accumulating footprints into an aggregate footprint image? -**RESOLVED**: We expect that the most common usage of this feature will be -to accumulate aggregate footprint coverage, as described in the previous -issue. +*RESOLVED*: We expect that the most common usage of this feature will be to +accumulate aggregate footprint coverage, as described in the previous issue. Even if you ignore the anisotropic filtering case where the implementation may return a granularity larger than that requested by the caller, each shader invocation will need to use atomic functions to update up to four diff --git a/appendices/VK_NV_viewport_swizzle.txt b/appendices/VK_NV_viewport_swizzle.txt index e521e680..56dc0484 100644 --- a/appendices/VK_NV_viewport_swizzle.txt +++ b/appendices/VK_NV_viewport_swizzle.txt @@ -33,7 +33,6 @@ None. === New Enum Constants * Extending elink:VkStructureType: - ** ename:VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_SWIZZLE_STATE_CREATE_INFO_NV === New Enums @@ -54,7 +53,7 @@ None. 1) Where does viewport swizzling occur in the pipeline? -**RESOLVED**: Despite being associated with the viewport, viewport swizzling +*RESOLVED*: Despite being associated with the viewport, viewport swizzling must happen prior to the viewport transform. In particular, it needs to be performed before clipping and perspective division. @@ -70,7 +69,7 @@ feedback, and makes primitive queries only count each primitive once. `<<VK_NV_viewport_array2>>`, and `<<VK_NV_geometry_shader_passthrough>>` can be used together in practice? -**RESOLVED**: One interesting use case for this extension is for single-pass +*RESOLVED*: One interesting use case for this extension is for single-pass rendering to a cubemap. In this example, the application would attach a cubemap texture to a layered FBO where the six cube faces are treated as layers. @@ -188,39 +187,38 @@ viewport swizzle does not support arbitrary math. To get proper projection, [eq]#1/W# buffering should be used. To do this: -1. -Program the viewport swizzles to move the pre-projection [eq]#W# eye -coordinate (typically 1.0) into the [eq]#Z# coordinate of the swizzle output -and the eye coordinate component used for depth into the [eq]#W# coordinate. -For example, the viewport corresponding to the [eq]#+Z# face might use a -swizzle of [eq]#(+X, -Y, +W, +Z)#. -The [eq]#Z# normalized device coordinate computed after swizzling would then -be [eq]#z'/w' = 1/Z~eye~#. - -2. -On NVIDIA implementations supporting floating-point depth buffers with -values outside [eq]#[0,1]#, prevent unwanted near plane clipping by enabling -pname:depthClampEnable. -Ensure that the depth clamp doesn't mess up depth testing by programming the -depth range to very large values, such as [eq]#pname:minDepthBounds=-z#, -[eq]#pname:maxDepthBounds=+z#, where [eq]#z = 2^127^#. -It should be possible to use IEEE infinity encodings also (`0xFF800000` for -`-INF`, `0x7F800000` for `+INF`). -Even when near/far clipping is disabled, primitives extending behind the eye -will still be clipped because one or more vertices will have a negative -[eq]#W# coordinate and fail [eq]#X#/[eq]#Y# clipping tests. - + . Program the viewport swizzles to move the pre-projection [eq]#W# eye + coordinate (typically 1.0) into the [eq]#Z# coordinate of the swizzle + output and the eye coordinate component used for depth into the [eq]#W# + coordinate. + For example, the viewport corresponding to the [eq]#+Z# face might use a + swizzle of [eq]#(+X, -Y, +W, +Z)#. + The [eq]#Z# normalized device coordinate computed after swizzling would + then be [eq]#z'/w' = 1/Z~eye~#. + . On NVIDIA implementations supporting floating-point depth buffers with + values outside [eq]#[0,1]#, prevent unwanted near plane clipping by + enabling pname:depthClampEnable. + Ensure that the depth clamp doesn't mess up depth testing by programming + the depth range to very large values, such as + [eq]#pname:minDepthBounds=-z#, [eq]#pname:maxDepthBounds=+z#, where + [eq]#z = 2^127^#. + It should be possible to use IEEE infinity encodings also (`0xFF800000` + for `-INF`, `0x7F800000` for `+INF`). + Even when near/far clipping is disabled, primitives extending behind the + eye will still be clipped because one or more vertices will have a + negative [eq]#W# coordinate and fail [eq]#X#/[eq]#Y# clipping tests. ++ +-- On other implementations, scale [eq]#X#, [eq]#Y#, and [eq]#Z# eye coordinates so that vertices on the near plane have a post-swizzle [eq]#W# coordinate of 1.0. For example, if the near plane is at [eq]#Z~eye~ = 1/256#, scale [eq]#X#, [eq]#Y#, and [eq]#Z# by 256. - -3. -Adjust depth testing to reflect the fact that [eq]#1/W# values are large -near the eye and small away from the eye. -Clear the depth buffer to zero (infinitely far away) and use a depth test of -ename:VK_COMPARE_OP_GREATER instead of ename:VK_COMPARE_OP_LESS. +-- + . Adjust depth testing to reflect the fact that [eq]#1/W# values are large + near the eye and small away from the eye. + Clear the depth buffer to zero (infinitely far away) and use a depth + test of ename:VK_COMPARE_OP_GREATER instead of ename:VK_COMPARE_OP_LESS. === Version History diff --git a/appendices/boilerplate.txt b/appendices/boilerplate.txt index 772fa00a..b4e4314c 100644 --- a/appendices/boilerplate.txt +++ b/appendices/boilerplate.txt @@ -275,7 +275,7 @@ If dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when This allows the application to define a binary-compatible custom handle which may: provide more type-safety or other features needed by the application. -Behavior is undefined if the application defines a non-binary-compatible +Behavior is undefined: if the application defines a non-binary-compatible handle and may: result in memory corruption or application termination. Binary compatibility is platform dependent so the application must: be careful if it overrides the default dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE diff --git a/appendices/glossary.txt b/appendices/glossary.txt index f0919023..9fdbdd5e 100644 --- a/appendices/glossary.txt +++ b/appendices/glossary.txt @@ -779,26 +779,28 @@ Linear Resource:: * a slink:VkBuffer * a slink:VkImage created with ename:VK_IMAGE_TILING_LINEAR ifdef::VK_EXT_image_drm_format_modifier[] - * a slink:VkImage created with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT - and whose <<glossary-drm-format-modifier,Linux DRM format modifier>> - is ename:DRM_FORMAT_MOD_LINEAR + * a slink:VkImage created with + ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and whose + <<glossary-drm-format-modifier,Linux DRM format modifier>> is + ename:DRM_FORMAT_MOD_LINEAR endif::VK_EXT_image_drm_format_modifier[] + A resource is _non-linear_ if it is one of the following: * a slink:VkImage created with ename:VK_IMAGE_TILING_OPTIMAL ifdef::VK_EXT_image_drm_format_modifier[] - * a slink:VkImage created with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT - and whose <<glossary-drm-format-modifier,Linux DRM format modifier>> - is not ename:DRM_FORMAT_MOD_LINEAR + * a slink:VkImage created with + ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and whose + <<glossary-drm-format-modifier,Linux DRM format modifier>> is not + ename:DRM_FORMAT_MOD_LINEAR endif::VK_EXT_image_drm_format_modifier[] ifdef::VK_EXT_image_drm_format_modifier[] [[glossary-drm-format-modifier,Linux DRM format modifier]] Linux DRM Format Modifier:: A 64-bit, vendor-prefixed, semi-opaque unsigned integer that describes - vendor-specific details of an image's memory layout. In Linux graphics APIs, - _modifiers_ are - commonly used to specify the memory layout of externally shared images. + vendor-specific details of an image's memory layout. + In Linux graphics APIs, _modifiers_ are commonly used to specify the + memory layout of externally shared images. An image has a _modifier_ if and only if it is created with pname:tiling equal to ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. For more details, refer to the appendix for extension diff --git a/appendices/spirvenv.txt b/appendices/spirvenv.txt index 0f441002..3d030aec 100755 --- a/appendices/spirvenv.txt +++ b/appendices/spirvenv.txt @@ -640,7 +640,8 @@ instructions: <<ieee-754,IEEE 754>> infinity. * Any denormalized value input into a shader or potentially generated by any instruction in a shader may: be flushed to 0. - * The rounding mode cannot: be set and is undefined. + * The rounding mode cannot: be set, and results will be <<Correctly + Rounded>>, as described below. * [eq]##NaN##s may: not be generated. Instructions that operate on a [eq]#NaN# may: not result in a [eq]#NaN#. * Support for signaling [eq]##NaN##s is optional: and exceptions are never @@ -678,7 +679,7 @@ Where the range of allowed return values includes any value of magnitude larger than that of the largest representable finite floating-point number, operations may return an infinity of the appropriate sign. If the infinitely precise result of the operation is not mathematically -defined then the value returned is undefined. +defined then the value returned is undefined:. .Inherited From ... Where an operation's precision is described as being inherited from a @@ -731,11 +732,11 @@ at least as follows, unless decorated with RelaxedPrecision: GLSL.std.450 extended instructions specifically defined in terms of the above instructions inherit the above errors. GLSL.std.450 extended instructions not listed above and not defined in terms -of the above have undefined precision. +of the above have undefined: precision. These include, for example, the trigonometric functions and determinant. For the code:OpSRem and code:OpSMod instructions, if either operand is -negative the result is undefined. +negative the result is undefined:. [NOTE] .Note diff --git a/chapters/VK_EXT_blend_operation_advanced/advanced_blend.txt b/chapters/VK_EXT_blend_operation_advanced/advanced_blend.txt index 2c24a139..3a69fb15 100644 --- a/chapters/VK_EXT_blend_operation_advanced/advanced_blend.txt +++ b/chapters/VK_EXT_blend_operation_advanced/advanced_blend.txt @@ -141,7 +141,7 @@ as the product of non-premultiplied R, G, and B component values and the A component of the color. If any R, G, or B component of a premultiplied input color is non-zero and the A component is zero, the color is considered ill-formed, and the -corresponding component of the blend result is undefined. +corresponding component of the blend result is undefined:. The weighting functions [eq]#p~0~#, [eq]#p~1~#, and [eq]#p~2~# are defined in table <<framebuffer-blend-advanced-overlap-modes,Advanced Blend Overlap diff --git a/chapters/VK_EXT_debug_report.txt b/chapters/VK_EXT_debug_report.txt index 730e0f0f..ca264f6e 100644 --- a/chapters/VK_EXT_debug_report.txt +++ b/chapters/VK_EXT_debug_report.txt @@ -88,7 +88,7 @@ which cause a debug report, are: include::../api/enums/VkDebugReportFlagBitsEXT.txt[] * ename:VK_DEBUG_REPORT_ERROR_BIT_EXT specifies that an error that may - cause undefined results, including an application crash. + cause undefined: results, including an application crash. * ename:VK_DEBUG_REPORT_WARNING_BIT_EXT specifies use of Vulkan that may: expose an app bug. Such cases may not be immediately harmful, such as a fragment shader @@ -134,7 +134,7 @@ include::../api/funcpointers/PFN_vkDebugReportCallbackEXT.txt[] triggered. * pname:object is the object where the issue was detected. If pname:objectType is ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, - pname:object is undefined. + pname:object is undefined:. * pname:location is a component (layer, driver, loader) defined value that specifies the _location_ of the trigger. This is an optional: value. diff --git a/chapters/VK_EXT_debug_utils.txt b/chapters/VK_EXT_debug_utils.txt index 534ea4cb..80c3d13b 100644 --- a/chapters/VK_EXT_debug_utils.txt +++ b/chapters/VK_EXT_debug_utils.txt @@ -466,7 +466,7 @@ include::../api/enums/VkDebugUtilsMessageSeverityFlagBitsEXT.txt[] In general if you see a warning but you know that the behavior is intended/desired, then simply ignore the warning. * ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT specifies that an - error that may cause undefined results, including an application crash. + error that may cause undefined: results, including an application crash. -- diff --git a/chapters/VK_FUCHSIA_imagepipe_surface/platformCreateSurface_imagepipe.txt b/chapters/VK_FUCHSIA_imagepipe_surface/platformCreateSurface_imagepipe.txt new file mode 100644 index 00000000..c39ce1cf --- /dev/null +++ b/chapters/VK_FUCHSIA_imagepipe_surface/platformCreateSurface_imagepipe.txt @@ -0,0 +1,53 @@ +// Copyright (c) 2014-2018 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ + +[[platformCreateSurface_imagepipe,platformCreateSurface_imagepipe]] + +=== Fuchsia Platform + +[open,refpage='vkCreateImagePipeSurfaceFUCHSIA',desc='Create a slink:VkSurfaceKHR object for a Fuchsia ImagePipe',type='protos'] +-- + +To create a sname:VkSurfaceKHR object for a Fuchsia ImagePipe, call: + +include::../../api/protos/vkCreateImagePipeSurfaceFUCHSIA.txt[] + + * pname:instance is the instance to associate with the surface. + * pname:pCreateInfo is a pointer to an instance of the + slink:VkImagePipeSurfaceCreateInfoFUCHSIA structure containing + parameters affecting the creation of the surface object. + * pname:pAllocator is the allocator used for host memory allocated for the + surface object when there is no more specific allocator available (see + <<memory-allocation,Memory Allocation>>). + * pname:pSurface points to a slink:VkSurfaceKHR handle in which the + created surface object is returned. + +include::../../validity/protos/vkCreateImagePipeSurfaceFUCHSIA.txt[] +-- + +[open,refpage='VkImagePipeSurfaceCreateInfoFUCHSIA',desc='Structure specifying parameters of a newly created ImagePipe surface object',type='structs'] +-- + +The sname:VkImagePipeSurfaceCreateInfoFUCHSIA structure is defined as: + +include::../../api/structs/VkImagePipeSurfaceCreateInfoFUCHSIA.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:imagePipeHandle is a code:zx_handle_t referring to the ImagePipe + to associate with the surface. + +.Valid Usage +**** + * [[VUID-VkImagePipeSurfaceCreateInfoFUCHSIA-imagePipeHandle-00000]] + pname:imagePipeHandle must: be a valid code:zx_handle_t +**** + +include::../../validity/structs/VkImagePipeSurfaceCreateInfoFUCHSIA.txt[] +-- + +On Fuchsia, the surface pname:currentExtent is the special value +[eq]#(0xFFFFFFFF, 0xFFFFFFFF)#, indicating that the surface size will be +determined by the extent of a swapchain targeting the surface. diff --git a/chapters/VK_FUCHSIA_imagepipe_surface/platformQuerySupport_imagepipe.txt b/chapters/VK_FUCHSIA_imagepipe_surface/platformQuerySupport_imagepipe.txt new file mode 100644 index 00000000..c7bfda55 --- /dev/null +++ b/chapters/VK_FUCHSIA_imagepipe_surface/platformQuerySupport_imagepipe.txt @@ -0,0 +1,12 @@ +// Copyright (c) 2014-2018 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ + +[[platformQuerySupport_fuchsia,platformQuerySupport_fuchsia]] + +=== Fuchsia Platform + +On Fuchsia, all physical devices and queue families must: be capable of +presentation with any ImagePipe. +As a result there is no Fuchsia-specific query for these capabilities. + diff --git a/chapters/VK_KHR_surface/wsi.txt b/chapters/VK_KHR_surface/wsi.txt index 7eed4236..14d922a0 100644 --- a/chapters/VK_KHR_surface/wsi.txt +++ b/chapters/VK_KHR_surface/wsi.txt @@ -114,6 +114,10 @@ ifdef::VK_KHR_xlib_surface[] include::../VK_KHR_xlib_surface/platformCreateSurface_xlib.txt[] endif::VK_KHR_xlib_surface[] +ifdef::VK_FUCHSIA_imagepipe_surface[] +include::../VK_FUCHSIA_imagepipe_surface/platformCreateSurface_imagepipe.txt[] +endif::VK_FUCHSIA_imagepipe_surface[] + ifdef::VK_MVK_ios_surface[] include::../VK_MVK_ios_surface/platformCreateSurface_ios.txt[] endif::VK_MVK_ios_surface[] @@ -243,6 +247,10 @@ ifdef::VK_KHR_xlib_surface[] include::../VK_KHR_xlib_surface/platformQuerySupport_xlib.txt[] endif::VK_KHR_xlib_surface[] +ifdef::VK_FUCHSIA_imagepipe_surface[] +include::../VK_FUCHSIA_imagepipe_surface/platformQuerySupport_imagepipe.txt[] +endif::VK_FUCHSIA_imagepipe_surface[] + ifdef::VK_MVK_ios_surface[] include::../VK_MVK_ios_surface/platformQuerySupport_ios.txt[] endif::VK_MVK_ios_surface[] diff --git a/chapters/VK_KHR_swapchain/wsi.txt b/chapters/VK_KHR_swapchain/wsi.txt index 1af1e40d..0fa8a962 100644 --- a/chapters/VK_KHR_swapchain/wsi.txt +++ b/chapters/VK_KHR_swapchain/wsi.txt @@ -169,7 +169,7 @@ Usage requirements. swapchain may: not own all of their pixels. Pixels in the presentable images that correspond to regions of the target surface obscured by another window on the desktop, or subject to - some other clipping mechanism will have undefined content when read + some other clipping mechanism will have undefined: content when read back. Pixel shaders may: not execute for these pixels, and thus any side effects they would have had will not occur. @@ -585,14 +585,14 @@ the sname:VkImages returned by fname:vkGetSwapchainImagesKHR. The memory for each image will not alias with the memory for other images or with any sname:VkDeviceMemory object. As such, performing any operation affecting the binding of memory to a -presentable image results in undefined behavior. +presentable image results in undefined: behavior. All presentable images are initially in the ename:VK_IMAGE_LAYOUT_UNDEFINED layout, thus before using presentable images, the application must: transition them to a valid layout for the intended use. Further, the lifetime of presentable images is controlled by the implementation so destroying a presentable image with flink:vkDestroyImage -results in undefined behavior. +results in undefined: behavior. See flink:vkDestroySwapchainKHR for further details on the lifetime of presentable images. @@ -809,15 +809,26 @@ re-create the swapchain to better match the platform surface properties. If the native surface and presented image sizes no longer match, presentation may: fail. -If presentation does succeed, parts of the native surface may: be undefined, -parts of the presented image may: have been clipped before presentation, -and/or the image may: have been scaled (uniformly or not uniformly) before -presentation. +If presentation does succeed, the mapping from the presented image to the +native surface is implementation-defined. It is the application's responsibility to detect surface size changes and react appropriately. If presentation fails because of a mismatch in the surface and presented image sizes, a ename:VK_ERROR_OUT_OF_DATE_KHR error will be returned. +[NOTE] +.Note +==== +For example, consider a 4x3 window/surface that gets resized to be 3x4 +(taller than wider). +On some window systems, the portion of the window/surface that was +previously and still is visible (the 3x3 part) will contain the same +contents as before, while the remaining parts of the window will have +undefined: contents. +Other window systems may: squash/stretch the image to fill the new window +size without any undefined: contents, or apply some other mapping. +==== + ifdef::VK_VERSION_1_1,VK_KHR_device_group[] [open,refpage='vkAcquireNextImage2KHR',desc='Retrieve the index of the next available presentable image',type='protos'] @@ -1122,7 +1133,7 @@ If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then each element of pname:pDeviceMasks selects which instances of the swapchain image are component-wise summed and the sum of those images is presented. If the sum in any component is outside the representable range, the value of -that component is undefined. +that component is undefined:. Each element of pname:pDeviceMasks must: have a value for which all set bits are set in one of the elements of slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask. @@ -1232,7 +1243,7 @@ as they were prior to transitioning the image to the present source layout and presenting it. However, if a mechanism other than Vulkan is used to modify the platform window associated with the swapchain, the content of all presentable images -in the swapchain becomes undefined. +in the swapchain becomes undefined:. [NOTE] .Note diff --git a/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt b/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt index 23166808..c6b86ad0 100644 --- a/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt +++ b/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt @@ -50,7 +50,9 @@ include::../../api/structs/VkWaylandSurfaceCreateInfoKHR.txt[] include::../../validity/structs/VkWaylandSurfaceCreateInfoKHR.txt[] -- -On Wayland, pname:currentExtent is undefined [eq]#(0xFFFFFFFF, 0xFFFFFFFF)#. +On Wayland, pname:currentExtent is the special value [eq]#(0xFFFFFFFF, +0xFFFFFFFF)#, indicating that the surface size will be determined by the +extent of a swapchain targeting the surface. Whatever the application sets a swapchain's pname:imageExtent to will be the size of the window, after the first image is presented. pname:minImageExtent is [eq]#(1,1)#, and pname:maxImageExtent is the maximum diff --git a/chapters/VK_NN_vi_surface/platformCreateSurface_vi.txt b/chapters/VK_NN_vi_surface/platformCreateSurface_vi.txt index 476b768f..a8689891 100644 --- a/chapters/VK_NN_vi_surface/platformCreateSurface_vi.txt +++ b/chapters/VK_NN_vi_surface/platformCreateSurface_vi.txt @@ -25,9 +25,9 @@ During the lifetime of a surface created using a particular code:nn::code:vi::code:NativeWindowHandle any attempts to create another surface for the same code:nn::code:vi::code:Layer and any attempts to connect to the same code:nn::code:vi::code:Layer through other platform -mechanisms will have undefined results. +mechanisms will have undefined: results. -The pname:currentExtent of a VI surface is always undefined. +The pname:currentExtent of a VI surface is always undefined:. Applications are expected to choose an appropriate size for the swapchain's pname:imageExtent (e.g., by matching the result of a call to code:nn::code:vi::code:GetDisplayResolution). diff --git a/chapters/VK_NVX_device_generated_commands/generation.txt b/chapters/VK_NVX_device_generated_commands/generation.txt index 9c2151ae..45465816 100644 --- a/chapters/VK_NVX_device_generated_commands/generation.txt +++ b/chapters/VK_NVX_device_generated_commands/generation.txt @@ -54,7 +54,7 @@ defined in the command buffer prior this call. However, given the stateless nature of the generated sequences, they will not affect commands after the reserved space. Treat the state that can: be affected by the provided -sname:VkIndirectCommandsLayoutNVX as undefined. +sname:VkIndirectCommandsLayoutNVX as undefined:. [open,refpage='vkCmdProcessCommandsNVX',desc='Performs the generation of commands on the device',type='protos'] -- @@ -187,7 +187,7 @@ cmdProcessAllSequences(cmd, objectTable, .Note ==== It is important to note that the state that may be affected through -generated commands must: be considered undefined for the commands following +generated commands must: be considered undefined: for the commands following them. It is not possible to setup generated state and provoking work that uses this state outside of the generated sequence. diff --git a/chapters/clears.txt b/chapters/clears.txt index 154ca86d..a6189c86 100644 --- a/chapters/clears.txt +++ b/chapters/clears.txt @@ -370,7 +370,7 @@ include::../api/structs/VkClearColorValue.txt[] negative values in the smaller type). If the integer clear value is not representable in the target type (e.g. would overflow in conversion to that type), the clear value is - undefined. + undefined:. * pname:uint32 are the color clear values when the format of the image or attachment is unsigned integer (etext:UINT). Unsigned integer values are converted to the format of the image by diff --git a/chapters/cmdbuffers.txt b/chapters/cmdbuffers.txt index bab61926..752c3f0d 100644 --- a/chapters/cmdbuffers.txt +++ b/chapters/cmdbuffers.txt @@ -32,18 +32,18 @@ Each command buffer manages state independently of other command buffers. There is no inheritance of state across primary and secondary command buffers, or between secondary command buffers. When a command buffer begins recording, all state in that command buffer is -undefined. +undefined:. When secondary command buffer(s) are recorded to execute on a primary command buffer, the secondary command buffer inherits no state from the primary command buffer, and all state of the primary command buffer is -undefined after an execute secondary command buffer command is recorded. +undefined: after an execute secondary command buffer command is recorded. There is one exception to this rule - if the primary command buffer is inside a render pass instance, then the render pass and subpass state is not disturbed by executing secondary command buffers. -Whenever the state of a command buffer is undefined, the application must: +Whenever the state of a command buffer is undefined:, the application must: set all relevant state on the command buffer before any state dependent commands such as draws and dispatches are recorded, otherwise the behavior -of executing that command buffer is undefined. +of executing that command buffer is undefined:. Unless otherwise specified, and without explicit synchronization, the various commands submitted to a queue via command buffers may: execute in @@ -101,8 +101,7 @@ Invalid:: Command buffers in the invalid state can: only be reset or freed. [[commandbuffer-lifecycle-diagram]] -[%inline] -image::images/commandbuffer_lifecycle.svg[title="Lifecycle of a command buffer",align="center"] +image::images/commandbuffer_lifecycle.svg[title="Lifecycle of a command buffer",align="center",opts="{imageopts}"] Any given command that operates on a command buffer has its own requirements on what state a command buffer must: be in, which are detailed in the valid @@ -1351,7 +1350,7 @@ the fname:vkCmdWaitEvents commands that wait upon them must: not be inside a render pass instance. Implementations may: have limits on how long the command buffer will wait, in order to avoid interfering with progress of other clients of the device. -If the event is not signaled within these limits, results are undefined and +If the event is not signaled within these limits, results are undefined: and may: include device loss. diff --git a/chapters/copies.txt b/chapters/copies.txt index b76bfbe9..594d0651 100644 --- a/chapters/copies.txt +++ b/chapters/copies.txt @@ -84,8 +84,8 @@ include::../api/protos/vkCmdCopyBuffer.txt[] Each region in pname:pRegions is copied from the source buffer to the same region of the destination buffer. pname:srcBuffer and pname:dstBuffer can: be the same buffer or alias the -same memory, but the result is undefined if the copy regions overlap in -memory. +same memory, but the resulting values are undefined: if the copy regions +overlap in memory. .Valid Usage **** @@ -1102,7 +1102,7 @@ Specifically: * data copied to or from the depth aspect of a ename:VK_FORMAT_X8_D24_UNORM_PACK32 or ename:VK_FORMAT_D24_UNORM_S8_UINT format is packed with one 32-bit word per texel with the D24 value in - the LSBs of the word, and undefined values in the eight MSBs. + the LSBs of the word, and undefined: values in the eight MSBs. [NOTE] .Note @@ -1115,8 +1115,11 @@ in pname:imageSubresource, and the other specifies the stencil aspect. Because depth or stencil aspect buffer to image copies may: require format conversions on some implementations, they are not supported on queues that do not support graphics. + +ifndef::VK_EXT_depth_range_unrestricted[] When copying to a depth aspect, the data in buffer memory must: be in the -the range [eq]#[0,1]# or undefined results occur. +the range [eq]#[0,1]#, or the resulting values are undefined:. +endif::VK_EXT_depth_range_unrestricted[] Copies are done layer by layer starting with image layer pname:baseArrayLayer member of pname:imageSubresource. @@ -1301,9 +1304,11 @@ endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] If the calling command's sname:VkImage parameter is of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the pname:baseArrayLayer and pname:layerCount members of pname:imageSubresource must: be `0` and `1`, respectively +ifndef::VK_EXT_depth_range_unrestricted[] * [[VUID-VkBufferImageCopy-None-00214]] When copying to the depth aspect of an image subresource, the data in the source buffer must: be in the range [eq]#[0,1]# +endif::VK_EXT_depth_range_unrestricted[] **** include::../validity/structs/VkBufferImageCopy.txt[] @@ -1479,9 +1484,9 @@ between pname:srcOffsets[0].pname:z and pname:srcOffsets[1].pname:z. If the pname:filter parameter is ename:VK_FILTER_LINEAR then the value sampled from the source image is taken by doing linear filtering using the interpolated *z* coordinate. -If pname:filter parameter is ename:VK_FILTER_NEAREST then value sampled from -the source image is taken from the single nearest slice (with undefined -rounding mode). +If pname:filter parameter is ename:VK_FILTER_NEAREST then the value sampled +from the source image is taken from the single nearest slice, with an +implementation-dependent arithmetic rounding mode. The following filtering and conversion rules apply: diff --git a/chapters/descriptorsets.txt b/chapters/descriptorsets.txt index 5a3667f2..190df469 100644 --- a/chapters/descriptorsets.txt +++ b/chapters/descriptorsets.txt @@ -537,8 +537,8 @@ The above layout definition allows the descriptor bindings to be specified sparsely such that not all binding numbers between 0 and the maximum binding number need to be specified in the pname:pBindings array. Bindings that are not specified have a pname:descriptorCount and -pname:stageFlags of zero, and the pname:descriptorType is treated as -undefined. +pname:stageFlags of zero, and the value of pname:descriptorType is +undefined:. However, all binding numbers between 0 and the maximum binding number in the slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings array may: consume memory in the descriptor set layout even if not all descriptor bindings are @@ -908,7 +908,7 @@ pname:descriptorCount of zero is treated as if the pname:descriptorCount is one, and thus the binding is not ignored and the maximum descriptor count will be returned. If the layout is not supported, then the value written to -pname:maxVariableDescriptorCount is undefined. +pname:maxVariableDescriptorCount is undefined:. include::../validity/structs/VkDescriptorSetVariableDescriptorCountLayoutSupportEXT.txt[] -- @@ -1572,7 +1572,7 @@ include::../api/structs/VkPushConstantRange.txt[] that will access a range of push constants. If a particular stage is not included in the range, then accessing members of that range of push constants from the corresponding shader - stage will result in undefined data being read. + stage will return undefined: values. * pname:offset and pname:size are the start offset and size, respectively, consumed by the range. Both pname:offset and pname:size are in units of bytes and must: be a @@ -2090,7 +2090,7 @@ include::../api/protos/vkAllocateDescriptorSets.txt[] The allocated descriptor sets are returned in pname:pDescriptorSets. When a descriptor set is allocated, the initial state is largely -uninitialized and all descriptors are undefined. +uninitialized and all descriptors are undefined:. However, the descriptor set can: be bound in a command buffer without causing errors or exceptions. ifdef::VK_EXT_descriptor_indexing[] @@ -2107,9 +2107,14 @@ ifndef::VK_EXT_descriptor_indexing[] All descriptors that are statically used must: have been populated before the descriptor set is consumed. endif::VK_EXT_descriptor_indexing[] +ifdef::VK_EXT_inline_uniform_block[] +Descriptor bindings with descriptor type of +ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT need not be populated +before the descriptor set is consumed. +endif::VK_EXT_inline_uniform_block[] Entries that are not used by a pipeline can: have uninitialized descriptors or descriptors of resources that have been destroyed, and executing a draw -or dispatch with such a descriptor set bound does not cause undefined +or dispatch with such a descriptor set bound does not cause undefined: behavior. This means applications need not populate unused entries with dummy descriptors. @@ -3669,7 +3674,7 @@ descriptor set and later bound to a command buffer. Push descriptors allow for incremental updates of descriptors without managing the lifetime of descriptor sets. -When a command buffer begins recording, all push descriptors have undefined +When a command buffer begins recording, all push descriptors have undefined: contents. Push descriptors can: be updated incrementally and cause shaders to use the updated descriptors for subsequent rendering commands (either compute or @@ -3848,7 +3853,8 @@ Push constants represent a high speed path to modify constant data in pipelines that is expected to outperform memory-backed resource updates. ==== -The values of push constants are undefined at the start of a command buffer. +The values of push constants are undefined: at the start of a command +buffer. [open,refpage='vkCmdPushConstants',desc='Update the values of push constants',type='protos'] -- diff --git a/chapters/devsandqueues.txt b/chapters/devsandqueues.txt index 264a2ccd..51921479 100644 --- a/chapters/devsandqueues.txt +++ b/chapters/devsandqueues.txt @@ -344,8 +344,8 @@ ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] compatibility>> endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] -If pname:deviceLUIDValid is ename:VK_FALSE, the contents of pname:deviceLUID -and pname:deviceNodeMask are undefined. +If pname:deviceLUIDValid is ename:VK_FALSE, the values of pname:deviceLUID +and pname:deviceNodeMask are undefined:. If pname:deviceLUIDValid is ename:VK_TRUE and Vulkan is running on the Windows operating system, the contents of pname:deviceLUID can: be cast to an sname:LUID object and must: be equal to the locally unique identifier of @@ -482,6 +482,7 @@ include::../api/protos/vkGetPhysicalDeviceQueueFamilyProperties.txt[] If pname:pQueueFamilyProperties is `NULL`, then the number of queue families available is returned in pname:pQueueFamilyPropertyCount. +Implementations must: support at least one queue family. Otherwise, pname:pQueueFamilyPropertyCount must: point to a variable set by the user to the number of elements in the pname:pQueueFamilyProperties array, and on return the variable is overwritten with the number of @@ -504,6 +505,7 @@ include::../api/structs/VkQueueFamilyProperties.txt[] capabilities of the queues in this queue family. * pname:queueCount is the unsigned integer count of queues in this queue family. + Each queue family must: support at least one queue. * pname:timestampValidBits is the unsigned integer count of meaningful bits in the timestamps written via fname:vkCmdWriteTimestamp. The valid range for the count is 36..64 bits, or a value of 0, @@ -1089,10 +1091,10 @@ via the Vulkan API. ==== Undefined behavior caused by an application error may: cause a device to become lost. -However, such undefined behavior may: also cause unrecoverable damage to the -process, and it is then not guaranteed that the API objects, including the -sname:VkPhysicalDevice or the sname:VkInstance are still valid or that the -error is recoverable. +However, such undefined: behavior may: also cause unrecoverable damage to +the process, and it is then not guaranteed that the API objects, including +the sname:VkPhysicalDevice or the sname:VkInstance are still valid or that +the error is recoverable. ==== When a device is lost, its child objects are not implicitly destroyed and @@ -1102,7 +1104,7 @@ can: be destroyed (see the <<fundamentals-objectmodel-lifetime,Object Lifetime>> section). The host address space corresponding to device memory mapped using flink:vkMapMemory is still valid, and host memory accesses to these mapped -regions are still valid, but the contents are undefined. +regions are still valid, but the contents are undefined:. It is still legal to call any API command on the device and child objects. Once a device is lost, command execution may: fail, and commands that return @@ -1128,10 +1130,10 @@ ename:VK_ERROR_DEVICE_LOST is equivalent to ename:VK_SUCCESS. ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] The content of any external memory objects that have been exported from or -imported to a lost device become undefined. +imported to a lost device become undefined:. Objects on other logical devices or in other APIs which are associated with the same underlying memory resource as the external memory objects on the -lost device are unaffected other than their content becoming undefined. +lost device are unaffected other than their content becoming undefined:. The layout of subresources of images on other logical devices that are bound to sname:VkDeviceMemory objects associated with the same underlying memory resources as external memory objects on the lost device becomes @@ -1143,10 +1145,10 @@ ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[] The state of sname:VkSemaphore objects on other logical devices created by <<synchronization-semaphores-importing,importing a semaphore payload>> with -temporary permanence which was exported from the lost device is undefined. +temporary permanence which was exported from the lost device is undefined:. The state of sname:VkSemaphore objects on other logical devices that permanently share a semaphore payload with a sname:VkSemaphore object on the -lost device is undefined, and remains undefined following any subsequent +lost device is undefined:, and remains undefined: following any subsequent signal operations. Implementations must: ensure pending and subsequently submitted wait operations on such semaphores behave as defined in diff --git a/chapters/drawing.txt b/chapters/drawing.txt index 2ed6e160..bafb1cf7 100644 --- a/chapters/drawing.txt +++ b/chapters/drawing.txt @@ -156,8 +156,7 @@ ename:VK_PRIMITIVE_TOPOLOGY_POINT_LIST. Each vertex defines a separate point. .Point Lists -[%inline] -image::images/primitive_topology_point_list.svg[align="center"] +image::images/primitive_topology_point_list.svg[align="center",opts="{imageopts}"] === Line Lists @@ -169,8 +168,7 @@ vertices each defining one more segment. If the number of vertices is odd, then the last vertex is ignored. .Line Lists -[%inline] -image::images/primitive_topology_line_list.svg[align="center"] +image::images/primitive_topology_line_list.svg[align="center",opts="{imageopts}"] === Line Strips @@ -186,8 +184,7 @@ The last vertex specifies the end of the last segment. If only one vertex is specified, then no primitive is generated. .Line Strips -[%inline] -image::images/primitive_topology_line_strip.svg[align="center"] +image::images/primitive_topology_line_strip.svg[align="center",opts="{imageopts}"] === Triangle Lists @@ -201,8 +198,7 @@ where there are [eq]#3 n {plus} k# vertices drawn. vertices are ignored. .Triangle Lists -[%inline] -image::images/primitive_topology_triangle_list.svg[align="center"] +image::images/primitive_topology_triangle_list.svg[align="center",opts="{imageopts}"] === Triangle Strips @@ -218,8 +214,7 @@ The order of vertices in successive triangles changes as shown in the figure below, so that all triangle faces have the same orientation. .Triangle Strips -[%inline] -image::images/primitive_topology_triangle_strip.svg[align="center"] +image::images/primitive_topology_triangle_strip.svg[align="center",opts="{imageopts}"] === Triangle Fans @@ -230,8 +225,7 @@ It is similar to a triangle strip, but changes the vertex replaced from the previous triangle so that all triangles in the fan share a common vertex. .Triangle Fans -[%inline] -image::images/primitive_topology_triangle_fan.svg[align="center"] +image::images/primitive_topology_triangle_fan.svg[align="center",opts="{imageopts}"] === Line Lists With Adjacency @@ -252,8 +246,7 @@ are considered adjacent to vertices [eq]#4 i {plus} 1# and [eq]#4 i {plus} 2#, respectively. .Line Lists With Adjacency -[%inline] -image::images/primitive_topology_line_list_with_adjacency.svg[align="center"] +image::images/primitive_topology_line_list_with_adjacency.svg[align="center",opts="{imageopts}"] === Line Strips With Adjacency @@ -273,8 +266,7 @@ considered adjacent to vertices [eq]#i {plus} 1# and [eq]#i {plus} 2#, respectively. .Line Strips With Adjacency -[%inline] -image::images/primitive_topology_line_strip_with_adjacency.svg[align="center"] +image::images/primitive_topology_line_strip_with_adjacency.svg[align="center",opts="{imageopts}"] === Triangle Lists With Adjacency @@ -296,8 +288,7 @@ For triangle [eq]#i#, vertices [eq]#6 i {plus} 1#, [eq]#6 i {plus} 3#, and 4#, and from [eq]#6 i {plus} 4# to [eq]#6 i# vertices, respectively. .Triangle Lists With Adjacency -[%inline] -image::images/primitive_topology_triangle_list_with_adjacency.svg[align="center"] +image::images/primitive_topology_triangle_list_with_adjacency.svg[align="center",opts="{imageopts}"] === Triangle Strips With Adjacency @@ -314,8 +305,7 @@ are [eq]#2 (n {plus} 2) {plus} k# vertices. If there are fewer than 6 vertices, the entire primitive is ignored. .Triangle Strips With Adjacency -[%inline] -image::images/primitive_topology_triangle_strip_with_adjacency.svg[align="center"] +image::images/primitive_topology_triangle_strip_with_adjacency.svg[align="center",opts="{imageopts}"] The table below illustrates the vertices and order used to draw each triangle, and which vertices are considered adjacent to each edge of those @@ -428,10 +418,10 @@ the pipeline. If the draw includes multiple instances, then the set of primitives is sent to the vertex shading stage multiple times, once for each instance. -It is undefined whether vertex shading occurs on vertices that are discarded -as part of incomplete primitives, but if it does occur then it operates as -if they were vertices in complete primitives and such invocations can: have -side effects. +It is implementation-dependent whether vertex shading occurs on vertices +that are discarded as part of incomplete primitives, but if it does occur +then it operates as if they were vertices in complete primitives and such +invocations can: have side effects. Vertex shading receives two per-vertex inputs from the primitive assembly stage - the code:vertexIndex and the code:instanceIndex. diff --git a/chapters/features.txt b/chapters/features.txt index d45a7199..cd28bb29 100755 --- a/chapters/features.txt +++ b/chapters/features.txt @@ -64,7 +64,7 @@ sname:VkDevice creation time. If a feature is enabled that the physical device does not support, sname:VkDevice creation will fail. If an application uses a feature without enabling it at sname:VkDevice -creation time, the device behavior is undefined. +creation time, the device behavior is undefined:. The validation layer will warn if features are used without being enabled. The fine-grained features are enabled by passing a pointer to the @@ -223,7 +223,7 @@ used. bound to the buffer, but must: not modify any other memory. ** Out-of-bounds atomics may: modify values within the memory range(s) bound to the buffer, but must: not modify any other memory, and return - an undefined value. + an undefined: value. ** Vertex input attributes are considered out of bounds if the offset of the attribute in the bound vertex buffer range plus the size of the attribute is greater than either: @@ -246,7 +246,7 @@ binding for that vertex shader invocation are considered out of bounds. attribute. **** Zero values, or [eq]#(0,0,0,x)# vectors, as described above. ** If pname:robustBufferAccess is not enabled, out of bounds accesses may: - corrupt any memory within the process and cause undefined behavior up + corrupt any memory within the process and cause undefined: behavior up to and including application termination. * [[features-features-fullDrawIndexUint32]] pname:fullDrawIndexUint32 specifies the full 32-bit range of indices is supported for indexed draw @@ -421,9 +421,10 @@ endif::VK_NV_scissor_exclusive[] ** ename:VK_FORMAT_EAC_R11G11_UNORM_BLOCK ** ename:VK_FORMAT_EAC_R11G11_SNORM_BLOCK + +To query for additional properties, or if the feature is not enabled, flink:vkGetPhysicalDeviceFormatProperties and flink:vkGetPhysicalDeviceImageFormatProperties can: be used to check for -additional supported properties of individual formats. +supported properties of individual formats as normal. * [[features-features-textureCompressionASTC_LDR]] pname:textureCompressionASTC_LDR specifies whether all of the ASTC LDR @@ -463,9 +464,10 @@ additional supported properties of individual formats. ** ename:VK_FORMAT_ASTC_12x12_UNORM_BLOCK ** ename:VK_FORMAT_ASTC_12x12_SRGB_BLOCK + +To query for additional properties, or if the feature is not enabled, flink:vkGetPhysicalDeviceFormatProperties and flink:vkGetPhysicalDeviceImageFormatProperties can: be used to check for -additional supported properties of individual formats. +supported properties of individual formats as normal. * [[features-features-textureCompressionBC]] pname:textureCompressionBC specifies whether all of the BC compressed texture formats are @@ -493,9 +495,10 @@ additional supported properties of individual formats. ** ename:VK_FORMAT_BC7_UNORM_BLOCK ** ename:VK_FORMAT_BC7_SRGB_BLOCK + +To query for additional properties, or if the feature is not enabled, flink:vkGetPhysicalDeviceFormatProperties and flink:vkGetPhysicalDeviceImageFormatProperties can: be used to check for -additional supported properties of individual formats. +supported properties of individual formats as normal. * [[features-features-occlusionQueryPrecise]] pname:occlusionQueryPrecise specifies whether occlusion queries returning actual sample counts are @@ -3071,7 +3074,7 @@ mapping of the image view used with min/max filtering must: have been created with the pname:r component set to ename:VK_COMPONENT_SWIZZLE_IDENTITY. Only the pname:r component of the sampled image value is defined and the -other component values are undefined. +other component values are undefined:. If pname:filterMinmaxImageComponentMapping is ename:VK_TRUE this restriction does not apply and image component mapping works as normal. @@ -3090,11 +3093,11 @@ include::../api/structs/VkPhysicalDeviceProtectedMemoryProperties.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:protectedNoFault specifies whether the undefined behavior will not + * pname:protectedNoFault specifies whether the undefined: behavior may: include process termination or device loss. - If pname:protectedNoFault is ename:VK_FALSE, undefined behavior may: + If pname:protectedNoFault is ename:VK_FALSE, undefined: behavior may: include process termination or device loss. - If pname:protectedNoFault is ename:VK_TRUE, undefined behavior will not + If pname:protectedNoFault is ename:VK_TRUE, undefined: behavior will not include process termination or device loss. If the sname:VkPhysicalDeviceProtectedMemoryProperties structure is included @@ -7154,7 +7157,7 @@ sname:VkImageFormatProperties will be filled with zero. .Note ==== Filling sname:VkImageFormatProperties with zero for unsupported formats is -an exception to the usual rule that output structures have undefined +an exception to the usual rule that output structures have undefined: contents on error. This exception was unintentional, but is preserved for backwards compatibility. @@ -7292,7 +7295,7 @@ pname:imageFormatProperties will be filled with zero. .Note ==== Filling pname:imageFormatProperties with zero for unsupported formats is an -exception to the usual rule that output structures have undefined contents +exception to the usual rule that output structures have undefined: contents on error. This exception was unintentional, but is preserved for backwards compatibility. diff --git a/chapters/fragops.txt b/chapters/fragops.txt index d1249e91..250293bc 100644 --- a/chapters/fragops.txt +++ b/chapters/fragops.txt @@ -633,7 +633,7 @@ coverage value. endif::VK_NV_sample_mask_override_coverage[] If such a fragment shader did not assign a value to code:SampleMask due to flow of control, the value code:ANDed with the fragment coverage is -undefined. +undefined:. If no fragment shader is active, or if the active fragment shader does not include code:SampleMask in its interface, the fragment coverage is not modified. @@ -967,7 +967,7 @@ stencil comparison. The reference value used by stencil comparison must be within the range [eq]#[0,2^s^-1]# , where [eq]#s# is the number of bits in the stencil framebuffer attachment, otherwise the reference value is considered -undefined. +undefined:. The [eq]#s# least significant bits of pname:compareMask are bitwise code:ANDed with both the reference and the stored stencil value, and the resulting masked values are those that participate in the comparison diff --git a/chapters/fundamentals.txt b/chapters/fundamentals.txt index b6709d58..c67126ef 100644 --- a/chapters/fundamentals.txt +++ b/chapters/fundamentals.txt @@ -684,7 +684,7 @@ although more rigorous validation can: be enabled through the use of layers. The core layer assumes applications are using the API correctly. Except as documented elsewhere in the Specification, the behavior of the -core layer to an application using the API incorrectly is undefined, and +core layer to an application using the API incorrectly is undefined:, and may: include program termination. However, implementations must: ensure that incorrect usage by an application does not affect the integrity of the operating system, the Vulkan @@ -885,7 +885,7 @@ A bit flag is valid if: Any etext:Vk*Flags member or parameter returned from a query command or otherwise output from Vulkan to the application may: contain bit flags -undefined in its corresponding etext:Vk*FlagBits type. +undefined: in its corresponding etext:Vk*FlagBits type. An application cannot: rely on the state of these unspecified bits. @@ -1127,10 +1127,10 @@ ifdef::VK_EXT_descriptor_indexing[] endif::VK_EXT_descriptor_indexing[] If a command returns a run time error, unless otherwise specified any output -parameters will have undefined contents, except that if the output parameter -is a structure with pname:sType and pname:pNext fields, those fields will be -unmodified. -Any structures chained from pname:pNext will also have undefined contents, +parameters will have undefined: contents, except that if the output +parameter is a structure with pname:sType and pname:pNext fields, those +fields will be unmodified. +Any structures chained from pname:pNext will also have undefined: contents, except that pname:sType and pname:pNext will be unmodified. Out of memory errors do not damage any currently existing Vulkan objects. @@ -1212,7 +1212,7 @@ Most single-precision floating-point formats meet these requirements. The special values [eq]#Inf# and [eq]#-Inf# encode values with magnitudes too large to be represented; the special value [eq]#NaN# encodes {ldquo}Not -A Number{rdquo} values resulting from undefined arithmetic operations such +A Number{rdquo} values resulting from undefined: arithmetic operations such as [eq]#0 / 0#. Implementations may: support [eq]#Inf# and [eq]#NaN# in their floating-point computations. diff --git a/chapters/initialization.txt b/chapters/initialization.txt index 0d519a30..dfde861b 100644 --- a/chapters/initialization.txt +++ b/chapters/initialization.txt @@ -41,8 +41,8 @@ be cast to the type of the command being queried. [width="80%",options="header"] |==== | pname:instance | pname:pName | return value -| * | `NULL` | undefined -| invalid instance | * | undefined +| * | `NULL` | undefined: +| invalid instance | * | undefined: ifdef::VK_VERSION_1_1[] | `NULL` | flink:vkEnumerateInstanceVersion | fp endif::VK_VERSION_1_1[] @@ -95,9 +95,9 @@ first parameter) that is pname:device or a child of pname:device. [width="80%",options="header"] |==== | pname:device | pname:pName | return value -| `NULL` | * | undefined -| invalid device | * | undefined -| device | `NULL` | undefined +| `NULL` | * | undefined: +| invalid device | * | undefined: +| device | `NULL` | undefined: | device | core device-level Vulkan command | fp | device | enabled device extension commands | fp | device | * (any pname:pName not covered above) | `NULL` @@ -148,12 +148,12 @@ To obtain a function pointer for a physical-device-level command from a device extension, an application can: use flink:vkGetInstanceProcAddr. This function pointer may: point to dispatch code, which calls a different real implementation for different sname:VkPhysicalDevice objects. -Behavior is undefined if an extension physical-device command is called on a -physical device that does not support the extension. +Behavior is undefined: if an extension physical-device command is called on +a physical device that does not support the extension. Device extensions may: define structures that can: be added to the ptext:pNext chain of physical-device-level commands. -Behavior is undefined if such an extension structure is passed to a +Behavior is undefined: if such an extension structure is passed to a physical-device-level command for a physical device that does not support the extension. diff --git a/chapters/interfaces.txt b/chapters/interfaces.txt index 1261c7bb..bd0a11d3 100755 --- a/chapters/interfaces.txt +++ b/chapters/interfaces.txt @@ -53,7 +53,7 @@ operands to the code:OpEntryPoint instruction and are declared with the code:Input or code:Output storage classes, respectively, in the SPIR-V module. -code:Output variables of a shader stage have undefined values until the +code:Output variables of a shader stage have undefined: values until the shader writes to them or uses the code:Initializer operand when declaring the variable. @@ -371,8 +371,8 @@ B, and A inputs to the blending unit, respectively, or to the output attachment if blending is disabled. If two variables are placed within the same location, they must: have the same underlying type (floating-point or integer). -The input to blending or color attachment writes is undefined for components -which do not correspond to a fragment shader output. +The input values to blending or color attachment writes are undefined: for +components which do not correspond to a fragment shader output. Fragment outputs identified with an code:Index of zero are directed to the first input of the blending unit associated with the corresponding @@ -398,11 +398,11 @@ fixed-point as described in <<fundamentals-fpfixedconv>>; If the color attachment has an integer format, color values are assumed to be integers and converted to the bit-depth of the target. Any value that cannot be represented in the attachment's format is -undefined. +undefined:. For any other attachment format no conversion is performed. If the type of the values written by the fragment shader do not match the -format of the corresponding color attachment, the result is undefined for -those components. +format of the corresponding color attachment, the resulting values are +undefined: for those components. [[interfaces-inputattachment]] @@ -440,7 +440,7 @@ by a fragment stage. The basic data type (floating-point, integer, unsigned integer) of the subpass input must: match the basic format of the corresponding input attachment, or the values of subpass loads from these variables are -undefined. +undefined:. See <<descriptorsets-inputattachment>> for more details. @@ -514,7 +514,7 @@ code:OpTypeSampledImage, or an array of one of these types. The code:Sampled code:Type of an code:OpTypeImage declaration must: match the same basic data type as the corresponding resource, or the values -obtained by reading or sampling from this image are undefined. +obtained by reading or sampling from this image are undefined:. The code:Image code:Format of an code:OpTypeImage declaration must: not be *Unknown*, for variables which are used for code:OpImageRead, @@ -1399,8 +1399,8 @@ ifdef::VK_EXT_shader_stencil_export[] code:FragStencilRefEXT:: Decorating a variable with the code:FragStencilRefEXT built-in decoration -will make that variable contain the stencil reference value for all samples -covered by the fragment. +will make that variable contain the new stencil reference value for all +samples covered by the fragment. This value will be used as the stencil reference value used in stencil testing. + @@ -1409,7 +1409,7 @@ code:StencilRefReplacingEXT execution mode. If a shader declares the code:StencilRefReplacingEXT execution mode and there is an execution path through the shader that does not set code:FragStencilRefEXT, then the fragment's stencil reference value is -undefined for executions of the shader that take that path. +undefined: for executions of the shader that take that path. + The code:FragStencilRefEXT decoration must: be used only within fragment shaders. @@ -1737,7 +1737,7 @@ code:Layer for all output vertices of a given primitive. If the code:Layer value is less than 0 or greater than or equal to the number of layers in the framebuffer, then primitives may: still be rasterized, fragment shaders may: be executed, and the framebuffer values -for all layers are undefined. +for all layers are undefined:. + The code:Layer decoration must: be used only within ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[] @@ -2007,7 +2007,7 @@ point being rasterized, normalized to the size of the point with origin in the upper left corner of the point, as described in <<primsrast-points-basic,Basic Point Rasterization>>. If the primitive the fragment shader invocation belongs to is not a point, -then the variable decorated with code:PointCoord contains an undefined +then the variable decorated with code:PointCoord contains an undefined: value. + The code:PointCoord decoration must: be used only within fragment shaders. @@ -2416,7 +2416,7 @@ explicitly, to be no larger than the implementation-dependent maximum sample-mask (as an array of 32-bit elements), determined by the maximum number of samples. If a fragment shader entry point's interface includes an output variable -decorated with code:SampleMask, the sample mask will be undefined for any +decorated with code:SampleMask, the sample mask will be undefined: for any array elements of any fragment shader invocations that fail to assign a value. If a fragment shader entry point's interface does not include an output @@ -2450,7 +2450,7 @@ code:Input storage class. ifdef::VK_EXT_sample_locations[] If the current pipeline uses <<primrast-samplelocations, custom sample locations>> the value of any variable decorated with the code:SamplePosition -built-in decoration is undefined. +built-in decoration is undefined:. endif::VK_EXT_sample_locations[] + The variable decorated with code:SamplePosition must: be declared as a @@ -2902,7 +2902,7 @@ viewport transform, scissor rectangle, and exclusive endif::VK_NV_scissor_exclusive[] scissor rectangle, for each view. The same values must: be written to all vertices in a given primitive, or -else the set of viewports used for that primitive is undefined. +else the set of viewports used for that primitive is undefined:. + Any variable decorated with code:ViewportMaskPerViewNV must: be declared as an array of scalar 32-bit integers with at least as many elements as the diff --git a/chapters/introduction.txt b/chapters/introduction.txt index eb16e7a5..54b32a9d 100644 --- a/chapters/introduction.txt +++ b/chapters/introduction.txt @@ -85,8 +85,8 @@ in this Specification. *Cannot* means something the application literally is unable to express or accomplish through the API, while *must not* means something that the application is capable of expressing through the API, but that the -consequences of doing so are undefined and potentially unrecoverable for the -implementation. +consequences of doing so are undefined: and potentially unrecoverable for +the implementation. ================== Unless otherwise noted in the section heading, all sections and appendices diff --git a/chapters/memory.txt b/chapters/memory.txt index 6466837b..eeb8e74b 100644 --- a/chapters/memory.txt +++ b/chapters/memory.txt @@ -159,7 +159,7 @@ pname:size bytes, and the contents of the original allocation from bytes zero to [eq]#min(original size, new size) - 1# must: be preserved in the returned allocation. If pname:size is larger than the old size, the contents of the additional -space are undefined. +space are undefined:. If satisfying these requirements involves creating a new allocation, then the old allocation should: be freed. @@ -837,10 +837,10 @@ different types (with potentially different alignment requirements) in the same memory object. ifndef::VK_VERSION_1_1[] -When memory is allocated, its contents are undefined. +When memory is allocated, its contents are undefined:. endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1[] -When memory is allocated, its contents are undefined with the following +When memory is allocated, its contents are undefined: with the following constraint: * The contents of unprotected memory must: not be a function of data @@ -2261,7 +2261,7 @@ object is no longer in use by the device--for example by command buffers in the _pending state_. The memory can: remain bound to images or buffers at the time the memory object is freed, but any further use of them (on host or device) for -anything other than destroying those objects will result in undefined +anything other than destroying those objects will result in undefined: behavior. If there are still any bound images or buffers, the memory may: not be immediately released by the implementation, but must: be released by the @@ -2488,7 +2488,7 @@ available to the host memory domain using the ename:VK_ACCESS_HOST_WRITE_BIT and ename:VK_ACCESS_HOST_READ_BIT <<synchronization-access-types, access types>>, are made visible to the host. If a range of non-coherent memory is written by the host and then -invalidated without first being flushed, its contents are undefined. +invalidated without first being flushed, its contents are undefined:. Within each range described by pname:pMemoryRanges, each set of pname:nonCoherentAtomSize bytes in that range is invalidated if any byte in @@ -2665,20 +2665,21 @@ Protected memory adds the following concepts: ** Unprotected queue operations *** Any read from or write to protected memory during unprotected queue - operations results in undefined behavior but is subject to the + operations results in undefined: behavior but is subject to the inviolable rules below. ** Protected queue operations *** Any write to unprotected memory during protected queue operations - results in undefined behavior but is subject to the inviolable rules + results in undefined: behavior but is subject to the inviolable rules below. *** Except for framebuffer-space pipeline stages, compute shader stage, and transfer stage, any read from or write to protected memory during - protected queue operations results in undefined behavior but is + protected queue operations results in undefined: behavior but is subject to the inviolable rules below. - *** Any queries during protected queue operations results in undefined - behavior but is subject to the inviolable rules below. + *** Any query during protected queue operations results in undefined: + behavior, but is subject to the inviolable rules below. + [[memory-protected-memory-undefined]] ==== Protected memory inviolable rules @@ -2693,7 +2694,7 @@ The implementation must: guarantee that: data from protected memory. Incorrect usage by an application of the memory protection system results in -undefined behavior which may: include process termination or device loss. +undefined: behavior which may: include process termination or device loss. endif::VK_VERSION_1_1[] ifdef::VK_KHR_external_memory_capabilities+VK_ANDROID_external_memory_android_hardware_buffer[] diff --git a/chapters/pipelines.txt b/chapters/pipelines.txt index 3416b08b..a1a116f1 100644 --- a/chapters/pipelines.txt +++ b/chapters/pipelines.txt @@ -84,12 +84,11 @@ Actual ordering guarantees between pipeline stages are explained in detail in the <<synchronization-pipeline-stages-order, synchronization chapter>>. [[pipelines-block-diagram]] -[%inline] ifndef::VK_NV_mesh_shader[] -image::images/pipeline.svg[title="Block diagram of the Vulkan pipeline",align="center"] +image::images/pipeline.svg[title="Block diagram of the Vulkan pipeline",align="center",opts="{imageopts}"] endif::VK_NV_mesh_shader[] ifdef::VK_NV_mesh_shader[] -image::images/pipelinemesh.svg[title="Block diagram of the Vulkan pipeline",{fullimagewidth},align="center"] +image::images/pipelinemesh.svg[title="Block diagram of the Vulkan pipeline",{fullimagewidth},align="center",opts="{imageopts}"] endif::VK_NV_mesh_shader[] Each pipeline is controlled by a monolithic object created from a @@ -1155,10 +1154,8 @@ fixed-function stages of the pipeline are skipped. If a geometry shader is omitted, the geometry shading stage is skipped. -If a fragment shader is omitted, the results of fragment processing are -undefined. -Specifically, any fragment color outputs are considered to have undefined -values, and the fragment depth is considered to be unmodified. +If a fragment shader is omitted, fragment color outputs have undefined: +values, and the fragment depth value is unmodified. This can: be useful for depth-only rendering. Presence of a shader stage in a pipeline is indicated by including a valid @@ -1881,17 +1878,17 @@ parameter: pipeline object, then that command buffer state is not disturbed. * If the state is specified as dynamic in the new pipeline object but is not specified as dynamic in the previous pipeline object, then that - command buffer state becomes undefined. - If the state is an array, then the entire array becomes undefined. + command buffer state becomes undefined:. + If the state is an array, then the entire array becomes undefined:. * If the state is an array specified as dynamic in both the new and the previous pipeline object, and the array size is not the same in both - pipeline objects, then that command buffer state becomes undefined. + pipeline objects, then that command buffer state becomes undefined:. Dynamic state setting commands must: not be issued for state that is not specified as dynamic in the bound pipeline object. Dynamic state that does not affect the result of operations can: be left -undefined. +undefined:. [NOTE] .Note diff --git a/chapters/primsrast.txt b/chapters/primsrast.txt index 0f8a4e2b..08550fc3 100644 --- a/chapters/primsrast.txt +++ b/chapters/primsrast.txt @@ -428,8 +428,7 @@ instructions enabling the application to get direct access to the fragment mask and the individual color fragment values. [[vk-amd-shader-fragment-mask-diagram]] -[%inline] -image::images/fragment_mask.svg[align="center",title="Fragment Mask",align="center"] +image::images/fragment_mask.svg[align="center",title="Fragment Mask",align="center",opts="{imageopts}"] endif::VK_AMD_shader_fragment_mask[] @@ -1306,8 +1305,7 @@ code:PointSize written by: and clamped to the implementation-dependent point size range [eq]#[pname:pointSizeRange[0],pname:pointSizeRange[1]]#. -If the value written to code:PointSize is less than or equal to zero, or if -no value was written to code:PointSize, results are undefined. +The value written to code:PointSize must: be greater than zero. Not all point sizes need be supported, but the size 1.0 must: be supported. The range of supported sizes and the size of evenly-spaced gradations within @@ -1518,8 +1516,7 @@ triangles where each pair of vertices at each end of the line has identical attributes. [[fig-non-strict-lines]] -[%inline] -image::images/non_strict_lines.svg[align="center",title="Non strict lines"] +image::images/non_strict_lines.svg[align="center",title="Non strict lines",opts="{imageopts}"] [[primsrast-polygons]] @@ -1870,7 +1867,7 @@ triangle, where the depth is extrapolated. endif::VK_NV_fill_rectangle[] -If no depth buffer is present, [eq]#r# is undefined. +If no depth buffer is present, [eq]#r# is undefined:. The bias value [eq]#o# for a polygon is diff --git a/chapters/queries.txt b/chapters/queries.txt index b3f96619..8d441804 100644 --- a/chapters/queries.txt +++ b/chapters/queries.txt @@ -160,7 +160,7 @@ Each query in a query pool has a status that is either _unavailable_ or _available_, and also has state to store the numerical results of a query operation of the type requested when the query pool was created. Resetting a query via flink:vkCmdResetQueryPool sets the status to -unavailable and makes the numerical results undefined. +unavailable and makes the numerical results undefined:. Performing a query operation with flink:vkCmdBeginQuery and flink:vkCmdEndQuery changes the status to available when the query <<queries-operation-finished,finishes>>, and updates the numerical results. @@ -178,10 +178,10 @@ flink:vkCmdCopyQueryPoolResults does not include ename:VK_QUERY_RESULT_WAIT_BIT, execution of flink:vkCmdCopyQueryPoolResults may: happen-before the results of flink:vkCmdEndQuery are available. -After query pool creation, each query is in an undefined state and must: be +After query pool creation, each query is in an undefined: state and must: be reset prior to use. Queries must: also be reset between uses. -Using a query that has not been reset will result in undefined behavior. +Using a query that has not been reset will result in undefined: behavior. ifdef::VK_VERSION_1_1,VK_KHR_device_group[] @@ -436,7 +436,7 @@ In either case, the layout in memory is defined as follows: Timestamps write one integer value. * If more than one query is retrieved and pname:stride is not at least as large as the size of the array of integers corresponding to a single - query, the values written to memory are undefined. + query, the values written to memory are undefined:. [open,refpage='vkGetQueryPoolResults',desc='Copy results of queries in a query pool to a host memory region',type='protos'] -- @@ -787,8 +787,8 @@ While the query is active, the pipeline type determines which set of statistics are available, but these must: be configured on the query pool when it is created. If a statistic counter is issued on a command buffer that does not support -the corresponding operation, that counter is undefined after the query has -finished. +the corresponding operation, the value of that counter is undefined: after +the query has finished. At least one statistic counter relevant to the operations supported on the recording command buffer must: be enabled. diff --git a/chapters/renderpass.txt b/chapters/renderpass.txt index f9a65075..9936aecf 100644 --- a/chapters/renderpass.txt +++ b/chapters/renderpass.txt @@ -350,7 +350,7 @@ Correlation masks must: not have a functional effect on the results of the multiview rendering. When multiview is enabled, at the beginning of each subpass all non-render -pass state is undefined. +pass state is undefined:. In particular, each time flink:vkCmdBeginRenderPass or flink:vkCmdNextSubpass is called the graphics pipeline must: be bound, any relevant descriptor sets or vertex/index buffers must: be bound, and any @@ -657,7 +657,7 @@ include::../api/enums/VkAttachmentLoadOp.txt[] ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. * ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE specifies that the previous contents within the area need not be preserved; the contents of the - attachment will be undefined inside the render area. + attachment will be undefined: inside the render area. For attachments with a depth/stencil format, this uses the access type ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type @@ -682,7 +682,7 @@ include::../api/enums/VkAttachmentStoreOp.txt[] ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. * ename:VK_ATTACHMENT_STORE_OP_DONT_CARE specifies the contents within the render area are not needed after rendering, and may: be discarded; the - contents of the attachment will be undefined inside the render area. + contents of the attachment will be undefined: inside the render area. For attachments with a depth/stencil format, this uses the access type ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type @@ -740,7 +740,7 @@ The precise set of valid scenarios is described in more detail If a set of attachments alias each other, then all except the first to be used in the render pass must: use an pname:initialLayout of ename:VK_IMAGE_LAYOUT_UNDEFINED, since the earlier uses of the other aliases -make their contents undefined. +make their contents undefined:. Once an alias has been used and a different alias has been used after it, the first alias must: not be used in any later subpasses. However, an application can: assign the same image view to multiple aliasing @@ -820,8 +820,8 @@ include::../api/structs/VkSubpassDescription.txt[] used by a subpass, but whose contents must: be preserved throughout the subpass. -The contents of an attachment within the render area become undefined at the -start of a subpass *S* if all of the following conditions are true: +The contents of an attachment within the render area become undefined: at +the start of a subpass *S* if all of the following conditions are true: * The attachment is used as a color, depth/stencil, or resolve attachment in any subpass in the render pass. @@ -829,8 +829,8 @@ start of a subpass *S* if all of the following conditions are true: subpass dependency from *S~1~* to *S*. * The attachment is not used or preserved in subpass *S*. -Once the contents of an attachment become undefined in subpass *S*, they -remain undefined for subpasses in subpass dependency chains starting with +Once the contents of an attachment become undefined: in subpass *S*, they +remain undefined: for subpasses in subpass dependency chains starting with subpass *S* until they are written again. However, they remain valid for subpasses in other subpass dependency chains starting with subpass *S~1~* if those subpasses use or preserve the @@ -1338,7 +1338,7 @@ If no sample locations state has been specified for an automatic layout transition performed on an attachment referring to a depth/stencil image created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT the contents of the depth aspect of the depth/stencil attachment become -undefined as if the layout of the attachment was transitioned from the +undefined: as if the layout of the attachment was transitioned from the ename:VK_IMAGE_LAYOUT_UNDEFINED layout. endif::VK_EXT_sample_locations[] @@ -2430,9 +2430,7 @@ restricted to the pixels whose x and y coordinates fall within the render area on all attachments. The render area extends to all layers of pname:framebuffer. The application must: ensure (using scissor if necessary) that all rendering -is contained within the render area, otherwise the pixels outside of the -render area become undefined and shader side effects may: occur for -fragments outside the render area. +is contained within the render area. The render area must: be contained within the framebuffer dimensions. ifdef::VK_VERSION_1_1,VK_KHR_multiview[] diff --git a/chapters/resources.txt b/chapters/resources.txt index 4126b87b..45de848a 100644 --- a/chapters/resources.txt +++ b/chapters/resources.txt @@ -1786,7 +1786,7 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] However, the subresource layout of images in Android hardware buffer external memory is not known until the image has been bound to memory, so calling fname:vkGetImageSubresourceLayout for such an image before it has -been bound will result in undefined behavior. +been bound will result in undefined: behavior. endif::VK_ANDROID_external_memory_android_hardware_buffer[] .Valid Usage @@ -1923,7 +1923,8 @@ adjacent slices of a 3D image. address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compressedTexelBlockByteSize + offset; --------------------------------------------------- -pname:arrayPitch is undefined for images that were not created as arrays. +The value of pname:arrayPitch is undefined: for images that were not created +as arrays. pname:depthPitch is defined only for 3D images. If the image has a @@ -2257,7 +2258,7 @@ If it is ename:VK_IMAGE_LAYOUT_PREINITIALIZED, then the image data can: be preinitialized by the host while using this layout, and the transition away from this layout will preserve that data. If it is ename:VK_IMAGE_LAYOUT_UNDEFINED, then the contents of the data are -considered to be undefined, and the transition away from this layout is not +considered to be undefined:, and the transition away from this layout is not guaranteed to preserve that data. For either of these initial layouts, any image subresources must: be transitioned to another layout before they are accessed by the device. @@ -2437,21 +2438,21 @@ subresource as a depth/stencil attachment, thus applications must: provide the same sample locations that were last used to render to the given image subresource whenever a layout transition of the image subresource happens, otherwise the contents of the depth aspect of the image subresource become -undefined. +undefined:. In addition, depth reads from a depth/stencil attachment referring to an image subresource range of a depth/stencil image created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using different sample locations than what have been last used to perform depth -writes to the image subresources of the same image subresource range produce -undefined results. +writes to the image subresources of the same image subresource range return +undefined: values. Similarly, depth writes to a depth/stencil attachment referring to an image subresource range of a depth/stencil image created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using different sample locations than what have been last used to perform depth writes to the image subresources of the same image subresource range make -the contents of the depth aspect of those image subresources undefined. +the contents of the depth aspect of those image subresources undefined:. endif::VK_EXT_sample_locations[] @@ -3134,7 +3135,7 @@ image array layer [eq]#(pname:baseArrayLayer {plus} i)# is face index [eq]#(i mod 6)# of cube _i / 6_. If the number of layers in the view, whether set explicitly in pname:layerCount or implied by ename:VK_REMAINING_ARRAY_LAYERS, is not a -multiple of 6, behavior when indexing the last cube is undefined. +multiple of 6, behavior when indexing the last cube is undefined:. pname:aspectMask must: be only ename:VK_IMAGE_ASPECT_COLOR_BIT, ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT if @@ -3582,7 +3583,7 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] The precise size of images that will be bound to external Android hardware buffer memory is unknown until the memory has been imported or allocated, so calling flink:vkGetImageMemoryRequirements with such an image before it has -been bound to memory will result in undefined behavior. +been bound to memory will result in undefined: behavior. When importing Android hardware buffer memory, the pname:allocationSize can: be determined by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID. When allocating new memory for an image that can: be exported to an Android @@ -4963,7 +4964,7 @@ A queue family can: take ownership of an image subresource or buffer range of a resource created with ename:VK_SHARING_MODE_EXCLUSIVE, without an ownership transfer, in the same way as for a resource that was just created; however, taking ownership in this way has the effect that the contents of -the image subresource or buffer range are undefined. +the image subresource or buffer range are undefined:. Ranges of buffers and image subresources of image objects created using ename:VK_SHARING_MODE_CONCURRENT must: only be accessed by queues from the @@ -5020,12 +5021,13 @@ identical images that alias the same range of an underlying memory object affect the layout of all the subresources in the set. As a corollary, writes to any image subresources in such a set must: not -make the contents of memory used by other subresources in the set undefined. +make the contents of memory used by other subresources in the set +undefined:. An application can: define the content of a subresource of one image by performing device writes to an identical subresource of another image provided both images are bound to the same region of external memory. Applications may: also add resources to such a set after the content of the -existing set members has been defined without making the content undefined +existing set members has been defined without making the content undefined: by creating a new image with the initial layout ename:VK_IMAGE_LAYOUT_UNDEFINED and binding it to the same region of external memory as the existing images. @@ -5036,13 +5038,13 @@ external memory as the existing images. Because layout transitions apply to all identical images aliasing the same region of external memory, the actual layout of the memory backing a new image as well as an existing image with defined content will not be -undefined. +undefined:. Such an image is not usable until it acquires ownership of its memory from the existing owner. Therefore, the layout specified as part of this transition will be the true initial layout of the image. -The undefined layout specified when creating it is a placeholder to simplify -valid usage requirements. +The undefined: layout specified when creating it is a placeholder to +simplify valid usage requirements. ==== endif::VK_VERSION_1_1,VK_KHR_external_memory[] @@ -5164,25 +5166,25 @@ endif::VK_VERSION_1_1,VK_KHR_external_memory[] Otherwise, the aliases interpret the contents of the memory differently, and writes via one alias make the contents of memory partially or completely -undefined to the other alias. +undefined: to the other alias. If the first alias is a host-accessible subresource, then the bytes affected are those written by the memory operations according to its addressing scheme. If the first alias is not host-accessible, then the bytes affected are those overlapped by the image subresources that were written. If the second alias is a host-accessible subresource, the affected bytes -become undefined. +become undefined:. If the second alias is a not host-accessible, all sparse image blocks (for sparse partially-resident images) or all image subresources (for non-sparse image and fully resident sparse images) that overlap the affected bytes -become undefined. +become undefined:. -If any image subresources are made undefined due to writes to an alias, then -each of those image subresources must: have its layout transitioned from -ename:VK_IMAGE_LAYOUT_UNDEFINED to a valid layout before it is used, or from -ename:VK_IMAGE_LAYOUT_PREINITIALIZED if the memory has been written by the -host. -If any sparse blocks of a sparse image have been made undefined, then only +If any image subresources are made undefined: due to writes to an alias, +then each of those image subresources must: have its layout transitioned +from ename:VK_IMAGE_LAYOUT_UNDEFINED to a valid layout before it is used, or +from ename:VK_IMAGE_LAYOUT_PREINITIALIZED if the memory has been written by +the host. +If any sparse blocks of a sparse image have been made undefined:, then only the image subresources containing them must: be transitioned. Use of an overlapping range by two aliases must: be separated by a memory diff --git a/chapters/shaders.txt b/chapters/shaders.txt index 55fa0ac3..f1713072 100644 --- a/chapters/shaders.txt +++ b/chapters/shaders.txt @@ -199,14 +199,14 @@ simultaneously. Further, invocations of a single shader produced as the result of different commands may: execute simultaneously. The relative execution order of invocations of the same shader type is -undefined. +undefined:. Shader invocations may: complete in a different order than that in which the primitives they originated from were drawn or dispatched by the application. However, fragment shader outputs are written to attachments in <<primrast-order,rasterization order>>. -The relative order of invocations of different shader types is largely -undefined. +The relative execution order of invocations of different shader types is +largely undefined:. However, when invoking a shader whose inputs are generated from a previous pipeline stage, the shader invocations from the previous stage are guaranteed to have executed far enough to generate input values for all @@ -217,10 +217,10 @@ required inputs. == Shader Memory Access Ordering The order in which image or buffer memory is read or written by shaders is -largely undefined. +largely undefined:. For some shader types (vertex, tessellation evaluation, and in some cases, fragment), even the number of shader invocations that may: perform loads and -stores is undefined. +stores is undefined:. In particular, the following rules apply: @@ -230,15 +230,16 @@ In particular, the following rules apply: in those sections. * <<shaders-fragment-execution,Fragment>> shaders will be invoked zero or more times, as defined in that section. - * The relative order of invocations of the same shader type are undefined. + * The relative execution order of invocations of the same shader type is + undefined:. A store issued by a shader when working on primitive B might complete prior to a store for primitive A, even if primitive A is specified prior to primitive B. This applies even to fragment shaders; while fragment shader outputs are always written to the framebuffer in <<primrast-order, rasterization order>>, stores executed by fragment shader invocations are not. - * The relative order of invocations of different shader types is largely - undefined. + * The relative execution order of invocations of different shader types is + largely undefined:. [NOTE] .Note @@ -295,7 +296,7 @@ Reads that are the result of shader loads through a variable decorated with code:Coherent automatically have available writes to the same buffer, buffer view, or image view made visible to them. The order that coherent writes to different locations become available is -undefined, unless enforced by a memory barrier instruction or other memory +undefined:, unless enforced by a memory barrier instruction or other memory dependency. [NOTE] @@ -308,7 +309,7 @@ and visibility for access via other buffers, buffer views, or image views. The built-in atomic memory transaction instructions can: be used to read and write a given memory address atomically. While built-in atomic functions issued by multiple shader invocations are -executed in undefined order relative to each other, these functions perform +executed in undefined: order relative to each other, these functions perform both a read and a write of a memory address and guarantee that no other memory transaction will write to the underlying memory between the read and write. @@ -506,12 +507,12 @@ shader. Each invocation of the tessellation control shader can: read the attributes of any incoming vertices and their associated data. The invocations corresponding to a given patch execute logically in -parallel, with undefined relative execution order. +parallel, with undefined: relative execution order. However, the code:OpControlBarrier instruction can: be used to provide limited control of the execution order by synchronizing invocations within a patch, effectively dividing tessellation control shader execution into a set of phases. -Tessellation control shaders will read undefined values if one invocation +Tessellation control shaders will read undefined: values if one invocation reads a per-vertex or per-patch attribute written by another invocation at any point during the same phase, or if two invocations attempt to write different values to the same per-patch output in a single phase. @@ -620,7 +621,7 @@ for the purposes of evaluating derivatives for use in non-helper fragment shader invocations. Stores and atomics performed by helper invocations must: not have any effect on memory, and values returned by atomic instructions in helper invocations -are undefined. +are undefined:. [[shaders-fragment-earlytest]] @@ -810,8 +811,9 @@ including any helper invocations generated by that primitive. ifdef::VK_NV_compute_shader_derivatives[] A derivative group for a compute shader is a single local workgroup. endif::VK_NV_compute_shader_derivatives[] -Derivatives are undefined for a sampled image instruction if the instruction -is in flow control that is not uniform across the derivative group. +Derivatives are undefined: for a sampled image instruction if the +instruction is in flow control that is not uniform across the derivative +group. ifdef::VK_VERSION_1_1[] [[shaders-subgroup]] diff --git a/chapters/sparsemem.txt b/chapters/sparsemem.txt index 80509d37..a600e88c 100644 --- a/chapters/sparsemem.txt +++ b/chapters/sparsemem.txt @@ -68,7 +68,7 @@ slink:VkPhysicalDeviceFeatures. resource are well defined and behave as if the data bound is populated with all zeros; writes are discarded. When this property is absent, accesses are considered safe, but reads - will return undefined values. + will return undefined: values. ** Requested via the ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT and ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT bits. ** [[features-features-sparseResidency]] Sparse residency support is @@ -199,7 +199,7 @@ implementation: * pname:residencyNonResidentStrict If this property is not present, reads of unbound regions of the image will -return undefined values. +return undefined: values. Both reads and writes are still considered _safe_ and will not affect other resources or populated regions of the image. @@ -228,9 +228,9 @@ unbound regions. Reads and writes to unbound regions will access the implementation-managed memory instead. -Given that reads of unbound regions are undefined in this scenario, -implementations may: use the same physical memory for all unbound regions of -multiple resources within the same process. +Given that the values resulting from reads of unbound regions are undefined: +in this scenario, implementations may: use the same physical memory for all +unbound regions of multiple resources within the same process. **** endif::implementation-guide[] @@ -278,8 +278,7 @@ ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT and ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT alter memory usage and requirements. -[%inline] -image::images/sparseimage.svg[align="center", title="Sparse Image"] +image::images/sparseimage.svg[align="center",title="Sparse Image",opts="{imageopts}"] In the absence of ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT and ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT, each array layer contains a @@ -293,14 +292,12 @@ used sparse blocks. Any bound partially-used-sparse-blocks must: still have their full sparse block size in bytes allocated in memory. -[%inline] -image::images/sparseimage_singlemiptail.svg[align="center", title="Sparse Image with Single Mip Tail"] +image::images/sparseimage_singlemiptail.svg[align="center",title="Sparse Image with Single Mip Tail",opts="{imageopts}"] When ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT is present all array layers will share a single mip tail region. -[%inline] -image::images/sparseimage_alignedmipsize.svg[align="center", title="Sparse Image with Aligned Mip Size"] +image::images/sparseimage_alignedmipsize.svg[align="center",title="Sparse Image with Aligned Mip Size",opts="{imageopts}"] [NOTE] .Note @@ -320,8 +317,7 @@ Only the first [eq]#N# mip levels whose dimensions are an exact multiple of the sparse image block dimensions can: be bound and unbound on a sparse block basis. -[%inline] -image::images/sparseimage_alignedmipsize_singlemiptail.svg[align="center", title="Sparse Image with Aligned Mip Size and Single Mip Tail"] +image::images/sparseimage_alignedmipsize_singlemiptail.svg[align="center",title="Sparse Image with Aligned Mip Size and Single Mip Tail",opts="{imageopts}"] [NOTE] .Note @@ -436,8 +432,7 @@ memory allocation for implementation-private _metadata_ associated with the image. See the figure below: -[%inline] -image::images/sparseimage_multiaspect.svg[align="center",title="Multiple Aspect Sparse Image"] +image::images/sparseimage_multiaspect.svg[align="center",title="Multiple Aspect Sparse Image",opts="{imageopts}"] [NOTE] .Note @@ -488,7 +483,7 @@ memory. Memory dependencies must: be used to separate writes to one alias from reads or writes to another alias. Writes to aliased memory that are not properly guarded against accesses to -different aliases will have undefined results for all accesses to the +different aliases will have undefined: results for all accesses to the aliased memory. Applications that wish to make use of data consistent sparse memory aliasing @@ -566,7 +561,7 @@ Any pages that the application does not bind to memory may: be bound to one Given the following properties: * A process must: not access memory from another process - * Reads return undefined values + * Reads return undefined: values It is sufficient for each host process to allocate these dummy pages and use them for all resources in that process. @@ -1107,7 +1102,7 @@ include::../api/structs/VkSparseImageMemoryRequirements.txt[] * pname:imageMipTailStride is the offset stride between each array-layer's mip tail, if pname:formatProperties.flags does not contain ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT (otherwise the value is - undefined). + undefined:). include::../validity/structs/VkSparseImageMemoryRequirements.txt[] -- @@ -1246,7 +1241,7 @@ It is important to note that freeing a sname:VkDeviceMemory object with fname:vkFreeMemory will not cause resources (or resource regions) bound to the memory object to become unbound. Access to resources that are bound to memory objects that have been freed -will result in undefined behavior, potentially including application +will result in undefined: behavior, potentially including application termination. Implementations must: ensure that no access to physical memory owned by the @@ -1261,7 +1256,7 @@ ename:VK_QUEUE_SPARSE_BINDING_BIT bit. Applications must: use <<synchronization,synchronization primitives>> to guarantee that other queues do not access ranges of memory concurrently with a binding change. -Accessing memory in a range while it is being rebound results in undefined +Accessing memory in a range while it is being rebound results in undefined: behavior. It is valid to access other ranges of the same resource while a bind operation is executing. diff --git a/chapters/synchronization.txt b/chapters/synchronization.txt index 25ba9f51..b171dbee 100644 --- a/chapters/synchronization.txt +++ b/chapters/synchronization.txt @@ -190,7 +190,7 @@ Write-after-read hazards can be solved with just an execution dependency, but read-after-write and write-after-write hazards need appropriate memory dependencies to be included between them. If an application does not include dependencies to solve these hazards, the -results and execution orders of memory accesses are undefined. +results and execution orders of memory accesses are undefined:. ==== @@ -1747,7 +1747,7 @@ Other than these non-deterministic results, behavior is well defined. In particular: * The implementation must: not crash or enter an internally inconsistent -state where future valid Vulkan commands might cause undefined results, +state where future valid Vulkan commands might cause undefined: results, * Timeouts on future wait commands on fences sharing the payload must: be effective. @@ -2477,7 +2477,7 @@ Unlike fences or events, the act of waiting for a semaphore also unsignals that semaphore. If two operations are separately specified to wait for the same semaphore, and there are no other execution dependencies between those operations, -behaviour is undefined. +behaviour is undefined:. An execution dependency must: be present that guarantees that the semaphore unsignal operation for the first of those waits, happens-before the semaphore is signalled again, and before the second unsignal operation. @@ -2645,7 +2645,7 @@ to one or more of the following: * Continuing execution of the violating command or operation as if the semaphore wait completed successfully after an implementation-dependent timeout. - In this case, the state of the payload becomes undefined, and future + In this case, the state of the payload becomes undefined:, and future operations on semaphores sharing the payload will be subject to these same rules. The semaphore must: be destroyed or have its payload replaced by an @@ -3541,7 +3541,8 @@ framebuffer-space>> pipeline stages is feature is not enabled, pname:dstStageMask must: not contain ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT - * If fname:vkCmdPipelineBarrier is called within a render pass instance, + * [[VUID-vkCmdPipelineBarrier-pDependencies-02285]] + If fname:vkCmdPipelineBarrier is called within a render pass instance, the render pass must: have been created with at least one sname:VkSubpassDependency instance in sname:VkRenderPassCreateInfo::pname:pDependencies that expresses a @@ -3553,8 +3554,8 @@ framebuffer-space>> pipeline stages is equal to sname:VkSubpassDependency::pname:dependencyFlags, pname:srcAccessMask member of each each element of pname:pMemoryBarriers and pname:pImageMemoryBarriers contains a subset of the bit values in - sname:VkSubpassDependency::pname:srcAccessMask, and - pname:dstAccessMask member of each element of pname:pMemoryBarriers and + sname:VkSubpassDependency::pname:srcAccessMask, and pname:dstAccessMask + member of each element of pname:pMemoryBarriers and pname:pImageMemoryBarriers contains a subset of the bit values in sname:VkSubpassDependency::pname:dstAccessMask * [[VUID-vkCmdPipelineBarrier-bufferMemoryBarrierCount-01178]] @@ -3998,7 +3999,7 @@ sname:VkImageMemoryBarrier does not match the sample location state last used to render to the image subresource range specified by pname:subresourceRange or if no sname:VkSampleLocationsInfoEXT structure is in the pname:pNext chain of sname:VkImageMemoryBarrier then the contents of -the given image subresource range becomes undefined as if pname:oldLayout +the given image subresource range becomes undefined: as if pname:oldLayout would equal ename:VK_IMAGE_LAYOUT_UNDEFINED. endif::VK_EXT_sample_locations[] @@ -4208,7 +4209,7 @@ endif::VK_EXT_queue_family_foreign[] endif::VK_VERSION_1_1,VK_KHR_external_memory[] If memory dependencies are correctly expressed between uses of such a resource between two queues in different families, but no ownership transfer -is defined, the contents of that resource are undefined for any read +is defined, the contents of that resource are undefined: for any read accesses performed by the second queue family. [NOTE] @@ -4277,9 +4278,9 @@ The acquire operation happens-before the visibility operation. Whilst it is not invalid to provide destination or source access masks for memory barriers used for release or acquire operations, respectively, they have no practical effect. -Access after a release operation has undefined results, and so visibility +Access after a release operation has undefined: results, and so visibility for those accesses has no practical effect. -Similarly, write access before an acquire operation will produce undefined +Similarly, write access before an acquire operation will produce undefined: results for future access, so availability of those writes has no practical use. In an earlier version of the specification, these were required to match on @@ -4312,10 +4313,10 @@ automatically made available. Once a queue family has acquired ownership of a buffer range or image subresource range of an ename:VK_SHARING_MODE_EXCLUSIVE resource, its -contents are undefined to other queue families unless ownership is +contents are undefined: to other queue families unless ownership is transferred. The contents of any portion of another resource which aliases memory that is -bound to the transferred buffer or image subresource range are undefined +bound to the transferred buffer or image subresource range are undefined: after a release or acquire operation. diff --git a/chapters/tessellation.txt b/chapters/tessellation.txt index 63d8570a..333fb2f0 100644 --- a/chapters/tessellation.txt +++ b/chapters/tessellation.txt @@ -89,13 +89,11 @@ The domain space has an upper-left origin. endif::VK_VERSION_1_1,VK_KHR_maintenance2[] [[img-tessellation-topology-ul]] -[%inline] -image::images/tessparamUL.svg[align="center",title="Domain parameterization for tessellation primitive modes (upper-left origin)"] +image::images/tessparamUL.svg[align="center",title="Domain parameterization for tessellation primitive modes (upper-left origin)",opts="{imageopts}"] ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] [[img-tessellation-topology-ll]] -[%inline] -image::images/tessparam.svg[align="center",title="Domain parameterization for tessellation primitive modes (lower-left origin)"] +image::images/tessparam.svg[align="center",title="Domain parameterization for tessellation primitive modes (lower-left origin)",opts="{imageopts}"] endif::VK_VERSION_1_1,VK_KHR_maintenance2[] .Caption @@ -298,8 +296,7 @@ This subdivision process is illustrated in <<img-innertri,Inner Triangle Tessellation>>. [[img-innertri]] -[%inline] -image::images/innertri.svg[align="center",title="Inner Triangle Tessellation"] +image::images/innertri.svg[align="center",title="Inner Triangle Tessellation",opts="{imageopts}"] .Caption **** @@ -409,8 +406,7 @@ This subdivision is illustrated in Figure <<img-innerquad,Inner Quad Tessellation>>. [[img-innerquad]] -[%inline] -image::images/innerquad.svg[align="center",title="Inner Quad Tessellation"] +image::images/innerquad.svg[align="center",title="Inner Quad Tessellation",opts="{imageopts}"] .Caption **** diff --git a/chapters/textures.txt b/chapters/textures.txt index c8a7e325..5ff5ec5b 100644 --- a/chapters/textures.txt +++ b/chapters/textures.txt @@ -130,8 +130,7 @@ n is the sample index and is taken from the code:Sample image operand. For all coordinate types, unused coordinates are assigned a value of zero. [[textures-texel-coordinate-systems-diagrams]] -[%inline] -image::images/vulkantexture0.svg[align="center",title="Texel Coordinate Systems"] +image::images/vulkantexture0.svg[align="center",title="Texel Coordinate Systems",opts="{imageopts}"] The Texel Coordinate Systems - For the example shown of an 8{times}4 texel two dimensional image. @@ -172,8 +171,7 @@ the unnormalized coordinate space of the lower-resolution channels. ==== endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] -[%inline] -image::images/vulkantexture1.svg[align="center",title="Texel Coordinate Systems"] +image::images/vulkantexture1.svg[align="center",title="Texel Coordinate Systems",opts="{imageopts}"] The Texel Coordinate Systems - For the example shown of an 8{times}4 texel two dimensional image. @@ -372,7 +370,7 @@ endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] _Texel input validation operations_ inspect instruction/image/sampler state or coordinates, and in certain circumstances cause the texel value to be -replaced or become undefined. +replaced or become undefined:. There are a series of validations that the texel undergoes. @@ -383,7 +381,7 @@ There are a number of cases where a SPIR-V instruction can: mismatch with the sampler, the image view, or both. There are a number of cases where the sampler can: mismatch with the image view. -In such cases the value of the texel returned is undefined. +In such cases the value of the texel returned is undefined:. These cases include: @@ -582,8 +580,8 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] If all planes of a _disjoint_ _multi-planar_ image are not in the same <<resources-image-layouts,image layout>> when the image is sampled with -<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>>, the result of -texel reads is undefined. +<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>>, the values +returned by texel reads are undefined:. endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] @@ -675,7 +673,7 @@ components in the image format | Four component color format | [eq]#C~rgba~ = (B~r~,B~g~,B~b~,B~a~)# |==== -The value returned by a read of an invalid texel is undefined, unless that +The value returned by a read of an invalid texel is undefined:, unless that read operation is from a buffer resource and the pname:robustBufferAccess feature is enabled. In that case, an invalid texel is replaced as described by the @@ -688,7 +686,7 @@ values for integer and floating-point components of the image format, respectively. If pname:residencyNonResidentStrict is ename:VK_FALSE, the value of the -sparse unbound texel is undefined. +sparse unbound texel is undefined:. [[textures-depth-compare-operation]] @@ -815,7 +813,7 @@ If the border color is one of the etext:VK_BORDER_COLOR_*_OPAQUE_BLACK enums and the elink:VkComponentSwizzle is not ename:VK_COMPONENT_SWIZZLE_IDENTITY for all components (or the <<resources-image-views-identity-mappings,equivalent identity mapping>>), -the value of the texel after swizzle is undefined. +the value of the texel after swizzle is undefined:. [[textures-sparse-residency]] @@ -874,23 +872,17 @@ positions where required for interpolation. The limits of a sample for etext:NEAREST sampling is shown as a grid. ==== -[%inline] -image::images/chromasamples_422_cosited.svg[align="center",title="422 downsampling, xChromaOffset=COSITED_EVEN"] +image::images/chromasamples_422_cosited.svg[align="center",title="422 downsampling, xChromaOffset=COSITED_EVEN",opts="{imageopts}"] -[%inline] -image::images/chromasamples_422_midpoint.svg[align="center",title="422 downsampling, xChromaOffset=MIDPOINT"] +image::images/chromasamples_422_midpoint.svg[align="center",title="422 downsampling, xChromaOffset=MIDPOINT",opts="{imageopts}"] -[%inline] -image::images/chromasamples_420_xcosited_ycosited.svg[align="center",title="420 downsampling, xChromaOffset=COSITED_EVEN, yChromaOffset=COSITED_EVEN"] +image::images/chromasamples_420_xcosited_ycosited.svg[align="center",title="420 downsampling, xChromaOffset=COSITED_EVEN, yChromaOffset=COSITED_EVEN",opts="{imageopts}"] -[%inline] -image::images/chromasamples_420_xmidpoint_ycosited.svg[align="center",title="420 downsampling, xChromaOffset=MIDPOINT, yChromaOffset=COSITED_EVEN"] +image::images/chromasamples_420_xmidpoint_ycosited.svg[align="center",title="420 downsampling, xChromaOffset=MIDPOINT, yChromaOffset=COSITED_EVEN",opts="{imageopts}"] -[%inline] -image::images/chromasamples_420_xcosited_ymidpoint.svg[align="center",title="420 downsampling, xChromaOffset=COSITED_EVEN, yChromaOffset=MIDPOINT"] +image::images/chromasamples_420_xcosited_ymidpoint.svg[align="center",title="420 downsampling, xChromaOffset=COSITED_EVEN, yChromaOffset=MIDPOINT",opts="{imageopts}"] -[%inline] -image::images/chromasamples_420_xmidpoint_ymidpoint.svg[align="center",title="420 downsampling, xChromaOffset=MIDPOINT, yChromaOffset=MIDPOINT"] +image::images/chromasamples_420_xmidpoint_ymidpoint.svg[align="center",title="420 downsampling, xChromaOffset=MIDPOINT, yChromaOffset=MIDPOINT",opts="{imageopts}"] Reconstruction is implemented in one of two ways: @@ -1326,7 +1318,7 @@ Floating-point outputs are converted as described in <<fundamentals-fixedconv,Fixed-Point Data Conversion>>. Integer outputs are converted such that their value is preserved. The converted value of any integer that cannot be represented in the target -format is undefined. +format is undefined:. == Derivative Operations @@ -1339,8 +1331,7 @@ compute and endif::VK_NV_compute_shader_derivatives[] fragment shaders. -[%inline] -image::images/vulkantexture2.svg[align="center",title="Implicit Derivatives"] +image::images/vulkantexture2.svg[align="center",title="Implicit Derivatives",opts="{imageopts}"] Derivatives are computed as if there is a 2{times}2 neighborhood of fragments for each fragment shader invocation. @@ -1499,13 +1490,13 @@ For implicit derivative image instructions, the partial derivative values may: be computed by linear approximation using a 2{times}2 neighborhood of shader invocations (known as a _quad_), as described above. If the instruction is in control flow that is not uniform across the quad, -then the derivative values and hence the implicit LOD values are undefined. +then the derivative values and hence the implicit LOD values are undefined:. ifdef::VK_EXT_descriptor_indexing[] If the image or sampler object used by an implicit derivative image instruction is not uniform across the quad and <<features-limits-quadDivergentImplicitLod,pname:quadDivergentImplicitLod>> -is not supported, then the derivative and LOD values are undefined. +is not supported, then the derivative and LOD values are undefined:. Implicit derivatives are well-defined when the image and sampler and control flow are uniform across the quad, even if they diverge between different quads. @@ -2143,9 +2134,9 @@ d & = level_{base} + If [eq]#d# does not lie in the range [eq]#[pname:baseMipLevel, pname:baseMipLevel {plus} pname:levelCount)# then any values fetched are -ifndef::VK_AMD_shader_image_load_store_lod[undefined.] +ifndef::VK_AMD_shader_image_load_store_lod[undefined:.] ifdef::VK_AMD_shader_image_load_store_lod[] -undefined, and any writes are discarded. +undefined:, and any writes are discarded. endif::VK_AMD_shader_image_load_store_lod[] diff --git a/chapters/vertexpostproc.txt b/chapters/vertexpostproc.txt index 3cee18fc..3220f5f1 100644 --- a/chapters/vertexpostproc.txt +++ b/chapters/vertexpostproc.txt @@ -203,7 +203,7 @@ If a geometry shader is active, the output primitive topology is either points, line strips, or triangle strips, and the selection of the provoking vertex behaves according to the corresponding row of the table. If a tessellation evaluation shader is active and a geometry shader is not -active, the provoking vertex is undefined but must: be one of the vertices +active, the provoking vertex is undefined: but must: be one of the vertices of the primitive. @@ -540,8 +540,8 @@ implementation-dependent vertex of each primitive. If code:ViewportIndex is outside the range zero to pname:viewportCount minus one for a primitive, or if the geometry shader did not assign a value to code:ViewportIndex for all vertices of a primitive due to flow control, the -results of the viewport transformation of the vertices of such primitives -are undefined. +values resulting from the viewport transformation of the vertices of such +primitives are undefined:. If no geometry shader is active, or if the geometry shader does not have an output decorated with code:ViewportIndex, the viewport numbered zero is used by the viewport transformation. @@ -563,8 +563,8 @@ If code:ViewportIndex or any of the bits in code:ViewportMaskNV are outside the range zero to pname:viewportCount minus one for a primitive, or if the last active vertex processing stage did not assign a value to either code:ViewportIndex or code:ViewportMaskNV for all vertices of a primitive -due to flow control, the results of the viewport transformation of the -vertices of such primitives are undefined. +due to flow control, the values resulting from the viewport transformation +of the vertices of such primitives are undefined:. If the last vertex processing stage does not have an output decorated with code:ViewportIndex or code:ViewportMaskNV, the viewport numbered zero is used by the viewport transformation. @@ -582,8 +582,8 @@ primitive. If code:ViewportIndex is outside the range zero to pname:viewportCount minus one for a primitive, or if the last active vertex processing stage did not assign a value to code:ViewportIndex for all vertices of a primitive due to -flow control, the results of the viewport transformation of the vertices of -such primitives are undefined. +flow control, the values resulting from the viewport transformation of the +vertices of such primitives are undefined:. If the last vertex processing stage does not have an output decorated with code:ViewportIndex, the viewport numbered zero is used by the viewport transformation. diff --git a/config/makeSubmit.py b/config/makeSubmit.py index 88ecc771..32cfcf6c 100755 --- a/config/makeSubmit.py +++ b/config/makeSubmit.py @@ -42,6 +42,7 @@ def enQuote(str): def makeTarget(outDir, extensionList, submitName, title, target): print('make clean_generated') print('make OUTDIR=' + outDir, + 'IMAGEOPTS=', 'EXTENSIONS="' + ' '.join(extensionList) + '"', 'APITITLE="' + title + '"', target) # Rename into submission directory diff --git a/config/vulkan-macros.rb b/config/vulkan-macros.rb index f23d7b4b..7bbcdef9 100644 --- a/config/vulkan-macros.rb +++ b/config/vulkan-macros.rb @@ -43,4 +43,5 @@ Asciidoctor::Extensions.register do inline_macro CodeInlineMacro inline_macro AttrInlineMacro inline_macro TagInlineMacro + inline_macro UndefinedInlineMacro end diff --git a/config/vulkan-macros/extension.rb b/config/vulkan-macros/extension.rb index d1779927..0c4ecb1b 100644 --- a/config/vulkan-macros/extension.rb +++ b/config/vulkan-macros/extension.rb @@ -219,3 +219,13 @@ class AttrInlineMacro < StrongInlineMacroBase match /attr:(\w+)/ end +# Does nothing - just markup that we've considered the use case +class UndefinedInlineMacro < VulkanInlineMacroBase + named :undefined + match /undefined:/ + + def process parent, target, attributes + 'undefined' + end +end + diff --git a/copyright-spec.txt b/copyright-spec.txt index 76d60b28..70beafbb 100644 --- a/copyright-spec.txt +++ b/copyright-spec.txt @@ -25,17 +25,17 @@ This Specification has been created under the Khronos Intellectual Property Rights Policy, which is Attachment A of the Khronos Group Membership Agreement available at www.khronos.org/files/member_agreement.pdf, and which defines the terms 'Scope', 'Compliant Portion', and 'Necessary Patent Claims'. -Parties desiring to implement the Specification and make use of Khronos trademarks -in relation to that implementation, and receive reciprocal patent license protection -under the Khronos Intellectual Property Rights Policy must become Adopters and -confirm the implementation as conformant under the process defined by Khronos for +Parties desiring to implement the Specification and make use of Khronos trademarks +in relation to that implementation, and receive reciprocal patent license protection +under the Khronos Intellectual Property Rights Policy must become Adopters and +confirm the implementation as conformant under the process defined by Khronos for this Specification; see https://www.khronos.org/adopters. This Specification contains substantially unmodified functionality from, and is a successor to, Khronos specifications including OpenGL, OpenGL ES and OpenCL. Some parts of this Specification are purely informative and so are EXCLUDED from -the Scope of this Specification. The <<introduction-conventions>> section of the +the Scope of this Specification. The <<introduction-conventions>> section of the <<introduction>> defines how these parts of the Specification are identified. Where this Specification uses <<introduction-technical-terminology,technical @@ -60,8 +60,8 @@ implemented, are considered to be included as Compliant Portions. Where this Specification includes <<introduction-normative-references, normative references to external documents>>, only the specifically identified sections of those external documents are INCLUDED in the Scope of -this Specification. If not created by Khronos, those external documents may -contain contributions from non-members of Khronos not covered by the Khronos +this Specification. If not created by Khronos, those external documents may +contain contributions from non-members of Khronos not covered by the Khronos Intellectual Property Rights Policy. ifndef::ratified_core_spec[] @@ -75,8 +75,9 @@ https://www.khronos.org/registry/vulkan/specs/1.1-khr_extensions/html/vkspec.htm (core with KHR extensions). endif::ratified_core_spec[] -Vulkan is a registered trademark, and Khronos is a trademark of The Khronos -Group Inc. ASTC is a trademark of ARM Holdings PLC; OpenCL is a trademark of -Apple Inc.; and OpenGL is a registered trademark of Silicon Graphics International, -all used under license by Khronos. All other product names, trademarks, and/or -company names are used solely for identification and belong to their respective owners. +Vulkan and Khronos are registered trademarks of The Khronos Group Inc. +ASTC is a trademark of ARM Holdings PLC; OpenCL is a trademark of Apple +Inc.; and OpenGL is a registered trademark of Silicon Graphics +International, all used under license by Khronos. All other product names, +trademarks, and/or company names are used solely for identification and +belong to their respective owners. diff --git a/include/vulkan/vulkan.h b/include/vulkan/vulkan.h index d05c8490..cf9d85ae 100644 --- a/include/vulkan/vulkan.h +++ b/include/vulkan/vulkan.h @@ -24,6 +24,10 @@ #include "vulkan_android.h" #endif +#ifdef VK_USE_PLATFORM_FUCHSIA +#include <zircon/types.h> +#include "vulkan_fuchsia.h" +#endif #ifdef VK_USE_PLATFORM_IOS_MVK #include "vulkan_ios.h" diff --git a/include/vulkan/vulkan_core.h b/include/vulkan/vulkan_core.h index 39f4dc6f..163fb176 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 86 +#define VK_HEADER_VERSION 87 #define VK_NULL_HANDLE 0 @@ -443,6 +443,7 @@ typedef enum VkStructureType { VK_STRUCTURE_TYPE_CHECKPOINT_DATA_NV = 1000206000, VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_NV = 1000206001, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES_KHR = 1000211000, + VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA = 1000214000, VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT, VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES, diff --git a/include/vulkan/vulkan_fuchsia.h b/include/vulkan/vulkan_fuchsia.h new file mode 100644 index 00000000..e0ed5455 --- /dev/null +++ b/include/vulkan/vulkan_fuchsia.h @@ -0,0 +1,58 @@ +#ifndef VULKAN_FUCHSIA_H_ +#define VULKAN_FUCHSIA_H_ 1 + +#ifdef __cplusplus +extern "C" { +#endif + +/* +** Copyright (c) 2015-2018 The Khronos Group Inc. +** +** Licensed under the Apache License, Version 2.0 (the "License"); +** you may not use this file except in compliance with the License. +** You may obtain a copy of the License at +** +** http://www.apache.org/licenses/LICENSE-2.0 +** +** Unless required by applicable law or agreed to in writing, software +** distributed under the License is distributed on an "AS IS" BASIS, +** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +** See the License for the specific language governing permissions and +** limitations under the License. +*/ + +/* +** This header is generated from the Khronos Vulkan XML API Registry. +** +*/ + + +#define VK_FUCHSIA_imagepipe_surface 1 +#define VK_FUCHSIA_IMAGEPIPE_SURFACE_SPEC_VERSION 1 +#define VK_FUCHSIA_IMAGEPIPE_SURFACE_EXTENSION_NAME "VK_FUCHSIA_imagepipe_surface" + +typedef VkFlags VkImagePipeSurfaceCreateFlagsFUCHSIA; + +typedef struct VkImagePipeSurfaceCreateInfoFUCHSIA { + VkStructureType sType; + const void* pNext; + VkImagePipeSurfaceCreateFlagsFUCHSIA flags; + zx_handle_t imagePipeHandle; +} VkImagePipeSurfaceCreateInfoFUCHSIA; + + +typedef VkResult (VKAPI_PTR *PFN_vkCreateImagePipeSurfaceFUCHSIA)(VkInstance instance, const VkImagePipeSurfaceCreateInfoFUCHSIA* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkSurfaceKHR* pSurface); + +#ifndef VK_NO_PROTOTYPES +VKAPI_ATTR VkResult VKAPI_CALL vkCreateImagePipeSurfaceFUCHSIA( + VkInstance instance, + const VkImagePipeSurfaceCreateInfoFUCHSIA* pCreateInfo, + const VkAllocationCallbacks* pAllocator, + VkSurfaceKHR* pSurface); +#endif + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/reflow_count.py b/reflow_count.py index 513b5759..25547668 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 = 2285 +startVUID = 2286 diff --git a/registry.txt b/registry.txt index edca83f4..4cc1d4a4 100644 --- a/registry.txt +++ b/registry.txt @@ -2,7 +2,7 @@ // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ -= The Khronos Vulkan^(R)^ API Registry += The Khronos^®^ Vulkan^®^ API Registry Jon Leech :data-uri: :icons: font @@ -492,12 +492,15 @@ member. generate validation code from the allowed length. * attr:externsync - denotes that the member should be externally synchronized when accessed by Vulkan - * attr:optional - a value of `"true"` or `"false"` determines whether this + * attr:optional - optional. + A value of `"true"` or `"false"` determines whether this member can be omitted by providing `NULL` (for pointers), `VK_NULL_HANDLE` (for handles), 0 (for bitmasks), or 0 for values that are the size of an array in the same structure. If the member is a pointer to one of those types, multiple values may be provided, separated by commas - one for each pointer indirection. + If not present, the value is assumed to be `"false"` (the member must + not be omitted). * attr:noautovalidity - prevents automatic validity language being generated for the tagged item. Only suppresses item-specific validity - parenting issues etc. are still captured. @@ -890,12 +893,14 @@ members. item count in attr:len list. This attribute is intended to support consumers of the XML who need to generate validation code from the allowed length. - * attr:optional - a value of `"true"` or `"false"` determines whether this - member can be omitted by providing `NULL` (for pointers), + * attr:optional - optional. A value of `"true"` or `"false"` determines whether this + parameter can be omitted by providing `NULL` (for pointers), `VK_NULL_HANDLE` (for handles), 0 (for bitmasks), or 0 for values - that are the size of an array in the same command. If the member is + that are the size of an array in the same command. If the parameter is a pointer to one of those types, multiple values may be provided, - separated by commas - one for each pointer indirection. + separated by commas - one for each pointer indirection. If not present, + the value is assumed to be `"false"` (the parameter must not be + omitted). * attr:noautovalidity - prevents automatic validity language being generated for the tagged item. Only suppresses item-specific validity - parenting issues etc. are still captured. @@ -2006,6 +2011,8 @@ files and Python scripts are logged in Github history. [[changelog]] = Change Log + * 2018-10-01 - Add description of the default value of attr:optional + member and parameter attributes, if not specified. * 2018-08-28 - Add optional attr:provisional attribute to tag:extension tags. * 2018-07-07 - Add optional attr:promotedto, attr:deprecatedby, and diff --git a/style/markup.txt b/style/markup.txt index cc1b0347..1ced4d1c 100644 --- a/style/markup.txt +++ b/style/markup.txt @@ -348,17 +348,20 @@ and is added to the list of figures: .Example Markup ---- [[fig-anchorname]] -[%inline] -image::images/imagename.svg[align="center",title="Figure caption",{fullimagewidth}] +image::images/imagename.svg[align="center",title="Figure caption",opts="{imageopts}"] ---- There must be SVG versions of each figure checked into the `images/` directory, to support generating both HTML and PDF outputs. The PDF generation pipeline is now able to use SVG images, so PDF versions of each image are no longer required. -The `[%inline]` directive decreases output image size in the generated HTML. +The `opts=` attribute defaults to `inline`, which decreases output image +size in the generated HTML. +However, the `inline` option interferes with generating HTML diffs between +two specifications with the script we currently use. +By using an asciidoctor attribute, this behavior can be controlled. -Asciidoc restricts captions in figures to be a single line in the source +Asciidoctor restricts captions in figures to be a single line in the source document. If a longer caption is required, follow the figure directive with a sidebar block including the full caption preceded by a link to the figure: diff --git a/style/writing.txt b/style/writing.txt index 36c6b729..4e2759dd 100644 --- a/style/writing.txt +++ b/style/writing.txt @@ -192,6 +192,28 @@ the prefix from the word with a hyphen. This list is not intended to be complete. +[[writing-undefined]] +== Describing Undefined Behavior + +When describing undefined behavior, be clear about what is and is not +defined. + +Do not write "`undefined results`" unless the effect of an operation is +truly completely undefined (up to and including termination of the +application, for example). + +More often, what should be done is to say that the *values* of specified +variables, or the *contents* of specified memory, become undefined or +implementation-defined as a result of such operations. + +Use the undefined{cl} macro to indicate that each use of the term +"`undefined`" has been carefully considered and accurately represents the +degree of undefined behavior allowed. +Any use of the word "`undefined`" without the trailing {cl} is suspect. +Note that this does not translate into visible markup in the output +document; it is simply markup to help track uses of the word. + + [[writing-describing]] == Describing Commands and Parameters diff --git a/styleguide.txt b/styleguide.txt index 2d9a3af0..679d7a9a 100644 --- a/styleguide.txt +++ b/styleguide.txt @@ -2,7 +2,7 @@ // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ -= Vulkan^(R)^ Documentation and Extensions: Procedures and Conventions += Vulkan^®^ Documentation and Extensions: Procedures and Conventions Jon Leech, Tobias Hector :data-uri: :icons: font @@ -31,8 +31,8 @@ include::copyright-ccby.txt[] This document contains required procedures and conventions when writing specifications for new Vulkan APIs, extensions and layers, or related -Khronos documentation such as white papers and tutorials; or contributing to -existing Vulkan specifications. +Khronos^{reg}^ documentation such as white papers and tutorials; or +contributing to existing Vulkan specifications. These are collectively referred to as _Vulkan Documentation_ or just _documentation_ below. The primary focus is the API Specification and API extensions, although all @@ -152,6 +152,9 @@ include::style/vuid.txt[] * 2018-08-13 - Add %inline directive to the <<markup-sample-section-images, Figures>> section (public pull request 734). +* 2018-07-30 - Added a section on <<writing-undefined, Describing Undefined + Behavior>> (as part of the fixes for public issue 379), and describing why + the undefined{cl} macro should always be used. * 2018-07-08 - Remove requirement to explicitly include extension appendices in the <<extensions-documenting-extensions, Changes for New Extensions>> section. diff --git a/vkspec.txt b/vkspec.txt index d47340ae..ed9ff9ce 100644 --- a/vkspec.txt +++ b/vkspec.txt @@ -2,8 +2,8 @@ // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ -= Vulkan^(R)^ {revnumber} - A Specification {apititle} -The Khronos Vulkan Working Group += Vulkan^®^ {revnumber} - A Specification {apititle} +The Khronos^®^ Vulkan Working Group :data-uri: :icons: font :toc2: diff --git a/xml/Makefile b/xml/Makefile index 196fda94..37149063 100644 --- a/xml/Makefile +++ b/xml/Makefile @@ -43,6 +43,7 @@ SRC = ../src # Vulkan platform-specific headers PLATFORM_HEADERS = \ $(VULKAN)/vulkan_android.h \ + $(VULKAN)/vulkan_fuchsia.h \ $(VULKAN)/vulkan_ios.h \ $(VULKAN)/vulkan_macos.h \ $(VULKAN)/vulkan_mir.h \ diff --git a/xml/genvk.py b/xml/genvk.py index 6d7760b5..cdbf9385 100755 --- a/xml/genvk.py +++ b/xml/genvk.py @@ -254,6 +254,7 @@ def makeGenOpts(args): [ 'vulkan_android.h', [ 'VK_KHR_android_surface', 'VK_ANDROID_external_memory_android_hardware_buffer' ], commonSuppressExtensions ], + [ 'vulkan_fuchsia.h', [ 'VK_FUCHSIA_imagepipe_surface'], commonSuppressExtensions ], [ 'vulkan_ios.h', [ 'VK_MVK_ios_surface' ], commonSuppressExtensions ], [ 'vulkan_macos.h', [ 'VK_MVK_macos_surface' ], commonSuppressExtensions ], [ 'vulkan_mir.h', [ 'VK_KHR_mir_surface' ], commonSuppressExtensions ], diff --git a/xml/vk.xml b/xml/vk.xml index 3eb0fe02..cdd66d9f 100644 --- a/xml/vk.xml +++ b/xml/vk.xml @@ -55,6 +55,7 @@ server. <platform name="vi" protect="VK_USE_PLATFORM_VI_NN" comment="Nintendo Vi"/> <platform name="ios" protect="VK_USE_PLATFORM_IOS_MVK" comment="Apple IOS"/> <platform name="macos" protect="VK_USE_PLATFORM_MACOS_MVK" comment="Apple MacOS"/> + <platform name="fuchsia" protect="VK_USE_PLATFORM_FUCHSIA" comment="Fuchsia"/> </platforms> <tags comment="Vulkan vendor/author tags for extensions and layers"> @@ -99,13 +100,14 @@ server. <type category="include" name="wayland-client.h"/> <type category="include" name="windows.h"/> <type category="include" name="xcb/xcb.h"/> + <type category="include" name="zircon/types.h"/> <comment> In the current header structure, each platform's interfaces are confined to a platform-specific header (vulkan_xlib.h, vulkan_win32.h, etc.). These headers are not self-contained, and should not include native headers (X11/Xlib.h, windows.h, etc.). Code should either include vulkan.h after - defining the appropriate VK_USE_PLATFORM_platform_KHR + defining the appropriate VK_USE_PLATFORM_platform macros, or include the required native headers prior to explicitly including the corresponding platform header. @@ -133,6 +135,7 @@ server. <type requires="xcb/xcb.h" name="xcb_connection_t"/> <type requires="xcb/xcb.h" name="xcb_visualid_t"/> <type requires="xcb/xcb.h" name="xcb_window_t"/> + <type requires="zircon/types.h" name="zx_handle_t"/> <type category="define">#define <name>VK_MAKE_VERSION</name>(major, minor, patch) \ (((major) << 22) | ((minor) << 12) | (patch))</type> @@ -147,7 +150,7 @@ server. <type category="define">// Vulkan 1.1 version number #define <name>VK_API_VERSION_1_1</name> <type>VK_MAKE_VERSION</type>(1, 1, 0)// Patch version should always be set to 0</type> <type category="define">// Version of this file -#define <name>VK_HEADER_VERSION</name> 86</type> +#define <name>VK_HEADER_VERSION</name> 87</type> <type category="define"> #define <name>VK_DEFINE_HANDLE</name>(object) typedef struct object##_T* object;</type> @@ -270,6 +273,7 @@ server. <type category="bitmask">typedef <type>VkFlags</type> <name>VkXcbSurfaceCreateFlagsKHR</name>;</type> <type category="bitmask">typedef <type>VkFlags</type> <name>VkIOSSurfaceCreateFlagsMVK</name>;</type> <type category="bitmask">typedef <type>VkFlags</type> <name>VkMacOSSurfaceCreateFlagsMVK</name>;</type> + <type category="bitmask">typedef <type>VkFlags</type> <name>VkImagePipeSurfaceCreateFlagsFUCHSIA</name>;</type> <type requires="VkPeerMemoryFeatureFlagBits" category="bitmask">typedef <type>VkFlags</type> <name>VkPeerMemoryFeatureFlags</name>;</type> <type category="bitmask" name="VkPeerMemoryFeatureFlagsKHR" alias="VkPeerMemoryFeatureFlags"/> <type requires="VkMemoryAllocateFlagBits" category="bitmask">typedef <type>VkFlags</type> <name>VkMemoryAllocateFlags</name>;</type> @@ -1125,7 +1129,7 @@ server. <member values="VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO"><type>VkStructureType</type> <name>sType</name></member> <member>const <type>void</type>* <name>pNext</name></member> <member optional="true"><type>VkPipelineDynamicStateCreateFlags</type> <name>flags</name></member> - <member><type>uint32_t</type> <name>dynamicStateCount</name></member> + <member optional="true"><type>uint32_t</type> <name>dynamicStateCount</name></member> <member len="dynamicStateCount">const <type>VkDynamicState</type>* <name>pDynamicStates</name></member> </type> <type category="struct" name="VkStencilOpState"> @@ -1677,6 +1681,12 @@ server. <member noautovalidity="true"><type>xcb_connection_t</type>* <name>connection</name></member> <member><type>xcb_window_t</type> <name>window</name></member> </type> + <type category="struct" name="VkImagePipeSurfaceCreateInfoFUCHSIA"> + <member values="VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA"><type>VkStructureType</type> <name>sType</name></member> + <member>const <type>void</type>* <name>pNext</name></member> + <member optional="true"><type>VkImagePipeSurfaceCreateFlagsFUCHSIA</type> <name>flags</name></member> + <member><type>zx_handle_t</type> <name>imagePipeHandle</name></member> + </type> <type category="struct" name="VkSurfaceFormatKHR" returnedonly="true"> <member><type>VkFormat</type> <name>format</name><comment>Supported pair of rendering format</comment></member> <member><type>VkColorSpaceKHR</type> <name>colorSpace</name><comment>and color space for the surface</comment></member> @@ -2776,10 +2786,10 @@ server. </type> <type category="struct" name="VkSampleLocationsInfoEXT" structextends="VkImageMemoryBarrier"> <member values="VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT"><type>VkStructureType</type> <name>sType</name></member> - <member>const <type>void</type>* <name>pNext</name></member> - <member><type>VkSampleCountFlagBits</type> <name>sampleLocationsPerPixel</name></member> - <member><type>VkExtent2D</type> <name>sampleLocationGridSize</name></member> - <member><type>uint32_t</type> <name>sampleLocationsCount</name></member> + <member>const <type>void</type>* <name>pNext</name></member> + <member optional="true"><type>VkSampleCountFlagBits</type> <name>sampleLocationsPerPixel</name></member> + <member><type>VkExtent2D</type> <name>sampleLocationGridSize</name></member> + <member optional="true"><type>uint32_t</type> <name>sampleLocationsCount</name></member> <member len="sampleLocationsCount">const <type>VkSampleLocationEXT</type>* <name>pSampleLocations</name></member> </type> <type category="struct" name="VkAttachmentSampleLocationsEXT"> @@ -5837,6 +5847,13 @@ server. <param><type>xcb_connection_t</type>* <name>connection</name></param> <param><type>xcb_visualid_t</type> <name>visual_id</name></param> </command> + <command successcodes="VK_SUCCESS" errorcodes="VK_ERROR_OUT_OF_HOST_MEMORY,VK_ERROR_OUT_OF_DEVICE_MEMORY"> + <proto><type>VkResult</type> <name>vkCreateImagePipeSurfaceFUCHSIA</name></proto> + <param><type>VkInstance</type> <name>instance</name></param> + <param>const <type>VkImagePipeSurfaceCreateInfoFUCHSIA</type>* <name>pCreateInfo</name></param> + <param optional="true">const <type>VkAllocationCallbacks</type>* <name>pAllocator</name></param> + <param><type>VkSurfaceKHR</type>* <name>pSurface</name></param> + </command> <command successcodes="VK_SUCCESS" errorcodes="VK_ERROR_OUT_OF_HOST_MEMORY"> <proto><type>VkResult</type> <name>vkCreateDebugReportCallbackEXT</name></proto> <param><type>VkInstance</type> <name>instance</name></param> @@ -7486,7 +7503,7 @@ server. <command name="vkGetPhysicalDeviceWaylandPresentationSupportKHR"/> </require> </extension> - <extension name="VK_KHR_mir_surface" number="8" type="instance" requires="VK_KHR_surface" platform="mir" author="KHR" contact="Jesse Hall @critsec,Ian Elliott @ianelliottus" supported="vulkan"> + <extension name="VK_KHR_mir_surface" number="8" type="instance" requires="VK_KHR_surface" platform="mir" author="KHR" contact="Jesse Hall @critsec,Ian Elliott @ianelliottus" obsoletedby="" supported="vulkan"> <require> <enum value="4" name="VK_KHR_MIR_SURFACE_SPEC_VERSION"/> <enum value=""VK_KHR_mir_surface"" name="VK_KHR_MIR_SURFACE_EXTENSION_NAME"/> @@ -9743,10 +9760,14 @@ server. <enum value=""VK_KHR_extension_214"" name="VK_KHR_EXTENSION_214_EXTENSION_NAME"/> </require> </extension> - <extension name="VK_GOOGLE_extension_215" number="215" author="GOOGLE" contact="Jesse Hall @critsec" supported="disabled"> + <extension name="VK_FUCHSIA_imagepipe_surface" number="215" type="instance" author="FUCHSIA" requires="VK_KHR_surface" platform="fuchsia" contact="Craig Stout @cdotstout" supported="vulkan"> <require> - <enum value="0" name="VK_KHR_EXTENSION_215_SPEC_VERSION"/> - <enum value=""VK_KHR_extension_215"" name="VK_KHR_EXTENSION_215_EXTENSION_NAME"/> + <enum value="1" name="VK_FUCHSIA_IMAGEPIPE_SURFACE_SPEC_VERSION"/> + <enum value=""VK_FUCHSIA_imagepipe_surface"" name="VK_FUCHSIA_IMAGEPIPE_SURFACE_EXTENSION_NAME"/> + <enum offset="0" extends="VkStructureType" name="VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA"/> + <type name="VkImagePipeSurfaceCreateFlagsFUCHSIA"/> + <type name="VkImagePipeSurfaceCreateInfoFUCHSIA"/> + <command name="vkCreateImagePipeSurfaceFUCHSIA"/> </require> </extension> <extension name="VK_GOOGLE_extension_216" number="216" author="GOOGLE" contact="Jesse Hall @critsec" supported="disabled"> @@ -9883,8 +9904,8 @@ server. </extension> <extension name="VK_KHR_extension_237" number="237" author="KHR" contact="Jesse Hall @critsec" supported="disabled"> <require> - <enum value="0" name="VK_AMD_EXTENSION_237_SPEC_VERSION"/> - <enum value=""VK_KHR_extension_237"" name="VK_AMD_EXTENSION_237_EXTENSION_NAME"/> + <enum value="0" name="VK_KHR_EXTENSION_237_SPEC_VERSION"/> + <enum value=""VK_KHR_extension_237"" name="VK_KHR_EXTENSION_237_EXTENSION_NAME"/> </require> </extension> </extensions>