From 5de77cf663c84cc2edfa355c49319dca0a869eb2 Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Fri, 10 Jun 2016 15:49:54 -0700 Subject: [PATCH] Change log for June 10, 2016 Vulkan 1.0.16 spec update: * Bump API patch number and header version number to 16 for this update. Github Issues: * Clarify that integer border values are meant to be 0/1, and that integer texture lookups are sign-extended in the <> and <> sections (public issue 52). * Add logic to generate spec boilerplate without using the 'git' command-line client, needed when building from a tarball or another source of the Vulkan tree rather than a cloned git repo. Remove boilerplate as part of 'clean' target (public issue 195). * Document that color writes and clears to unused attachments have no effect for slink:VkClearAttachment and elink:VkColorComponentFlagBits (public issue 198). * Fixed flink:vkCmdExecuteCommands validity statement for sname:VkCommandBufferInheritanceInfo::pname:framebuffer. If used, it must match the framebuffer in the current renderpass instance (public issue 226). * Added valid usage language to require for all functions that set dynamic state that the currently bound graphics pipeline has the corresponding dynamic state enabled (public issue 235). Internal Issues: * Clarify for flink:vkEnumerateInstanceExtensionProperties, in the <> section, and in the <> section when functionality should be exposed as an instance extension, as a device extension, or as both (internal issue 109). * Place WorkgroupSize in alphabetical order in the <> section (internal issue 323). * Corrects valid usage in vkEndRenderPass to only affect primary render passes, as secondaries may be entirely within a render pass, and should be able to be ended (previous language disallowed that) (internal issue 338). * Fix relational operator from <= to >= in the <> section (internal issue 343). * Disallow recursion under SPIR-V entry points in the <> section (internal SPIR-V issue 37). Other Commits: * Use standard Python ElementTree package instead of lxml.etree in header / validation layer / include autogeneration from XML, reducing platform dependencies. --- ChangeLog.txt | 58 +++++++++++++++ doc/specs/vulkan/Makefile | 14 +++- doc/specs/vulkan/appendices/glossary.txt | 10 +++ doc/specs/vulkan/appendices/spirvenv.txt | 1 + doc/specs/vulkan/chapters/clears.txt | 10 ++- doc/specs/vulkan/chapters/extensions.txt | 70 +++++++++++++++++++ doc/specs/vulkan/chapters/features.txt | 12 ++-- doc/specs/vulkan/chapters/framebuffer.txt | 4 ++ doc/specs/vulkan/chapters/interfaces.txt | 32 ++++----- doc/specs/vulkan/chapters/shaders.txt | 2 +- doc/specs/vulkan/chapters/textures.txt | 12 +++- .../validity/protos/vkCmdExecuteCommands.txt | 2 +- .../protos/vkCmdSetBlendConstants.txt | 1 + .../validity/protos/vkCmdSetDepthBias.txt | 1 + .../validity/protos/vkCmdSetDepthBounds.txt | 1 + .../validity/protos/vkCmdSetLineWidth.txt | 1 + .../validity/protos/vkCmdSetScissor.txt | 1 + .../protos/vkCmdSetStencilCompareMask.txt | 1 + .../protos/vkCmdSetStencilReference.txt | 1 + .../protos/vkCmdSetStencilWriteMask.txt | 1 + .../validity/protos/vkCmdSetViewport.txt | 1 + .../validity/protos/vkEndCommandBuffer.txt | 2 +- src/spec/README | 16 ++--- src/spec/generator.py | 4 +- src/spec/readme.tex | 3 +- src/spec/reg.py | 32 +++++++-- src/spec/vk.xml | 56 ++++++++++++--- src/vulkan/vulkan.h | 2 +- 28 files changed, 291 insertions(+), 60 deletions(-) diff --git a/ChangeLog.txt b/ChangeLog.txt index 4b2db94810..3ee0ebb4fa 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -694,3 +694,61 @@ Internal Issues: * Update the <> to refer to the correct feature names (internal issue 305). + +----------------------------------------------------- + +Change log for June 10, 2016 Vulkan 1.0.16 spec update: + + * Bump API patch number and header version number to 16 for this + update. + +Github Issues: + + * Clarify that integer border values are meant to be 0/1, and that + integer texture lookups are sign-extended in the + <> and + <> sections (public + issue 52). + * Add logic to generate spec boilerplate without using the 'git' + command-line client, needed when building from a tarball or another + source of the Vulkan tree rather than a cloned git repo. Remove + boilerplate as part of 'clean' target (public issue 195). + * Document that color writes and clears to unused attachments have no + effect for slink:VkClearAttachment and + elink:VkColorComponentFlagBits (public issue 198). + * Fixed flink:vkCmdExecuteCommands validity statement for + sname:VkCommandBufferInheritanceInfo::pname:framebuffer. If used, it + must match the framebuffer in the current renderpass instance + (public issue 226). + * Added valid usage language to require for all functions that set + dynamic state that the currently bound graphics pipeline has the + corresponding dynamic state enabled (public issue 235). + +Internal Issues: + + * Clarify for flink:vkEnumerateInstanceExtensionProperties, in the + <> section, and in the + <> section when functionality should be exposed + as an instance extension, as a device extension, or as both + (internal issue 109). + * Place WorkgroupSize in alphabetical order in the + <> section + (internal issue 323). + * Corrects valid usage in vkEndRenderPass to only affect primary + render passes, as secondaries may be entirely within a render pass, + and should be able to be ended (previous language disallowed that) + (internal issue 338). + * Fix relational operator from <= to >= in the + <> section + (internal issue 343). + * Disallow recursion under SPIR-V entry points in the + <> + section (internal SPIR-V issue 37). + +Other Commits: + + * Use standard Python ElementTree package instead of lxml.etree in + header / validation layer / include autogeneration from XML, + reducing platform dependencies. + diff --git a/doc/specs/vulkan/Makefile b/doc/specs/vulkan/Makefile index 21d9e24458..e01f71e444 100644 --- a/doc/specs/vulkan/Makefile +++ b/doc/specs/vulkan/Makefile @@ -91,7 +91,7 @@ DBLATEXOPTS := $(KEEP) -V -T db2latex -I. -I images -I images/icons -s $(DBLATEX A2XDBLATEXOPTS := --dblatex-opts='$(DBLATEXOPTS)' # Misc. files to clean up (see 'checkinc' target below) -DIRT := +DIRT = $(SPECVERSION) .PHONY: directories @@ -125,7 +125,7 @@ INCLUDES := $(wildcard protos/*.txt structs/*.txt flags/*.txt enums/*.txt funcpo COMMONDOCS := $(CHAPTERS) $(INCLUDES) # A generated included file with the spec version, date, and git commit SPECVERSION = specversion.txt -SPECREVISION = 1.0.15 +SPECREVISION = 1.0.16 SPECREMARK = # Spec targets @@ -173,19 +173,27 @@ $(PDFDIR): $(QUIET)if test ! -d $(PDFDIR) ; then $(MKDIR) $(PDFDIR) ; fi # Generate Asciidoc attributes for spec version / date +GITHEAD := ../../../.git/logs/HEAD +ifeq ($(wildcard $(GITHEAD)),) +# If GITHEAD does not exist, don't include branch info. +$(SPECVERSION): + $(QUIET)echo ":revnumber: $(SPECREVISION)" > $@ + $(QUIET)echo ":revdate: " `date` >> $@ + $(QUIET)echo ":revremark: Git branch information not available" >> $@ +else # Could use `git log -1 --format="%cd"` to get branch commit date # This used to be a dependency in the spec html/chunked/pdf targets, # but that's likely to lead to merge conflicts. Just regenerate # when pushing a new spec for review to the sandbox. # The dependency on HEAD is per the suggestion in # http://neugierig.org/software/blog/2014/11/binary-revisions.html -GITHEAD := ../../../.git/logs/HEAD $(SPECVERSION): $(GITHEAD) $(QUIET)echo ":revnumber: $(SPECREVISION)" > $@ $(QUIET)echo ":revdate: " `date` >> $@ $(QUIET)echo ":revremark: $(SPECREMARK) from git branch:" \ `git symbolic-ref --short HEAD` \ "commit:" `git log -1 --format="%H"` >> $@ +endif styleguide: $(OUTDIR)/styleguide.html diff --git a/doc/specs/vulkan/appendices/glossary.txt b/doc/specs/vulkan/appendices/glossary.txt index 51a8ab3717..73381ac5c6 100644 --- a/doc/specs/vulkan/appendices/glossary.txt +++ b/doc/specs/vulkan/appendices/glossary.txt @@ -210,6 +210,11 @@ Device Memory:: Memory accessible to the device. Represented by a sname:VkDeviceMemory object. +Device-Level Object:: + Logical device objects and their child objects For example, + sname:VkDevice, sname:VkQueue, and sname:VkCommandBuffer objects are + device-level objects. + Device-Local Memory:: Memory that is connected to the device, and may: be more performant for device access than host-local memory. @@ -406,6 +411,11 @@ Instance:: connection to the implementation. Represented by a sname:VkInstance object. +Instance-Level Object:: + High-level Vulkan objects, which are not logical devices, nor children + of logical devices. For example, sname:VkInstance and + sname:VkPhysicalDevice objects are instance-level objects. + Internal Synchronization:: A type of synchronization required of the implementation, where parameters not defined to be externally synchronized may: require diff --git a/doc/specs/vulkan/appendices/spirvenv.txt b/doc/specs/vulkan/appendices/spirvenv.txt index 01830247f8..b2573bd895 100644 --- a/doc/specs/vulkan/appendices/spirvenv.txt +++ b/doc/specs/vulkan/appendices/spirvenv.txt @@ -92,6 +92,7 @@ A SPIR-V module passed to flink:vkCreateShaderModule must: conform to the following rules: * Every entry point must: have no return value and accept no arguments. + * Recursion: The static function-call graph for an entry point must not contain cycles. * The *Logical* addressing model must: be selected. * *Scope* for execution must: be limited to: ** *Workgroup* diff --git a/doc/specs/vulkan/chapters/clears.txt b/doc/specs/vulkan/chapters/clears.txt index 39ff7d81cf..476c188f2c 100644 --- a/doc/specs/vulkan/chapters/clears.txt +++ b/doc/specs/vulkan/chapters/clears.txt @@ -120,12 +120,16 @@ include::../structs/VkClearAttachment.txt[] ename:VK_IMAGE_ASPECT_COLOR_BIT for color attachments, ename:VK_IMAGE_ASPECT_DEPTH_BIT for depth/stencil attachments with a depth component, and ename:VK_IMAGE_ASPECT_STENCIL_BIT for depth/stencil - attachments with a stencil component. + attachments with a stencil component. If the subpass's depth/stencil + attachment is ename:VK_ATTACHMENT_UNUSED, then the clear has no effect. * pname:colorAttachment is only meaningful if ename:VK_IMAGE_ASPECT_COLOR_BIT is set in pname:aspectMask, in which case it is an index to the pname:pColorAttachments array in the slink:VkSubpassDescription structure of the current subpass which - selects the color attachment to clear. + selects the color attachment to clear. If pname:colorAttachment is + ename:VK_ATTACHMENT_UNUSED or is greater than or equal to + sname:VkSubpassDescription::pname:colorAttachmentCount, then the clear has + no effect. * pname:clearValue is the color or depth/stencil value to clear the attachment to, as described in <> below. @@ -133,7 +137,7 @@ No memory barriers are needed between fname:vkCmdClearAttachments and preceding or subsequent draw or attachment clear commands in the same subpass. -The fname:vkCmdClearAttachments commands is not affected by the bound +The fname:vkCmdClearAttachments command is not affected by the bound pipeline state. Attachments can: also be cleared at the beginning of a render pass instance diff --git a/doc/specs/vulkan/chapters/extensions.txt b/doc/specs/vulkan/chapters/extensions.txt index 41e526d8e2..92298c2f47 100644 --- a/doc/specs/vulkan/chapters/extensions.txt +++ b/doc/specs/vulkan/chapters/extensions.txt @@ -189,6 +189,10 @@ To enable an instance extension, the name of the extension should be added to the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo when creating a sname:VkInstance. +Enabling an extension does not change behavior of functionality exposed by +the core Vulkan API or any other extension, other than making valid the use +of the commands, enums and structures defined by that extension. + To query the extensions available to a given physical device, call: include::../protos/vkEnumerateDeviceExtensionProperties.txt[] @@ -231,3 +235,69 @@ include::../structs/VkExtensionProperties.txt[] incremented with backward compatible changes. include::../validity/structs/VkExtensionProperties.txt[] + +[[extended-functionality-instance-extensions-and-devices]] +=== Instance Extensions and Device Extensions + +Because an instance extension can affect the operation of an instance and +any of its child objects, the decision to expose functionality as an instance +extension or as a device extension is not always clear. +This section provides some guidelines and rules for when to expose new +functionality as an instance extension, device extension, or both. + +The decision is influenced by whether extension functionality affects +instance-level objects (e.g. instances and physical devices) and commands, +or device-level objects (e.g. logical devices, queues, and command buffers) +and commands, or both. + +In some cases, the decision is clear: + +* Functionality that is restricted to the instance-level must: be +implemented as an instance extension. +* Functionality that is restricted to the device-level must: be +implemented as an device extension. + +In other cases, the decision is not so clear: + +* Global functionality that affects the entire Vulkan API, including +instance and device-level objects and commands, should: be an instance +extension. +* Device-level functionality that contains physical-device queries, can: be +implemented as an instance extension. +If some part of an instance extension's functionality might not be available +on all physical devices, the extension should: provide a query to determine +which physical devices provide the functionality. +* For a set of global functionality that provides new instance-level and +device-level commands, and can: be enabled for a subset of devices, it is +recommended that the functionality be partitioned across two extensions--one +for the instance-level functionality, and one for the device-specific +functionality. +In this latter case, it is generally recommended that the two extensions have +unique names. + +Examples of instance extensions include: + +* Logging of debug messages by any enabled layers for all Vulkan commands. +* Functionality creating new objects which are direct children of an instance. +* Functionality creating new objects which are direct children of a +physical device and intended to work with any logical device created +from the physical device. +* Functionality adding new instance-level Vulkan commands that do not affect +any device-level commands. + +[NOTE] +.Note +==== +Instance extensions generally require support in the Vulkan loader. +This is especially true for commands that are dispatched from +instances and physical devices. +Additional information about supporting instance-level commands may be found +in the "Vulkan Loader Specification and Architecture Overview" document, +which may be found at the following web page: + +* https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/sdk-1.0.13/loader/LoaderAndLayerInterface.md + +Please see the "Architectural overview of layers and loader" section for +information about how both instance-level and device-level commands are +supported and dispatched. +==== diff --git a/doc/specs/vulkan/chapters/features.txt b/doc/specs/vulkan/chapters/features.txt index 1f25976903..f560103670 100644 --- a/doc/specs/vulkan/chapters/features.txt +++ b/doc/specs/vulkan/chapters/features.txt @@ -3737,24 +3737,24 @@ pname:format, pname:type, and pname:tiling. For ename:VK_IMAGE_TYPE_1D: - * pname:maxExtent.width >= + * pname:maxExtent.width <= slink:VkPhysicalDeviceLimits::pname:maxImageDimension1D * pname:maxExtent.height = 1 * pname:maxExtent.depth = 1 For ename:VK_IMAGE_TYPE_2D: - * pname:maxExtent.width >= + * pname:maxExtent.width <= slink:VkPhysicalDeviceLimits::pname:maxImageDimension2D - * pname:maxExtent.height >= + * pname:maxExtent.height <= slink:VkPhysicalDeviceLimits::pname:maxImageDimension2D * pname:maxExtent.depth = 1 For ename:VK_IMAGE_TYPE_3D: - * pname:maxExtent.width >= + * pname:maxExtent.width <= slink:VkPhysicalDeviceLimits::pname:maxImageDimension3D - * pname:maxExtent.height >= + * pname:maxExtent.height <= slink:VkPhysicalDeviceLimits::pname:maxImageDimension3D - * pname:maxExtent.depth >= + * pname:maxExtent.depth <= slink:VkPhysicalDeviceLimits::pname:maxImageDimension3D diff --git a/doc/specs/vulkan/chapters/framebuffer.txt b/doc/specs/vulkan/chapters/framebuffer.txt index 1ad5a5a66a..eaeabdba0b 100644 --- a/doc/specs/vulkan/chapters/framebuffer.txt +++ b/doc/specs/vulkan/chapters/framebuffer.txt @@ -300,6 +300,10 @@ the resulting latexmath:[$c_s$] values for R, G and B are unmodified. The value of A is never sRGB encoded. That is, the alpha component is always stored in memory as linear. +If the framebuffer color attachment is ename:VK_ATTACHMENT_UNUSED, no writes +are performed through that attachment. Framebuffer color attachments greater +than or equal to sname:VkSubpassDescription::pname:colorAttachmentCount +perform no writes. [[framebuffer-logicop]] == Logical Operations diff --git a/doc/specs/vulkan/chapters/interfaces.txt b/doc/specs/vulkan/chapters/interfaces.txt index 65f9a111f5..9dbe9d1bd7 100644 --- a/doc/specs/vulkan/chapters/interfaces.txt +++ b/doc/specs/vulkan/chapters/interfaces.txt @@ -927,22 +927,6 @@ The code:NumWorkgroups decoration must: be used only within compute shaders. code:NumWorkgroups must: be declared as a three-component vector of 32-bit integers. -code:WorkgroupSize:: - -The code:WorkgroupSize decoration can: be applied to declare an object -representing the dimensions of a local workgroup in a compute shader. If this -is done, it must: be applied to a code:uvec3 specialization constant or a -code:uvec3 constant. -+ -If a specialization constant or a constant is decorated with the -code:WorkgroupSize decoration, this must: take precedence over any execution -mode set for code:LocalSize. -+ -The code:WorkgroupSize decoration must: be used only within compute shaders. -+ -code:WorkgroupSize must: be declared as a three-component vector of 32-bit -integers. - code:PatchVertices:: An input variable decorated with code:PatchVertices in the tessellation @@ -1208,3 +1192,19 @@ The code:WorkgroupId decoration must: be used only within compute shaders. + code:WorkgroupId must: be declared as a three-component vector of 32-bit integers. + +code:WorkgroupSize:: + +The code:WorkgroupSize decoration can: be applied to declare an object +representing the dimensions of a local workgroup in a compute shader. If this +is done, it must: be applied to a code:uvec3 specialization constant or a +code:uvec3 constant. ++ +If a specialization constant or a constant is decorated with the +code:WorkgroupSize decoration, this must: take precedence over any execution +mode set for code:LocalSize. ++ +The code:WorkgroupSize decoration must: be used only within compute shaders. ++ +code:WorkgroupSize must: be declared as a three-component vector of 32-bit +integers. diff --git a/doc/specs/vulkan/chapters/shaders.txt b/doc/specs/vulkan/chapters/shaders.txt index dc59d5d5ee..9de48945d2 100644 --- a/doc/specs/vulkan/chapters/shaders.txt +++ b/doc/specs/vulkan/chapters/shaders.txt @@ -53,7 +53,7 @@ include::../protos/vkCreateShaderModule.txt[] * pname:pAllocator controls host memory allocation as described in the <> chapter. * pname:pShaderModule points to a sname:VkShaderModule handle in which the - resulting render pass object is returned. + resulting shader module object is returned. include::../validity/protos/vkCreateShaderModule.txt[] diff --git a/doc/specs/vulkan/chapters/textures.txt b/doc/specs/vulkan/chapters/textures.txt index 4c2e6cd8f7..ab4eefb2af 100644 --- a/doc/specs/vulkan/chapters/textures.txt +++ b/doc/specs/vulkan/chapters/textures.txt @@ -527,7 +527,8 @@ elink:VkFormat), using the appropriate equations in <>, <>, <>, and -<>. +<>. Signed integer components +smaller than 32 bits are sign-extended. If the image format is sRGB, the color components are first converted as if they are UNORM, and then sRGB to linear conversion is applied to the R, G, @@ -565,6 +566,15 @@ pname:borderColor of the sampler. The border color is: | ename:VK_BORDER_COLOR_INT_OPAQUE_WHITE | latexmath:[$B = (1, 1, 1, 1)$] |==== +[NOTE] +.Note +==== +The names etext:TRANSPARENT_BLACK, etext:OPAQUE_BLACK, and etext:OPAQUE_WHITE +are meant to describe which components are zeros and ones in the vocabulary of +compositing, and are not meant to imply that the numerical value of +etext:WHITE is a saturating value for integers. +==== + This is substituted for the texel value by replacing the number of components in the image format diff --git a/doc/specs/vulkan/validity/protos/vkCmdExecuteCommands.txt b/doc/specs/vulkan/validity/protos/vkCmdExecuteCommands.txt index 1e3efd7bfb..0a642a585d 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdExecuteCommands.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdExecuteCommands.txt @@ -23,7 +23,7 @@ endif::doctype-manpage[] * If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT * If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with sname:VkCommandBufferInheritanceInfo::pname:subpass set to the index of the subpass which the given command buffer will be executed in * If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with a render pass that is compatible with the current render pass - see <> -* If fname:vkCmdExecuteCommands is being called within a render pass instance, and any given element of pname:pCommandBuffers was recorded with sname:VkCommandBufferInheritanceInfo::pname:framebuffer not equal to sname:VK_NULL_HANDLE, that sname:VkFramebuffer must: be compatible with the sname:VkFramebuffer used in the current render pass instance +* If fname:vkCmdExecuteCommands is being called within a render pass instance, and any given element of pname:pCommandBuffers was recorded with sname:VkCommandBufferInheritanceInfo::pname:framebuffer not equal to sname:VK_NULL_HANDLE, that sname:VkFramebuffer must: match the sname:VkFramebuffer used in the current render pass instance * If the <> feature is not enabled, pname:commandBuffer mustnot: have any queries <> * If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query <>, then each element of pname:pCommandBuffers must: have been recorded with sname:VkCommandBufferInheritanceInfo::pname:occlusionQueryEnable set to ename:VK_TRUE * If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query <>, then each element of pname:pCommandBuffers must: have been recorded with sname:VkCommandBufferInheritanceInfo::pname:queryFlags having all bits set that are set for the query diff --git a/doc/specs/vulkan/validity/protos/vkCmdSetBlendConstants.txt b/doc/specs/vulkan/validity/protos/vkCmdSetBlendConstants.txt index 20a74391c2..7a0440643b 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdSetBlendConstants.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdSetBlendConstants.txt @@ -10,6 +10,7 @@ endif::doctype-manpage[] * pname:commandBuffer must: be a valid sname:VkCommandBuffer handle * pname:commandBuffer must: be in the recording state * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations +* The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS dynamic state enabled ifndef::doctype-manpage[] ******************************************************************************** endif::doctype-manpage[] diff --git a/doc/specs/vulkan/validity/protos/vkCmdSetDepthBias.txt b/doc/specs/vulkan/validity/protos/vkCmdSetDepthBias.txt index d12eb1d5a8..383cc3b362 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdSetDepthBias.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdSetDepthBias.txt @@ -10,6 +10,7 @@ endif::doctype-manpage[] * pname:commandBuffer must: be a valid sname:VkCommandBuffer handle * pname:commandBuffer must: be in the recording state * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations +* The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_DEPTH_BIAS dynamic state enabled * If the <> feature is not enabled, pname:depthBiasClamp must: be code:0.0 ifndef::doctype-manpage[] ******************************************************************************** diff --git a/doc/specs/vulkan/validity/protos/vkCmdSetDepthBounds.txt b/doc/specs/vulkan/validity/protos/vkCmdSetDepthBounds.txt index 8100b81eae..8da5b064f6 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdSetDepthBounds.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdSetDepthBounds.txt @@ -10,6 +10,7 @@ endif::doctype-manpage[] * pname:commandBuffer must: be a valid sname:VkCommandBuffer handle * pname:commandBuffer must: be in the recording state * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations +* The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS dynamic state enabled * pname:minDepthBounds must: be between `0.0` and `1.0`, inclusive * pname:maxDepthBounds must: be between `0.0` and `1.0`, inclusive ifndef::doctype-manpage[] diff --git a/doc/specs/vulkan/validity/protos/vkCmdSetLineWidth.txt b/doc/specs/vulkan/validity/protos/vkCmdSetLineWidth.txt index 71d9414f5c..c000a67790 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdSetLineWidth.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdSetLineWidth.txt @@ -10,6 +10,7 @@ endif::doctype-manpage[] * pname:commandBuffer must: be a valid sname:VkCommandBuffer handle * pname:commandBuffer must: be in the recording state * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations +* The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_LINE_WIDTH dynamic state enabled * If the <> feature is not enabled, pname:lineWidth must: be `1.0` ifndef::doctype-manpage[] ******************************************************************************** diff --git a/doc/specs/vulkan/validity/protos/vkCmdSetScissor.txt b/doc/specs/vulkan/validity/protos/vkCmdSetScissor.txt index 59ef56863e..3657a6434e 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdSetScissor.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdSetScissor.txt @@ -12,6 +12,7 @@ endif::doctype-manpage[] * pname:commandBuffer must: be in the recording state * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations * pname:scissorCount must: be greater than `0` +* The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_SCISSOR dynamic state enabled * pname:firstScissor must: be less than sname:VkPhysicalDeviceLimits::pname:maxViewports * The sum of pname:firstScissor and pname:scissorCount must: be between `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive * The pname:x and pname:y members of pname:offset must: be greater than or equal to `0` diff --git a/doc/specs/vulkan/validity/protos/vkCmdSetStencilCompareMask.txt b/doc/specs/vulkan/validity/protos/vkCmdSetStencilCompareMask.txt index 663f440009..41f1cad3d4 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdSetStencilCompareMask.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdSetStencilCompareMask.txt @@ -12,6 +12,7 @@ endif::doctype-manpage[] * pname:faceMask mustnot: be `0` * pname:commandBuffer must: be in the recording state * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations +* The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK dynamic state enabled ifndef::doctype-manpage[] ******************************************************************************** endif::doctype-manpage[] diff --git a/doc/specs/vulkan/validity/protos/vkCmdSetStencilReference.txt b/doc/specs/vulkan/validity/protos/vkCmdSetStencilReference.txt index 663f440009..a3903cbc7e 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdSetStencilReference.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdSetStencilReference.txt @@ -12,6 +12,7 @@ endif::doctype-manpage[] * pname:faceMask mustnot: be `0` * pname:commandBuffer must: be in the recording state * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations +* The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled ifndef::doctype-manpage[] ******************************************************************************** endif::doctype-manpage[] diff --git a/doc/specs/vulkan/validity/protos/vkCmdSetStencilWriteMask.txt b/doc/specs/vulkan/validity/protos/vkCmdSetStencilWriteMask.txt index 663f440009..414e524743 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdSetStencilWriteMask.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdSetStencilWriteMask.txt @@ -12,6 +12,7 @@ endif::doctype-manpage[] * pname:faceMask mustnot: be `0` * pname:commandBuffer must: be in the recording state * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations +* The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK dynamic state enabled ifndef::doctype-manpage[] ******************************************************************************** endif::doctype-manpage[] diff --git a/doc/specs/vulkan/validity/protos/vkCmdSetViewport.txt b/doc/specs/vulkan/validity/protos/vkCmdSetViewport.txt index eac2be8dcd..7ecca35e86 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdSetViewport.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdSetViewport.txt @@ -12,6 +12,7 @@ endif::doctype-manpage[] * pname:commandBuffer must: be in the recording state * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations * pname:viewportCount must: be greater than `0` +* The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_VIEWPORT dynamic state enabled * pname:firstViewport must: be less than sname:VkPhysicalDeviceLimits::pname:maxViewports * The sum of pname:firstViewport and pname:viewportCount must: be between `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive ifndef::doctype-manpage[] diff --git a/doc/specs/vulkan/validity/protos/vkEndCommandBuffer.txt b/doc/specs/vulkan/validity/protos/vkEndCommandBuffer.txt index 277cc0d97b..6c9a4cdc18 100644 --- a/doc/specs/vulkan/validity/protos/vkEndCommandBuffer.txt +++ b/doc/specs/vulkan/validity/protos/vkEndCommandBuffer.txt @@ -9,7 +9,7 @@ Valid Usage endif::doctype-manpage[] * pname:commandBuffer must: be a valid sname:VkCommandBuffer handle * pname:commandBuffer must: be in the recording state -* fname:vkEndCommandBuffer mustnot: be called inside a render pass instance +* If pname:commandBuffer is a primary command buffer, there mustnot: be an active render pass instance * All queries made <> during the recording of pname:commandBuffer must: have been made inactive ifndef::doctype-manpage[] ******************************************************************************** diff --git a/src/spec/README b/src/spec/README index f34133b098..d7ce75d946 100644 --- a/src/spec/README +++ b/src/spec/README @@ -29,8 +29,8 @@ When patches to the header or the includes are needed, follow this workflow: See 'readme.pdf' for a detailed description of the schema, and some examples of how to make simple changes in the API via the XML. -The generator scripts are written in Python 3, using the very nice -lxml.etree package for processing XML. +The generator scripts are written in Python 3, using the etree package for +processing XML. Jon Leech @@ -93,7 +93,7 @@ environment. Earlier versions *may* work but unless they are verified by someone else, there's no way to know that: - Python 3 (python3, version: 3.4.2) - - Python 3 version of lxml package (python3-lxml, version: 3.4.0-1) + - libxml2 - g++/gcc 4.9 (g++-4.9 / gcc-4.9, version: 4.9.2-10 - gcc 4.8 also reported to work, just needs to support the -std=c++11 target) - GNU make (make version: 4.0.8-1; older versions probably OK) @@ -107,11 +107,7 @@ RUNNING ON WINDOWS 1) Install python (32-bit works great): https://www.python.org/downloads/ a) Ensure the pip module is installed (should be by default) -2) Download the lxml package from - http://www.lfd.uci.edu/~gohlke/pythonlibs/#lxml - a) 32-bit latest is: lxml-3.4.4-cp34-none-win32.whl -3) Install the lxml package: - C:\PathToPython\python.exe pip install c:\PathToDownload\lxml-3.4.4-cp34-none-win32.whl +2) Install libxml2 (instructions TBD...) 4) Run the genvk.py script in C:\PathToVulkan\src\specfile : a) C:\PathToPython\python.exe genvk.py vulkan.h @@ -173,3 +169,7 @@ CHANGE LOG 2016/02/12 Update README and remove old files to stage for public release. + +2016/05/31 + + Remove dependency on lxml. diff --git a/src/spec/generator.py b/src/spec/generator.py index e68bb25c4e..be88e88c60 100644 --- a/src/spec/generator.py +++ b/src/spec/generator.py @@ -23,7 +23,7 @@ def write( *args, **kwargs ): file.write( end ) # noneStr - returns string argument, or "" if argument is None. -# Used in converting lxml Elements into text. +# Used in converting etree Elements into text. # str - string to convert def noneStr(str): if (str): @@ -525,7 +525,7 @@ def makeCDecls(self, cmd): # For typedefs, add (APIENTRY *) around the name and # use the PFN_cmdnameproc naming convention. # Done by walking the tree for element by element. - # lxml.etree has elem.text followed by (elem[i], elem[i].tail) + # etree has elem.text followed by (elem[i], elem[i].tail) # for each child element and any following text # Leading text pdecl += noneStr(proto.text) diff --git a/src/spec/readme.tex b/src/spec/readme.tex index 409efef661..3bf080000d 100644 --- a/src/spec/readme.tex +++ b/src/spec/readme.tex @@ -71,7 +71,7 @@ \section{Introduction} The registry uses an XML representation of the Vulkan API, together with a set of Python scripts to manipulate the registry once loaded. The scripts -rely on the lxml Python bindings to parse and operate on XML. An XML schema +rely on the Python etree package to parse and operate on XML. An XML schema and validator target are included. The schema is based on, but not identical to that used for the previously @@ -126,7 +126,6 @@ \section{Getting Started} \begin{itemize} \item Python 3.x (\code{python3}) -\item The lxml Python package (\code{python3-lxml}) \item Libxml (\code{libxml2}) \item A make tool, such as GNU make \end{itemize} diff --git a/src/spec/reg.py b/src/spec/reg.py index 3ecbd897ef..0a63783a94 100755 --- a/src/spec/reg.py +++ b/src/spec/reg.py @@ -15,7 +15,7 @@ # limitations under the License. import io,os,re,string,sys,copy -from lxml import etree +import xml.etree.ElementTree as etree # matchAPIProfile - returns whether an API and profile # being generated matches an element's profile @@ -70,7 +70,7 @@ def matchAPIProfile(api, profile, elem): # required - should this feature be defined during header generation # (has it been removed by a profile or version)? # declared - has this feature been defined already? -# elem - lxml.etree Element for this feature +# elem - etree Element for this feature # resetState() - reset required/declared to initial values. Used # prior to generating a new API interface. class BaseInfo: @@ -328,10 +328,23 @@ def parseTree(self): # Add additional enums defined only in tags # to the corresponding core type. - # When seen here, a copy, processed to contain the numeric enum - # value, is added to the corresponding element, as well - # as adding to the enum dictionary. Also add a 'extnumber' - # attribute containing the extension number. + # When seen here, the element, processed to contain the + # numeric enum value, is added to the corresponding + # element, as well as adding to the enum dictionary. It is + # *removed* from the element it is introduced in. + # Not doing this will cause spurious genEnum() + # calls to be made in output generation, and it's easier + # to handle here than in genEnum(). + # + # In lxml.etree, an Element can have only one parent, so the + # append() operation also removes the element. But in Python's + # ElementTree package, an Element can have multiple parents. So + # it must be explicitly removed from the tag, leading + # to the nested loop traversal of / elements + # below. + # + # This code also adds a 'extnumber' attribute containing the + # extension number, used for enumerant value calculation. # # For tags which are actually just constants, if there's # no 'extends' tag but there is a 'value' or 'bitpos' tag, just @@ -342,7 +355,9 @@ def parseTree(self): # Something like this will need to be done for 'feature's up # above, if we use the same mechanism for adding to the core # API in 1.1. - for enum in feature.findall('require/enum'): + # + for elem in feature.findall('require'): + for enum in elem.findall('enum'): addEnumInfo = False groupName = enum.get('extends') if (groupName != None): @@ -358,6 +373,9 @@ def parseTree(self): # groupName, 'found, adding element...') gi = self.groupdict[groupName] gi.elem.append(enum) + # Remove element from parent tag + # This should be a no-op in lxml.etree + elem.remove(enum) else: self.gen.logMsg('warn', '*** NO matching group', groupName, 'for enum', enum.get('name'), 'found.') diff --git a/src/spec/vk.xml b/src/spec/vk.xml index 270a4cfd50..45bdeb1cdf 100644 --- a/src/spec/vk.xml +++ b/src/spec/vk.xml @@ -101,7 +101,7 @@ maintained in the master branch of the Khronos Vulkan Github project. // Vulkan 1.0 version number #define VK_API_VERSION_1_0 VK_MAKE_VERSION(1, 0, 0) // Version of this file -#define VK_HEADER_VERSION 15 +#define VK_HEADER_VERSION 16 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; @@ -3790,7 +3790,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkCommandBuffer commandBuffer pname:commandBuffer must: be in the recording state - fname:vkEndCommandBuffer mustnot: be called inside a render pass instance + If pname:commandBuffer is a primary command buffer, there mustnot: be an active render pass instance All queries made <<queries-operation-active,active>> during the recording of pname:commandBuffer must: have been made inactive @@ -3823,6 +3823,7 @@ maintained in the master branch of the Khronos Vulkan Github project. uint32_t viewportCount const VkViewport* pViewports + The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_VIEWPORT dynamic state enabled pname:firstViewport must: be less than sname:VkPhysicalDeviceLimits::pname:maxViewports The sum of pname:firstViewport and pname:viewportCount must: be between `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive @@ -3834,6 +3835,7 @@ maintained in the master branch of the Khronos Vulkan Github project. uint32_t scissorCount const VkRect2D* pScissors + The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_SCISSOR dynamic state enabled pname:firstScissor must: be less than sname:VkPhysicalDeviceLimits::pname:maxViewports The sum of pname:firstScissor and pname:scissorCount must: be between `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive The pname:x and pname:y members of pname:offset must: be greater than or equal to `0` @@ -3846,6 +3848,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkCommandBuffer commandBuffer float lineWidth + The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_LINE_WIDTH dynamic state enabled If the <<features-features-wideLines,wide lines>> feature is not enabled, pname:lineWidth must: be `1.0` @@ -3856,6 +3859,7 @@ maintained in the master branch of the Khronos Vulkan Github project. float depthBiasClamp float depthBiasSlopeFactor + The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_DEPTH_BIAS dynamic state enabled If the <<features-features-depthBiasClamp,depth bias clamping>> feature is not enabled, pname:depthBiasClamp must: be code:0.0 @@ -3863,6 +3867,9 @@ maintained in the master branch of the Khronos Vulkan Github project. void vkCmdSetBlendConstants VkCommandBuffer commandBuffer const float blendConstants[4] + + The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS dynamic state enabled + void vkCmdSetDepthBounds @@ -3870,6 +3877,7 @@ maintained in the master branch of the Khronos Vulkan Github project. float minDepthBounds float maxDepthBounds + The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS dynamic state enabled pname:minDepthBounds must: be between `0.0` and `1.0`, inclusive pname:maxDepthBounds must: be between `0.0` and `1.0`, inclusive @@ -3879,18 +3887,27 @@ maintained in the master branch of the Khronos Vulkan Github project. VkCommandBuffer commandBuffer VkStencilFaceFlags faceMask uint32_t compareMask + + The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK dynamic state enabled + void vkCmdSetStencilWriteMask VkCommandBuffer commandBuffer VkStencilFaceFlags faceMask uint32_t writeMask + + The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK dynamic state enabled + void vkCmdSetStencilReference VkCommandBuffer commandBuffer VkStencilFaceFlags faceMask uint32_t reference + + The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled + void vkCmdBindDescriptorSets @@ -4466,14 +4483,14 @@ maintained in the master branch of the Khronos Vulkan Github project. VkCommandBuffer commandBuffer VkSubpassContents contents - The current subpass index must: be less than the number of subpasses in the render pass minus one + The current subpass index must: be less than the number of subpasses in the render pass minus one void vkCmdEndRenderPass VkCommandBuffer commandBuffer - The current subpass index must: be equal to the number of subpasses in the render pass minus one + The current subpass index must: be equal to the number of subpasses in the render pass minus one @@ -4491,7 +4508,7 @@ maintained in the master branch of the Khronos Vulkan Github project. If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with sname:VkCommandBufferInheritanceInfo::pname:subpass set to the index of the subpass which the given command buffer will be executed in If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with a render pass that is compatible with the current render pass - see <<renderpass-compatibility>> - If fname:vkCmdExecuteCommands is being called within a render pass instance, and any given element of pname:pCommandBuffers was recorded with sname:VkCommandBufferInheritanceInfo::pname:framebuffer not equal to sname:VK_NULL_HANDLE, that sname:VkFramebuffer must: be compatible with the sname:VkFramebuffer used in the current render pass instance + If fname:vkCmdExecuteCommands is being called within a render pass instance, and any given element of pname:pCommandBuffers was recorded with sname:VkCommandBufferInheritanceInfo::pname:framebuffer not equal to sname:VK_NULL_HANDLE, that sname:VkFramebuffer must: match the sname:VkFramebuffer used in the current render pass instance If the <<features-features-inheritedQueries,inherited queries>> feature is not enabled, pname:commandBuffer mustnot: have any queries <<queries-operation-active,active>> If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query <<queries-operation-active,active>>, then each element of pname:pCommandBuffers must: have been recorded with sname:VkCommandBufferInheritanceInfo::pname:occlusionQueryEnable set to ename:VK_TRUE If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query <<queries-operation-active,active>>, then each element of pname:pCommandBuffers must: have been recorded with sname:VkCommandBufferInheritanceInfo::pname:queryFlags having all bits set that are set for the query @@ -4795,9 +4812,8 @@ maintained in the master branch of the Khronos Vulkan Github project. void vkCmdDebugMarkerEndEXT VkCommandBuffer commandBuffer - There must: be an outstanding flink:vkCmdDebugMarkerBeginEXT command prior to the fname:vkCmdDebugMarkerEndEXT on the queue that pname:commandBuffer is submitted to. - If the matching flink:vkCmdDebugMarkerBeginEXT command was in a secondary command buffer, the fname:vkCmdDebugMarkerEndEXT must be in the same pname:commandBuffer. - + There must: be an outstanding flink:vkCmdDebugMarkerBeginEXT command prior to the fname:vkCmdDebugMarkerEndEXT on the queue that pname:commandBuffer is submitted to. + If the matching flink:vkCmdDebugMarkerBeginEXT command was in a secondary command buffer, the fname:vkCmdDebugMarkerEndEXT must be in the same pname:commandBuffer. @@ -5313,5 +5329,29 @@ maintained in the master branch of the Khronos Vulkan Github project. + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/vulkan/vulkan.h b/src/vulkan/vulkan.h index 26591ee9db..75afd4a78d 100644 --- a/src/vulkan/vulkan.h +++ b/src/vulkan/vulkan.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 15 +#define VK_HEADER_VERSION 16 #define VK_NULL_HANDLE 0