diff --git a/ChangeLog.txt b/ChangeLog.txt index ebb29146..026825d6 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -1738,3 +1738,30 @@ Internal Issues: flink:vkGetPhysicalDeviceImageFormatProperties would return ename:VK_SUCCESS for the requested image configuration (internal issue 598). + +----------------------------------------------------- + +Change log for December 16, 2016 Vulkan 1.0.38 spec update: + + * Bump API patch number and header version number to 38 for this update. + +Github Issues: + + * Make ename:VK_PIPELINE_STAGE_HOST_BIT invalid for all stage masks, + except for flink:vkCmdWaitEvents (public issue 261). + +Internal Issues: + + * Added validation language for flink:vkQueueBindSparse, + slink:VkPresentInfoKHR, and slink:VkSubmitInfo, and a note to the + <> + section to clarify that semaphores must be signaled and waited on in a + 1:1 fashion (internal issue 546). + * Modify valid usage for slink:VkBufferImageCopy to only require + pname:bufferOffset to be a multiple of the image format's element size + when the format is not depth/stencil (internal issue 594). + +Other Issues: + + * Vulkan(R) is now a registered trademark symbol, and this is reflected in + documents and copyright statements. diff --git a/README.md b/README.md index 56417fb7..cc89ea65 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -Vulkan API Documentation Project -================================ +Vulkan^(R)^ API Documentation Project +===================================== This repository contains formal documentation of the Vulkan API. This includes the main API Specification, the reference (man) pages, the XML API diff --git a/doc/specs/vulkan/Makefile b/doc/specs/vulkan/Makefile index 8b1d3ea0..1be617c6 100644 --- a/doc/specs/vulkan/Makefile +++ b/doc/specs/vulkan/Makefile @@ -160,7 +160,7 @@ GENDEPENDS = api/timeMarker validity/timeMarker hostsynctable/timeMarker COMMONDOCS = $(CHAPTERS) $(GENINCLUDE) $(GENDEPENDS) # A generated included file containing the spec version, date, and git commit SPECVERSION = specversion.txt -SPECREVISION = 1.0.37 +SPECREVISION = 1.0.38 SPECREMARK = # Spec targets diff --git a/doc/specs/vulkan/README.adoc b/doc/specs/vulkan/README.adoc index 0d96cd6d..b7b072c7 100644 --- a/doc/specs/vulkan/README.adoc +++ b/doc/specs/vulkan/README.adoc @@ -1,4 +1,4 @@ -= Vulkan Specification Build Instructions and Notes = += Vulkan^(R)^ Specification Build Instructions and Notes = * <> * <> diff --git a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt index f337bd97..dce8c6b0 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt @@ -656,6 +656,13 @@ ifdef::VK_KHR_display_swapchain[] surface, all display surfaces referenced that refer to the same display must: use the same display mode endif::VK_KHR_display_swapchain[] + * When a semaphore unsignal operation defined by the elements of the + pname:pWaitSemaphores member of pname:pPresentInfo executes on + pname:queue, no other queue must: be waiting on the same semaphore. + * All elements of elements of the pname:pWaitSemaphores member of + pname:pPresentInfo must: be semaphores that are signaled, or have + <> + previously submitted for execution. **** Any writes to memory backing the images referenced by the @@ -707,9 +714,6 @@ include::../../api/structs/VkPresentInfoKHR.txt[] corresponding element of the pname:pSwapchains array, and the presented image subresource must: be in the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout at the time the operation is executed on a sname:VkDevice - * Any given element of sname:VkSemaphore in pname:pWaitSemaphores must: - refer to a prior signal of that sname:VkSemaphore that will not be - consumed by any other wait on that semaphore **** include::../../validity/structs/VkPresentInfoKHR.txt[] diff --git a/doc/specs/vulkan/chapters/cmdbuffers.txt b/doc/specs/vulkan/chapters/cmdbuffers.txt index bb508540..befa50a5 100644 --- a/doc/specs/vulkan/chapters/cmdbuffers.txt +++ b/doc/specs/vulkan/chapters/cmdbuffers.txt @@ -617,6 +617,16 @@ operation>> section of <>. supported by one of the capabilities of pname:queue, as specified in the <>. + * Any given element of the pname:pSignalSemaphores member of any element + of pname:pSubmits must: be unsignaled when the semaphore signal + operation it defines is executed on the device + * When a semaphore unsignal operation defined by any element of the + pname:pWaitSemaphores member of any element of pname:pSubmits executes + on pname:queue, no other queue must: be waiting on the same semaphore. + * All elements of the pname:pWaitSemaphores member of all elements of + pname:pSubmits must: be semaphores that are signaled, or have + <> + previously submitted for execution. **** include::../validity/protos/vkQueueSubmit.txt[] @@ -654,8 +664,6 @@ include::../api/structs/VkSubmitInfo.txt[] .Valid Usage **** - * Any given element of pname:pSignalSemaphores must: currently be - unsignaled * Any given element of pname:pCommandBuffers must: either have been recorded with the ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, or not currently be executing on the device @@ -683,9 +691,6 @@ include::../api/structs/VkSubmitInfo.txt[] that the calling command's pname:queue belongs to * Any given element of pname:pCommandBuffers must: not have been allocated with ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY - * Any given element of sname:VkSemaphore in pname:pWaitSemaphores must: - refer to a prior signal of that sname:VkSemaphore that will not be - consumed by any other wait on that semaphore * If the <> feature is not enabled, any given element of pname:pWaitDstStageMask must: not contain ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT @@ -694,6 +699,8 @@ include::../api/structs/VkSubmitInfo.txt[] must: not contain ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT + * Any given element of pname:pWaitDstStageMask must: not include + ename:VK_PIPELINE_STAGE_HOST_BIT. **** include::../validity/structs/VkSubmitInfo.txt[] diff --git a/doc/specs/vulkan/chapters/copies.txt b/doc/specs/vulkan/chapters/copies.txt index c480505e..58c706c1 100644 --- a/doc/specs/vulkan/chapters/copies.txt +++ b/doc/specs/vulkan/chapters/copies.txt @@ -552,8 +552,9 @@ destination image. .Valid Usage **** - * pname:bufferOffset must: be a multiple of the calling command's - sname:VkImage parameter's format's element size + * If the the calling command's sname:VkImage parameter's format is not a + depth/stencil format, then pname:bufferOffset must: be a multiple of the + format's element size * pname:bufferOffset must: be a multiple of `4` * pname:bufferRowLength must: be `0`, or greater than or equal to the pname:width member of pname:imageExtent diff --git a/doc/specs/vulkan/chapters/renderpass.txt b/doc/specs/vulkan/chapters/renderpass.txt index ff2fb83d..6fd31e69 100644 --- a/doc/specs/vulkan/chapters/renderpass.txt +++ b/doc/specs/vulkan/chapters/renderpass.txt @@ -605,6 +605,10 @@ render pass. .Valid Usage **** + * If pname:srcSubpass is not ename:VK_SUBPASS_EXTERNAL, pname:srcStageMask + must: not include ename:VK_PIPELINE_STAGE_HOST_BIT + * If pname:dstSubpass is not ename:VK_SUBPASS_EXTERNAL, pname:dstStageMask + must: not include ename:VK_PIPELINE_STAGE_HOST_BIT * If the <> feature is not enabled, pname:srcStageMask must: not contain ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT diff --git a/doc/specs/vulkan/chapters/sparsemem.txt b/doc/specs/vulkan/chapters/sparsemem.txt index 0b592ec8..6a852122 100644 --- a/doc/specs/vulkan/chapters/sparsemem.txt +++ b/doc/specs/vulkan/chapters/sparsemem.txt @@ -1371,9 +1371,21 @@ Additional information about fence and semaphore operation is described in .Valid Usage **** - * pname:fence must: be unsignaled - * pname:fence must: not be associated with any other queue command that - has not yet completed execution on that queue + * If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be + unsignaled + * If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be + associated with any other queue command that has not yet completed + execution on that queue + * Any given element of the pname:pSignalSemaphores member of any element + of pname:pBindInfo must: be unsignaled when the semaphore signal + operation it defines is executed on the device + * When a semaphore unsignal operation defined by any element of the + pname:pWaitSemaphores member of any element of pname:pBindInfo executes + on pname:queue, no other queue must: be waiting on the same semaphore. + * All elements of the pname:pWaitSemaphores member of all elements of + pname:pBindInfo must: be semaphores that are signaled, or have + <> + previously submitted for execution. **** include::../validity/protos/vkQueueBindSparse.txt[] diff --git a/doc/specs/vulkan/chapters/synchronization.txt b/doc/specs/vulkan/chapters/synchronization.txt index 819386a7..c3e0a138 100644 --- a/doc/specs/vulkan/chapters/synchronization.txt +++ b/doc/specs/vulkan/chapters/synchronization.txt @@ -318,7 +318,7 @@ endif::VK_NVX_device_generated_commands[] where operations generated by all commands complete execution. * ename:VK_PIPELINE_STAGE_HOST_BIT: A pseudo-stage indicating execution on the host of reads/writes of device memory. - This stage is not invoked by any action commands. + This stage is not invoked by any commands recorded in a command buffer. * ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT: Execution of all graphics pipeline stages. Equivalent to the logical or of: @@ -1083,6 +1083,20 @@ The semaphore unsignal operation happens-after the first set of operations in the execution dependency, and happens-before the second set of operations in the execution dependency. +.Note +[NOTE] +==== +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. +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. +Semaphore waits and signals should thus occur in discrete 1:1 pairs. +==== + ifdef::VK_KHR_swapchain[] .Note [NOTE] @@ -1319,6 +1333,7 @@ signal operation occurs, and no execution dependency is generated. .Valid Usage **** + * pname:stageMask must: not include ename:VK_PIPELINE_STAGE_HOST_BIT * If the <> feature is not enabled, pname:stageMask must: not contain ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT @@ -1363,6 +1378,7 @@ event unsignal operation occurs, and no execution dependency is generated. .Valid Usage **** + * pname:stageMask must: not include ename:VK_PIPELINE_STAGE_HOST_BIT * If the <> feature is not enabled, pname:stageMask must: not contain ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT diff --git a/doc/specs/vulkan/copyright-spec.txt b/doc/specs/vulkan/copyright-spec.txt index e2eea321..4cd0d7ea 100644 --- a/doc/specs/vulkan/copyright-spec.txt +++ b/doc/specs/vulkan/copyright-spec.txt @@ -22,32 +22,32 @@ to the current version of this specification on the Khronos Group web-site shoul be included whenever possible with specification distributions. 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. This specification contains substantially -unmodified functionality from, and is a successor to, Khronos specifications including +which is Attachment A of the Khronos Group Membership Agreement available at +www.khronos.org/files/member_agreement.pdf. 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 do not define requirements -necessary for compliance and so are outside the Scope of this Specification. These -parts of the Specification are marked by the “Note” icon or designated “Informative”. +Some parts of this Specification are purely informative and do not define requirements +necessary for compliance and so are outside the Scope of this Specification. These +parts of the Specification are marked by the ``Note'' icon or designated ``Informative''. -Where this Specification uses terms, defined in the Glossary or otherwise, that refer to -enabling technologies that are not expressly set forth as being required for compliance, +Where this Specification uses terms, defined in the Glossary or otherwise, that refer to +enabling technologies that are not expressly set forth as being required for compliance, those enabling technologies are outside the Scope of this Specification. -Where this Specification uses the terms “may”, or “optional”, such features or -behaviors do not define requirements necessary for compliance and so are outside the +Where this Specification uses the terms ``may'', or ``optional'', such features or +behaviors do not define requirements necessary for compliance and so are outside the Scope of this Specification. -Where this Specification uses the terms “not required”, such features or +Where this Specification uses the terms ``not required'', such features or behaviors may be omitted from certain implementations, but when they are included, they -define requirements necessary for compliance and so are INCLUDED in the Scope of this +define requirements necessary for compliance and so are INCLUDED in the Scope of this Specification. -Where this Specification includes normative references to external documents, the -specifically identified sections and functionality of those external documents are in -Scope. Requirements defined by external documents not created by Khronos may contain -contributions from non-members of Khronos not covered by the Khronos Intellectual +Where this Specification includes normative references to external documents, the +specifically identified sections and functionality of those external documents are in +Scope. Requirements defined by external documents not created by Khronos may contain +contributions from non-members of Khronos not covered by the Khronos Intellectual Property Rights Policy. Khronos Group makes no, and expressly disclaims any, representations or warranties, @@ -62,6 +62,7 @@ representatives be liable for any damages, whether direct, indirect, special or consequential damages for lost revenues, lost profits, or otherwise, arising from or in connection with these materials. -Khronos and Vulkan are trademarks of The Khronos Group Inc. OpenCL is a trademark of -Apple Inc. and OpenGL is a registered trademark of Silicon Graphics International, both -used under license by Khronos. +Khronos is a trademark, and Vulkan is a registered trademark of The Khronos +Group Inc. OpenCL is a trademark of Apple Inc. and OpenGL is a registered +trademark of Silicon Graphics International, both used under license by +Khronos. diff --git a/doc/specs/vulkan/styleguide.txt b/doc/specs/vulkan/styleguide.txt index 768c65f6..ba029d13 100644 --- a/doc/specs/vulkan/styleguide.txt +++ b/doc/specs/vulkan/styleguide.txt @@ -2,7 +2,7 @@ // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ -= Vulkan Documentation and Extensions: Procedures and Conventions += Vulkan^(R)^ Documentation and Extensions: Procedures and Conventions Jon Leech, Tobias Hector include::specversion.txt[] :toc2: diff --git a/doc/specs/vulkan/vkspec.txt b/doc/specs/vulkan/vkspec.txt index 1e70a511..da28f902 100644 --- a/doc/specs/vulkan/vkspec.txt +++ b/doc/specs/vulkan/vkspec.txt @@ -3,7 +3,7 @@ include::specversion.txt[] -= Vulkan {apirevision} - A Specification {apititle} += Vulkan^(R)^ {apirevision} - A Specification {apititle} The Khronos Vulkan Working Group :icons: :toc2: diff --git a/src/spec/README.adoc b/src/spec/README.adoc index 938e5ba6..d5964db4 100644 --- a/src/spec/README.adoc +++ b/src/spec/README.adoc @@ -1,4 +1,4 @@ -= Vulkan API Registry Build Instructions and Notes = += Vulkan^(R)^ API Registry Build Instructions and Notes = Jon Leech diff --git a/src/spec/generator.py b/src/spec/generator.py index 3c5cc0a1..680cd6ac 100644 --- a/src/spec/generator.py +++ b/src/spec/generator.py @@ -14,12 +14,12 @@ # See the License for the specific language governing permissions and # limitations under the License. -import os,re,sys +import io,os,re,sys def write( *args, **kwargs ): - file = kwargs.pop('file',sys.stdout) - end = kwargs.pop( 'end','\n') - file.write( ' '.join([str(arg) for arg in args]) ) + file = kwargs.pop(u'file',sys.stdout) + end = kwargs.pop( u'end',u'\n') + file.write( u' '.join([str(arg) for arg in args]) ) file.write( end ) # noneStr - returns string argument, or "" if argument is None. @@ -319,7 +319,7 @@ class OutputGenerator: # Generator can be used without writing to a file. if (self.genOpts.filename != None): filename = self.genOpts.directory + '/' + self.genOpts.filename - self.outFile = open(filename, 'w', encoding='utf-8') + self.outFile = io.open(filename, 'w', encoding='utf-8') else: self.outFile = sys.stdout def endFile(self): diff --git a/src/spec/genvk.py b/src/spec/genvk.py index 0238d6b2..1628a785 100755 --- a/src/spec/genvk.py +++ b/src/spec/genvk.py @@ -233,7 +233,8 @@ def genTarget(args): createGenerator = genOpts[args.target][0] options = genOpts[args.target][1] - write('* Building', options.filename, file=sys.stderr) + if not args.quiet: + write('* Building', options.filename, file=sys.stderr) startTimer(args.time) gen = createGenerator(errFile=errWarn, @@ -241,7 +242,9 @@ def genTarget(args): diagFile=diag) reg.setGenerator(gen) reg.apiGen(options) - write('* Generated', options.filename, file=sys.stderr) + + if not args.quiet: + write('* Generated', options.filename, file=sys.stderr) endTimer(args.time, '* Time to generate ' + options.filename + ' =') else: write('No generator options for unknown target:', @@ -284,6 +287,8 @@ if __name__ == '__main__': help='Create target and related files in specified directory') parser.add_argument('target', metavar='target', nargs='?', help='Specify target') + parser.add_argument('-quiet', action='store_true', default=False, + help='Suppress script output during normal execution.') args = parser.parse_args() diff --git a/src/spec/registry.txt b/src/spec/registry.txt index 1c30e39b..37dd29c9 100644 --- a/src/spec/registry.txt +++ b/src/spec/registry.txt @@ -2,8 +2,8 @@ // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ -The Khronos Vulkan API Registry -=============================== +The Khronos Vulkan^(R)^ API Registry +==================================== Jon Leech include::../../doc/specs/vulkan/specversion.txt[] :toc2: diff --git a/src/spec/vk.xml b/src/spec/vk.xml index 869e1279..4f358c20 100644 --- a/src/spec/vk.xml +++ b/src/spec/vk.xml @@ -104,7 +104,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 37 +#define VK_HEADER_VERSION 38 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; diff --git a/src/vulkan/vulkan.h b/src/vulkan/vulkan.h index b42cca57..f24a0a2c 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 37 +#define VK_HEADER_VERSION 38 #define VK_NULL_HANDLE 0