From e5b16130fe5f5c0a8ffd801aa9ea706ef5b63dc8 Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Thu, 30 Jun 2016 19:34:54 -0700 Subject: [PATCH] Change log for July 1, 2016 Vulkan 1.0.19 spec update: * Bump API patch number and header version number to 19 for this update. Github Issues: * Clarified how flink:vkGetImageSubresourceLayout interacts with image layouts (public issue 247). * Remove ename:VK_IMAGE_LAYOUT_PREINITIALIZED from valid usage rule for slink:VkImageMemoryBarrier::pname:oldLayout. It is only valid if it is the current layout (public issue 248). * Modify valid usage for flink:vkBindBufferMemory so implementations are free to require a different backing memory size than the buffer size (public issue 251). * Clarify that filtering rules for flink:vkCmdBlitImage always apply, and are usually no-ops if the formats are the same (public issue 253). * Remove 'non-sparse' from description of flink:vkGetBufferMemoryRequirements and flink:vkGetImageMemoryRequirements (public issue 257). * Remove ename:VK_ERROR_LAYER_NOT_PRESENT error code from flink:vkCreateDevice (public issue 259). * Change "must not" to "should not" in constraint on when flink:vkAcquireNextImageKHR is called in the +VK_KHR_swapchain+ branch (public issue 262). * Change type of flink:vkCmdUpdateBuffer::pname:pData from basetype:uint32_t* to basetype:void* (public issue 263). * Change should: to must: in description of where additional segments are placed in the <<[tessellation-tessellator-spacing,Tessellator Spacing>> section (public issue 264). Internal Issues: * Normalize the language of all the compute shader built-ins in the <> section (internal issue 323). * Remove definition of presentation engine internal queue lengths associated with ename:VK_PRESENT_MODE_FIFO_KHR and ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR in the <> chapter (internal issue 374). * The language of a Note was too broad, and implied that loaders for a given OS would statically export functions for WSI extensions that weren't relevant to (or supported on) the OS. Also, removed "Khronos-provided" since the Android loader isn't (internal issue 380) Other Commits: * Add ename:VK_INCOMPLETE to list of return values for flink:vkGetPipelineCacheData. Spec says this value is returnable, but it wasn't listed in the error codes. * Fix "correponds" typo in member definitions for slink:VkSubpassDescription. --- ChangeLog.txt | 54 ++++++++ doc/specs/vulkan/Makefile | 2 +- doc/specs/vulkan/appendices/extensions.txt | 9 +- doc/specs/vulkan/chapters/clears.txt | 9 ++ doc/specs/vulkan/chapters/copies.txt | 3 +- doc/specs/vulkan/chapters/interfaces.txt | 83 +++++++------ doc/specs/vulkan/chapters/memory.txt | 1 + doc/specs/vulkan/chapters/renderpass.txt | 2 +- doc/specs/vulkan/chapters/resources.txt | 15 ++- doc/specs/vulkan/chapters/tessellation.txt | 2 +- doc/specs/vulkan/genRelease | 101 ++------------- doc/specs/vulkan/genspec.py | 115 ++++++++++++++++++ doc/specs/vulkan/protos/vkCmdUpdateBuffer.txt | 2 +- .../validity/protos/vkBindBufferMemory.txt | 2 +- .../validity/protos/vkCmdBeginRenderPass.txt | 2 +- .../validity/protos/vkCmdUpdateBuffer.txt | 4 +- .../vulkan/validity/protos/vkCreateDevice.txt | 1 - .../protos/vkGetPipelineCacheData.txt | 1 + .../validity/structs/VkImageMemoryBarrier.txt | 2 +- src/spec/vk.xml | 27 ++-- src/vulkan/vulkan.h | 6 +- 21 files changed, 284 insertions(+), 159 deletions(-) create mode 100755 doc/specs/vulkan/genspec.py diff --git a/ChangeLog.txt b/ChangeLog.txt index 291abd75..46070799 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -869,3 +869,57 @@ Other Commits: M, N, and I, describing set, binding, and index, consistently throughout the example code. +----------------------------------------------------- + +Change log for July 1, 2016 Vulkan 1.0.19 spec update: + + * Bump API patch number and header version number to 19 for this + update. + +Github Issues: + + * Clarified how flink:vkGetImageSubresourceLayout interacts with image + layouts (public issue 247). + * Remove ename:VK_IMAGE_LAYOUT_PREINITIALIZED from valid usage rule for + slink:VkImageMemoryBarrier::pname:oldLayout. It is only valid if it is + the current layout (public issue 248). + * Modify valid usage for flink:vkBindBufferMemory so implementations are + free to require a different backing memory size than the buffer size + (public issue 251). + * Clarify that filtering rules for flink:vkCmdBlitImage always apply, and + are usually no-ops if the formats are the same (public issue 253). + * Remove 'non-sparse' from description of + flink:vkGetBufferMemoryRequirements and + flink:vkGetImageMemoryRequirements (public issue 257). + * Remove ename:VK_ERROR_LAYER_NOT_PRESENT error code from + flink:vkCreateDevice (public issue 259). + * Change "must not" to "should not" in constraint on when + flink:vkAcquireNextImageKHR is called in the +VK_KHR_swapchain+ branch + (public issue 262). + * Change type of flink:vkCmdUpdateBuffer::pname:pData from + basetype:uint32_t* to basetype:void* (public issue 263). + * Change should: to must: in description of where additional segments are + placed in the <<[tessellation-tessellator-spacing,Tessellator Spacing>> + section (public issue 264). + +Internal Issues: + + * Normalize the language of all the compute shader built-ins in the + <> section (internal + issue 323). + * Remove definition of presentation engine internal queue lengths + associated with ename:VK_PRESENT_MODE_FIFO_KHR and + ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR in the <> chapter (internal issue 374). + * The language of a Note was too broad, and implied that loaders for a + given OS would statically export functions for WSI extensions that + weren't relevant to (or supported on) the OS. Also, removed + "Khronos-provided" since the Android loader isn't (internal issue 380) + +Other Commits: + + * Add ename:VK_INCOMPLETE to list of return values for + flink:vkGetPipelineCacheData. Spec says this value is returnable, but it + wasn't listed in the error codes. + * Fix "correponds" typo in member definitions for + slink:VkSubpassDescription. diff --git a/doc/specs/vulkan/Makefile b/doc/specs/vulkan/Makefile index ec9fc89f..a0d70222 100644 --- a/doc/specs/vulkan/Makefile +++ b/doc/specs/vulkan/Makefile @@ -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.18 +SPECREVISION = 1.0.19 SPECREMARK = # Spec targets diff --git a/doc/specs/vulkan/appendices/extensions.txt b/doc/specs/vulkan/appendices/extensions.txt index f99c3f63..d0100bf3 100644 --- a/doc/specs/vulkan/appendices/extensions.txt +++ b/doc/specs/vulkan/appendices/extensions.txt @@ -496,7 +496,8 @@ An extension can: be considered platform specific, in which case its interfaces in +vulkan.h+ are protected by #ifdefs. This is orthogonal to whether an extension command is considered to be part of the Vulkan ABI. -The initial set of WSI extension commands are considered to be part of the +The initial set of WSI extension commands (i.e. for VK_KHR_surface, +VK_KHR_swapchain, and VK_KHR_*_surface) are considered to be part of the Vulkan ABI. Function prototypes for these WSI commands are included in the +vulkan.h+ provided by Khronos, though the platform-specific portions of +vulkan.h+ are protected by #ifdefs. @@ -527,8 +528,10 @@ function without needing to call one of the ftext:vkGet*ProcAddr commands. [NOTE] .Note ==== -The Khronos-provided Vulkan API loader for Android, Linux, and Windows -exports functions for all core Vulkan API and WSI extension commands. The +The Vulkan API loader for Android, Linux, and Windows exports functions for all +core Vulkan API commands, and for a set of WSI extension commands that +are applicable to those operating systems (see Vulkan loader documentation for +the relevant platform/OS for details). The WSI functions are considered special, because they are required for many applications. ==== diff --git a/doc/specs/vulkan/chapters/clears.txt b/doc/specs/vulkan/chapters/clears.txt index 476c188f..28cc021a 100644 --- a/doc/specs/vulkan/chapters/clears.txt +++ b/doc/specs/vulkan/chapters/clears.txt @@ -271,4 +271,13 @@ buffer to be compatible with fname:vkCmdUpdateBuffer. include::../validity/protos/vkCmdUpdateBuffer.txt[] +[NOTE] +.Note +==== +The pname:pData parameter was of type basetype:uint32_t* instead of +basetype:void* prior to revision 1.0.19 of the Specification and +ename:VK_HEADER_VERSION 19 of +vulkan.h+. This was a +historical anomaly, as the source data may be of other types. +==== + [[clears-end]] diff --git a/doc/specs/vulkan/chapters/copies.txt b/doc/specs/vulkan/chapters/copies.txt index 07a7506f..5ed9dcf2 100644 --- a/doc/specs/vulkan/chapters/copies.txt +++ b/doc/specs/vulkan/chapters/copies.txt @@ -449,8 +449,7 @@ 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 fname:vkCmdBlitImage is used on images of different formats, the -following conversion rules apply: +The following filtering and conversion rules apply: * Integer formats can: only be converted to other integer formats with the same signedness. diff --git a/doc/specs/vulkan/chapters/interfaces.txt b/doc/specs/vulkan/chapters/interfaces.txt index cbbdc398..caf979c2 100644 --- a/doc/specs/vulkan/chapters/interfaces.txt +++ b/doc/specs/vulkan/chapters/interfaces.txt @@ -798,17 +798,19 @@ constant zero. code:GlobalInvocationId:: -An input variable decorated with code:GlobalInvocationId will contain the -location of the current compute shader invocation within the global -workgroup. The value in this variable is equal to the index of the local -workgroup multiplied by the size of the local workgroup plus -code:LocalInvocationId. +The code:GlobalInvocationId built-in decoration can: be applied to a variable +that represents the location of the current invocation within the global +workgroup. Each component is equal to the index of the local workgroup +multiplied by the size of the local workgroup plus code:LocalInvocationId. + The code:GlobalInvocationId decoration must: be used only within compute shaders. + -code:GlobalInvocationId must: be declared as a three-component vector of -32-bit integers. +The variable decorated with code:GlobalInvocationId must: be declared using the +input storage class. ++ +The variable decorated with code:GlobalInvocationId must: be declared as a +three-component vector of 32-bit unsigned integers. code:HelperInvocation:: @@ -893,17 +895,19 @@ code:Layer must: be declared as a scalar 32-bit integer. code:LocalInvocationId:: -The code:LocalInvocationId decoration can: be applied to a code:uvec3 input -variable in a compute shader, in which case it will contain the location of the -current compute shader invocation within the local workgroup. The possible -values for each component of code:LocalInvocationId range from zero through to -the size of the workgroup in that dimension minus one. +The code:LocalInvocationId built-in decoration can: be applied to a variable +that represents the location of the current compute shader invocation within +the local workgroup. Each component ranges from zero through to the size of the +workgroup in that dimension minus one. + The code:LocalInvocationId decoration must: be used only within compute shaders. + -code:LocalInvocationId must: be declared as a three-component vector of 32-bit -integers. +The variable decorated with code:LocalInvocationId must: be declared using the +input storage class. ++ +The variable decorated with code:LocalInvocationId must: be declared as a +three-component vector of 32-bit unsigned integers. [NOTE] .Note @@ -917,17 +921,19 @@ code:LocalInvocationId.y and code:LocalInvocationId.z will be zero. code:NumWorkgroups:: -The code:NumWorkgroups decoration can: be applied to a code:uvec3 input -variable in a compute shader, in which case it will contain the number of -local workgroups that are part of the dispatch that the invocation belongs -to. It reflects the values passed to a call to flink:vkCmdDispatch or -through the structure consumed by the execution of -flink:vkCmdDispatchIndirect. +The code:NumWorkgroups built-in decoration can: be applied to a variable that +represents the number of local workgroups that are part of the dispatch that the +invocation belongs to. Each component is equal to the values of the parameters +passed into flink:vkCmdDispatch or read from the sname:VkDispatchIndirectCommand +structure read through a call to flink:vkCmdDispatchIndirect. + 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. +The variable decorated with code:NumWorkgroups must: be declared using the input +storage class. ++ +The variable decorated with code:NumWorkgroups must: be declared as a +three-component vector of 32-bit integers. code:PatchVertices:: @@ -1183,30 +1189,31 @@ code:ViewportIndex must: be declared as a 32-bit integer. code:WorkgroupId:: -The code:WorkgroupId built-in decoration can: be applied to an input -variable in the compute shader. It will contain a three dimensional integer -index of the global workgroup that the current invocation is a member of. +The code:WorkgroupId built-in decoration can: be applied to a variable that +represents the global workgroup that the current invocation is a member of. Each component ranges from zero to the values of the parameters passed into -flink:vkCmdDispatch or read from the sname:VkDispatchIndirectCommand -structure read through a call to flink:vkCmdDispatchIndirect. +flink:vkCmdDispatch or read from the sname:VkDispatchIndirectCommand structure +read through a call to flink:vkCmdDispatchIndirect. + 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. +The variable decorated with code:WorkgroupId must: be declared using the input +storage class. ++ +The variable decorated with code:WorkgroupId must: be declared as a +three-component vector of 32-bit unsigned 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 +The code:WorkgroupSize built-in decoration can: be applied to an object that +represents the dimensions of a local workgroup. If an object 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. +The object decorated with code:WorkgroupSize must: be a specialization constant +or a constant. ++ +The object decorated with code:WorkgroupSize must: be declared as a +three-component vector of 32-bit unsigned integers. diff --git a/doc/specs/vulkan/chapters/memory.txt b/doc/specs/vulkan/chapters/memory.txt index cc8f7505..af3f0072 100644 --- a/doc/specs/vulkan/chapters/memory.txt +++ b/doc/specs/vulkan/chapters/memory.txt @@ -73,6 +73,7 @@ valid pointer to memory allocation containing at least pname:size bytes, and with the pointer value being a multiple of pname:alignment. [NOTE] +.Note ==== Correct Vulkan operation cannot: be assumed if the application doesn't follow these rules. diff --git a/doc/specs/vulkan/chapters/renderpass.txt b/doc/specs/vulkan/chapters/renderpass.txt index cea83b21..9177c159 100644 --- a/doc/specs/vulkan/chapters/renderpass.txt +++ b/doc/specs/vulkan/chapters/renderpass.txt @@ -295,7 +295,7 @@ include::../structs/VkSubpassDescription.txt[] slink:VkAttachmentReference structures that lists which of the render pass's attachments will be used as color attachments in the subpass, and what layout the attachment images will be in during the subpass. Each - element of the array correponds to a fragment shader output location, + element of the array corresponds to a fragment shader output location, i.e. if the shader declared an output variable `layout(location=X)` then it uses the attachment provided in pname:pColorAttachments[X]. * pname:pResolveAttachments is `NULL` or a pointer to an array of diff --git a/doc/specs/vulkan/chapters/resources.txt b/doc/specs/vulkan/chapters/resources.txt index 5589fc9b..9e514ab7 100644 --- a/doc/specs/vulkan/chapters/resources.txt +++ b/doc/specs/vulkan/chapters/resources.txt @@ -372,8 +372,8 @@ more details. be used to create a sname:VkImageView of type ename:VK_IMAGE_VIEW_TYPE_CUBE or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY. -The layout of an image subresource (mipLevel/arrayLayer) of an image created -with linear tiling is queried by calling: +To query the host access layout of an image subresource, for an image +created with linear tiling, call: include::../protos/vkGetImageSubresourceLayout.txt[] @@ -386,6 +386,9 @@ include::../protos/vkGetImageSubresourceLayout.txt[] include::../validity/protos/vkGetImageSubresourceLayout.txt[] +flink:vkGetImageSubresourceLayout is invariant for the lifetime of a single +image. + The sname:VkImageSubresource structure is defined as: include::../structs/VkImageSubresource.txt[] @@ -520,7 +523,9 @@ Host access to image memory is only well-defined for images created with ename:VK_IMAGE_TILING_LINEAR tiling and for image subresources of those images which are currently in either the ename:VK_IMAGE_LAYOUT_PREINITIALIZED or ename:VK_IMAGE_LAYOUT_GENERAL -layout. +layout. Calling flink:vkGetImageSubresourceLayout for a linear image returns +a subresource layout mapping that is valid for either of those image +layouts. The set of image layouts consists of: @@ -898,7 +903,7 @@ any of the following operations: Once bound, the memory binding is immutable for the lifetime of the resource. -To determine the memory requirements for a non-sparse buffer resource, call: +To determine the memory requirements for a buffer resource, call: include::../protos/vkGetBufferMemoryRequirements.txt[] @@ -910,7 +915,7 @@ include::../protos/vkGetBufferMemoryRequirements.txt[] include::../validity/protos/vkGetBufferMemoryRequirements.txt[] -To determine the memory requirements for a non-sparse image resource, call: +To determine the memory requirements for an image resource, call: include::../protos/vkGetImageMemoryRequirements.txt[] diff --git a/doc/specs/vulkan/chapters/tessellation.txt b/doc/specs/vulkan/chapters/tessellation.txt index e0c76de2..6248dc26 100644 --- a/doc/specs/vulkan/chapters/tessellation.txt +++ b/doc/specs/vulkan/chapters/tessellation.txt @@ -133,7 +133,7 @@ latexmath:[$n-f$], where latexmath:[$f$] is the clamped floating-point tessellation level. When latexmath:[$n-f$] is zero, the additional segments will have equal length to the other segments. As latexmath:[$n-f$] approaches 2.0, the relative length of the additional segments approaches -zero. The two additional segments should: be placed symmetrically on +zero. The two additional segments must: be placed symmetrically on opposite sides of the subdivided edge. The relative location of these two segments is implementation-dependent, but must: be identical for any pair of subdivided edges with identical values of latexmath:[$f$]. diff --git a/doc/specs/vulkan/genRelease b/doc/specs/vulkan/genRelease index 535da30d..905844d1 100755 --- a/doc/specs/vulkan/genRelease +++ b/doc/specs/vulkan/genRelease @@ -1,96 +1,17 @@ #!/usr/bin/python3 -import time -from datetime import * +from genspec import * -# This script builds a full release package including XHTML and PDF -# versions of the specified branches (usually 1.0 and 1.0-wsi_extensions, -# but tags or commits can be used as well). Other files in the release -# directory are removed, including man pages, XHTML chunked, HTML, -# validity output, etc. -# -# Both branches must be fully committed and up to date when the script -# is run, with no outstanding un-added / un-committed files. Both -# branches must have fully regnerated all automatically-regeneratable -# files. After completing the build, the current branch is set to -# the first (core) branch and suggestions for creating tags are printed out. - -# branch = branch or commit or tag name -# label = textual label to apply -# outdir = directory to generate specs in -# xmlTargets = targets to build in src/spec/ -# specTargets = targets to build in doc/specs/vulkan/ -def buildRelease(branch,label,outdir,xmlTargets,specTargets): - global root, xml, spec - - print('echo Info: Generating branch=' + branch, - 'label=' + label, - 'outdir=' + outdir) - print('git checkout', branch) - - print('echo Info: Cleaning spec in', outdir) - print('cd', spec) - print('rm -rf', - outdir + '/man', - outdir + '/xhtml', - outdir + '/pdf', - outdir + '/chunked', - outdir + '/vkspec.html', - 'specversion.txt') - - print('echo Info: Generating headers and spec include files') - print('cd', xml) - print('make OUTDIR=' + outdir, xmlTargets) - - print('echo Info: Generating spec') - print('cd', spec) - print('make specversion.txt') - print('make -j 4 OUTDIR=' + outdir, ' NOTEOPTS="-a implementation-guide"', - specTargets) - print('rm', outdir + '/pdf/vkspec.xml') - -# Main - -global root, xml, spec - -# Root of the Vulkan git repo containing the specs -root = '/home/tree/git/Vulkan-Docs' -# Directory with vk.xml and generation tools -xml = root + '/src/spec' -# Directory with spec sources -spec = root + '/doc/specs/vulkan' - -# Output directory, which does not have to be (and probably -# should not be) in the spec repo -outdir = '/home/tree/git/Vulkan-Web-Registry/specs/' - -# These can be changed to tags, etc. -corebranch = '1.0' -wsibranch = '1.0-wsi_extensions' - -# date in YYYYMMDD format -now = datetime.today().strftime('%Y%m%d') - -# Generate specs -coreXmlTargets='clobber full_install pdf_install' -coreSpecTargets='xhtml pdf styleguide manhtml manpdf manhtmlpages' -buildRelease(corebranch, corebranch, outdir + corebranch, - coreXmlTargets, coreSpecTargets) - -wsiXmlTargets='clobber full_install' -wsiSpecTargets='xhtml pdf' -buildRelease(wsibranch, wsibranch, outdir + wsibranch, - wsiXmlTargets, wsiSpecTargets) +buildBranch('1.0', + coreTargets = True, + repoDir = '/home/tree/git/vulkan', + outDir = '/home/tree/git/vulkan/out') +buildBranch('1.0-wsi_extensions', + coreTargets = False, + repoDir = '/home/tree/git/vulkan', + outDir = '/home/tree/git/vulkan/out') print('echo Info: post-generation cleanup') +print('git checkout ' + coreBranch) -print('git checkout ' + corebranch) - -print('echo To tag the spec branches, execute these commands:') -print('echo git checkout', corebranch) -print('echo git tag -a -m \\"Tag core API specification for', now, - 'release\\"', 'v1.0-core-' + now) - -print('echo git checkout', wsibranch) -print('echo git tag -a -m \\"Tag core+WSI API specification for', now, - 'release\\"', 'v1.0-core+wsi-' + now) +createTags(buildOnFriday()) diff --git a/doc/specs/vulkan/genspec.py b/doc/specs/vulkan/genspec.py new file mode 100755 index 00000000..a2115bd8 --- /dev/null +++ b/doc/specs/vulkan/genspec.py @@ -0,0 +1,115 @@ +#!/usr/bin/python3 + +import time +from datetime import timedelta, date + +# These can be changed to tags, etc. +coreBranch = '1.0' +wsiBranch = '1.0-wsi_extensions' + +# This script builds a full release package including XHTML and PDF +# versions of the specified branches (usually 1.0 and 1.0-wsi_extensions, +# but tags or commits can be used as well). Other files in the release +# directory are removed, including man pages, XHTML chunked, HTML, +# validity output, etc. +# +# Both branches must be fully committed and up to date when the script +# is run, with no outstanding un-added / un-committed files. Both +# branches must have fully regenerated all automatically generated +# files. After completing the build, the current branch is set to +# the first (core) branch and suggestions for creating tags are printed out. + +# Return a date for the current, or upcoming if not already, Friday, +# which is when releases happen +def buildOnFriday(): + today = date.today() + friday = today + timedelta((4 - today.weekday()) % 7) + return friday + +# branch = branch or commit or tag name +# label = textual label to apply +# outdir = directory to generate specs in +# xmlDir = directory containing registry XML +# xmlTargets = targets to build in src/spec/ +# specDir = directory containing spec source & Makefile +# specTargets = targets to build in doc/specs/vulkan/ +# miscSrc = path to copy misc files from, if non-None +# miscDst = path to copy misc files to, if non-None +def buildRelease(branch, label, outdir, + xmlDir, xmlTargets, + specDir, specTargets, + miscSrc = None, miscDst = None): + print('echo Info: Generating branch=' + branch, + 'label=' + label, + 'outdir=' + outdir) + print('git checkout', branch) + + print('echo Info: Cleaning spec in', outdir) + print('cd', specDir) + print('rm -rf', + outdir + '/man', + outdir + '/xhtml', + outdir + '/pdf', + outdir + '/chunked', + outdir + '/style', + outdir + '/vkspec.html', + 'styleguide.html', + 'specversion.txt') + + print('echo Info: Generating headers and spec include files') + print('cd', xmlDir) + print('make OUTDIR=' + outdir, xmlTargets) + + print('echo Info: Generating spec') + print('cd', specDir) + print('make specversion.txt') + print('make -j 4 OUTDIR=' + outdir, ' NOTEOPTS="-a implementation-guide"', + specTargets) + print('rm', outdir + '/pdf/vkspec.xml') + + if (miscSrc != None and miscDst != None): + print('cp', miscSrc + '/*.txt', miscDst + '/') + + +# Build all target branches +# repoDir = path to the Vulkan git repo containing the specs +# outDir = path to the output base directory in which each branch is generated +def buildBranch(branch, coreTargets, repoDir, outDir): + # Directory with vk.xml and generation tools + xmlDir = repoDir + '/src/spec' + # Directory with spec sources + specDir = repoDir + '/doc/specs/vulkan' + # Src/dst directories with misc. GLSL extension specs + miscSrc = repoDir + '/doc/specs/misc' + miscDst = outDir + '/misc' + + # Generate specs + if (coreTargets): + xmlTargets = 'clobber full_install pdf_install' + specTargets = 'xhtml pdf styleguide manhtml manpdf manhtmlpages' + else: + xmlTargets = 'clobber full_install' + specTargets = 'xhtml pdf' + + buildRelease(branch, branch, outDir + '/' + branch, + xmlDir, xmlTargets, specDir, specTargets, + miscSrc, miscDst) + +# Commands to tag the git branches +# tagdate = date to tag the tree with when done +def createTags(tagdate): + global coreBranch, wsiBranch + + # Tag date in YYYYMMDD format + now = tagdate.strftime('%Y%m%d') + + print('echo To tag the spec branches, execute these commands:') + print('echo git checkout', coreBranch) + print('echo git tag -a -m \\"Tag core API specification for', now, + 'release\\"', 'v1.0-core-' + now) + + print('echo git checkout', wsiBranch) + print('echo git tag -a -m \\"Tag core+WSI API specification for', now, + 'release\\"', 'v1.0-core+wsi-' + now) + + diff --git a/doc/specs/vulkan/protos/vkCmdUpdateBuffer.txt b/doc/specs/vulkan/protos/vkCmdUpdateBuffer.txt index 11fdf397..21585de7 100644 --- a/doc/specs/vulkan/protos/vkCmdUpdateBuffer.txt +++ b/doc/specs/vulkan/protos/vkCmdUpdateBuffer.txt @@ -12,5 +12,5 @@ void vkCmdUpdateBuffer( VkBuffer dstBuffer, VkDeviceSize dstOffset, VkDeviceSize dataSize, - const uint32_t* pData); + const void* pData); ------------------------------------------------------------------------------ diff --git a/doc/specs/vulkan/validity/protos/vkBindBufferMemory.txt b/doc/specs/vulkan/validity/protos/vkBindBufferMemory.txt index ee96e8b0..77fa01eb 100644 --- a/doc/specs/vulkan/validity/protos/vkBindBufferMemory.txt +++ b/doc/specs/vulkan/validity/protos/vkBindBufferMemory.txt @@ -20,8 +20,8 @@ endif::doctype-manpage[] * If pname:buffer was created with the ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT, pname:memoryOffset must: be a multiple of sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment * If pname:buffer was created with the ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, pname:memoryOffset must: be a multiple of sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment * pname:memory must: have been allocated using one of the memory types allowed in the pname:memoryTypeBits member of the sname:VkMemoryRequirements structure returned from a call to fname:vkGetBufferMemoryRequirements with pname:buffer -* The size of pname:buffer must: be less than or equal to the size of pname:memory minus pname:memoryOffset * pname:memoryOffset must: be an integer multiple of the pname:alignment member of the sname:VkMemoryRequirements structure returned from a call to fname:vkGetBufferMemoryRequirements with pname:buffer +* The pname:size member of the sname:VkMemoryRequirements structure returned from a call to fname:vkGetBufferMemoryRequirements with pname:buffer must: be less than or equal to the size of pname:memory minus pname:memoryOffset ifndef::doctype-manpage[] ******************************************************************************** endif::doctype-manpage[] diff --git a/doc/specs/vulkan/validity/protos/vkCmdBeginRenderPass.txt b/doc/specs/vulkan/validity/protos/vkCmdBeginRenderPass.txt index f5054b25..03e16c39 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdBeginRenderPass.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdBeginRenderPass.txt @@ -19,7 +19,7 @@ endif::doctype-manpage[] * If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_SAMPLED_BIT or ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set * If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set * If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set -* If any of the pname:initialLayout members of the sname:VkAttachmentDescription structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is not one of ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED, then each such pname:initialLayout must: be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin. +* If any of the pname:initialLayout members of the sname:VkAttachmentDescription structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is not ename:VK_IMAGE_LAYOUT_UNDEFINED, then each such pname:initialLayout must: be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin. ifndef::doctype-manpage[] ******************************************************************************** endif::doctype-manpage[] diff --git a/doc/specs/vulkan/validity/protos/vkCmdUpdateBuffer.txt b/doc/specs/vulkan/validity/protos/vkCmdUpdateBuffer.txt index 7c4a9b27..a0e5ee9a 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdUpdateBuffer.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdUpdateBuffer.txt @@ -9,12 +9,12 @@ Valid Usage endif::doctype-manpage[] * pname:commandBuffer must: be a valid sname:VkCommandBuffer handle * pname:dstBuffer must: be a valid sname:VkBuffer handle -* pname:pData must: be a pointer to an array of latexmath:[$dataSize \over 4$] basetype:uint32_t values +* pname:pData must: be a pointer to an array of pname:dataSize bytes * pname:commandBuffer must: be in the recording state * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support transfer, graphics or compute operations * This command must: only be called outside of a render pass instance -* Each of pname:commandBuffer and pname:dstBuffer must: have been created, allocated or retrieved from the same sname:VkDevice * pname:dataSize must: be greater than `0` +* Each of pname:commandBuffer and pname:dstBuffer must: have been created, allocated or retrieved from the same sname:VkDevice * pname:dstOffset must: be less than the size of pname:dstBuffer * pname:dataSize must: be less than or equal to the size of pname:dstBuffer minus pname:dstOffset * pname:dstBuffer must: have been created with ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag diff --git a/doc/specs/vulkan/validity/protos/vkCreateDevice.txt b/doc/specs/vulkan/validity/protos/vkCreateDevice.txt index 0dc2633d..d8649ebc 100644 --- a/doc/specs/vulkan/validity/protos/vkCreateDevice.txt +++ b/doc/specs/vulkan/validity/protos/vkCreateDevice.txt @@ -39,7 +39,6 @@ endif::doctype-manpage[] * ename:VK_ERROR_OUT_OF_HOST_MEMORY * ename:VK_ERROR_OUT_OF_DEVICE_MEMORY * ename:VK_ERROR_INITIALIZATION_FAILED -* ename:VK_ERROR_LAYER_NOT_PRESENT * ename:VK_ERROR_EXTENSION_NOT_PRESENT * ename:VK_ERROR_FEATURE_NOT_PRESENT * ename:VK_ERROR_TOO_MANY_OBJECTS diff --git a/doc/specs/vulkan/validity/protos/vkGetPipelineCacheData.txt b/doc/specs/vulkan/validity/protos/vkGetPipelineCacheData.txt index de0963af..87c4635f 100644 --- a/doc/specs/vulkan/validity/protos/vkGetPipelineCacheData.txt +++ b/doc/specs/vulkan/validity/protos/vkGetPipelineCacheData.txt @@ -32,6 +32,7 @@ ifdef::doctype-manpage[] On success, this command returns:: endif::doctype-manpage[] * ename:VK_SUCCESS +* ename:VK_INCOMPLETE ifndef::doctype-manpage[] <>:: endif::doctype-manpage[] diff --git a/doc/specs/vulkan/validity/structs/VkImageMemoryBarrier.txt b/doc/specs/vulkan/validity/structs/VkImageMemoryBarrier.txt index d39c1cc5..311e43ed 100644 --- a/doc/specs/vulkan/validity/structs/VkImageMemoryBarrier.txt +++ b/doc/specs/vulkan/validity/structs/VkImageMemoryBarrier.txt @@ -15,7 +15,7 @@ endif::doctype-manpage[] * pname:newLayout must: be a valid elink:VkImageLayout value * pname:image must: be a valid sname:VkImage handle * pname:subresourceRange must: be a valid sname:VkImageSubresourceRange structure -* pname:oldLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED, ename:VK_IMAGE_LAYOUT_PREINITIALIZED or the current layout of the image region affected by the barrier +* pname:oldLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED or the current layout of the image subresources affected by the barrier * pname:newLayout mustnot: be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED * If pname:image was created with a sharing mode of ename:VK_SHARING_MODE_CONCURRENT, pname:srcQueueFamilyIndex and pname:dstQueueFamilyIndex must: both be ename:VK_QUEUE_FAMILY_IGNORED * If pname:image was created with a sharing mode of ename:VK_SHARING_MODE_EXCLUSIVE, pname:srcQueueFamilyIndex and pname:dstQueueFamilyIndex must: either both be ename:VK_QUEUE_FAMILY_IGNORED, or both be a valid queue family (see <>) diff --git a/src/spec/vk.xml b/src/spec/vk.xml index 26091773..fd55c620 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 18 +#define VK_HEADER_VERSION 19 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; @@ -766,7 +766,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkImage image VkImageSubresourceRange subresourceRange - pname:oldLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED, ename:VK_IMAGE_LAYOUT_PREINITIALIZED or the current layout of the image region affected by the barrier + pname:oldLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED or the current layout of the image subresources affected by the barrier pname:newLayout mustnot: be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED If pname:image was created with a sharing mode of ename:VK_SHARING_MODE_CONCURRENT, pname:srcQueueFamilyIndex and pname:dstQueueFamilyIndex must: both be ename:VK_QUEUE_FAMILY_IGNORED If pname:image was created with a sharing mode of ename:VK_SHARING_MODE_EXCLUSIVE, pname:srcQueueFamilyIndex and pname:dstQueueFamilyIndex must: either both be ename:VK_QUEUE_FAMILY_IGNORED, or both be a valid queue family (see <<devsandqueues-queueprops>>) @@ -3043,7 +3043,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkImageCreateFlags flags VkImageFormatProperties* pImageFormatProperties - + VkResult vkCreateDevice VkPhysicalDevice physicalDevice const VkDeviceCreateInfo* pCreateInfo @@ -3207,8 +3207,8 @@ maintained in the master branch of the Khronos Vulkan Github project. If pname:buffer was created with the ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT, pname:memoryOffset must: be a multiple of sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment If pname:buffer was created with the ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, pname:memoryOffset must: be a multiple of sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment pname:memory must: have been allocated using one of the memory types allowed in the pname:memoryTypeBits member of the sname:VkMemoryRequirements structure returned from a call to fname:vkGetBufferMemoryRequirements with pname:buffer - The size of pname:buffer must: be less than or equal to the size of pname:memory minus pname:memoryOffset pname:memoryOffset must: be an integer multiple of the pname:alignment member of the sname:VkMemoryRequirements structure returned from a call to fname:vkGetBufferMemoryRequirements with pname:buffer + The pname:size member of the sname:VkMemoryRequirements structure returned from a call to fname:vkGetBufferMemoryRequirements with pname:buffer must: be less than or equal to the size of pname:memory minus pname:memoryOffset @@ -3522,7 +3522,7 @@ maintained in the master branch of the Khronos Vulkan Github project. If no sname:VkAllocationCallbacks were provided when pname:pipelineCache was created, pname:pAllocator must: be `NULL` - + VkResult vkGetPipelineCacheData VkDevice device VkPipelineCache pipelineCache @@ -4216,9 +4216,8 @@ maintained in the master branch of the Khronos Vulkan Github project. VkBuffer dstBuffer VkDeviceSize dstOffset VkDeviceSize dataSize - const uint32_t* pData + const void* pData - pname:dataSize must: be greater than `0` pname:dstOffset must: be less than the size of pname:dstBuffer pname:dataSize must: be less than or equal to the size of pname:dstBuffer minus pname:dstOffset pname:dstBuffer must: have been created with ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag @@ -4472,7 +4471,7 @@ maintained in the master branch of the Khronos Vulkan Github project. If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_SAMPLED_BIT or ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set - If any of the pname:initialLayout members of the sname:VkAttachmentDescription structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is not one of ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED, then each such pname:initialLayout must: be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin. + If any of the pname:initialLayout members of the sname:VkAttachmentDescription structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is not ename:VK_IMAGE_LAYOUT_UNDEFINED, then each such pname:initialLayout must: be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin. @@ -5452,5 +5451,17 @@ maintained in the master branch of the Khronos Vulkan Github project. + + + + + + + + + + + + diff --git a/src/vulkan/vulkan.h b/src/vulkan/vulkan.h index bbead897..14a15aea 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 18 +#define VK_HEADER_VERSION 19 #define VK_NULL_HANDLE 0 @@ -2347,7 +2347,7 @@ typedef void (VKAPI_PTR *PFN_vkCmdCopyImage)(VkCommandBuffer commandBuffer, VkIm typedef void (VKAPI_PTR *PFN_vkCmdBlitImage)(VkCommandBuffer commandBuffer, VkImage srcImage, VkImageLayout srcImageLayout, VkImage dstImage, VkImageLayout dstImageLayout, uint32_t regionCount, const VkImageBlit* pRegions, VkFilter filter); typedef void (VKAPI_PTR *PFN_vkCmdCopyBufferToImage)(VkCommandBuffer commandBuffer, VkBuffer srcBuffer, VkImage dstImage, VkImageLayout dstImageLayout, uint32_t regionCount, const VkBufferImageCopy* pRegions); typedef void (VKAPI_PTR *PFN_vkCmdCopyImageToBuffer)(VkCommandBuffer commandBuffer, VkImage srcImage, VkImageLayout srcImageLayout, VkBuffer dstBuffer, uint32_t regionCount, const VkBufferImageCopy* pRegions); -typedef void (VKAPI_PTR *PFN_vkCmdUpdateBuffer)(VkCommandBuffer commandBuffer, VkBuffer dstBuffer, VkDeviceSize dstOffset, VkDeviceSize dataSize, const uint32_t* pData); +typedef void (VKAPI_PTR *PFN_vkCmdUpdateBuffer)(VkCommandBuffer commandBuffer, VkBuffer dstBuffer, VkDeviceSize dstOffset, VkDeviceSize dataSize, const void* pData); typedef void (VKAPI_PTR *PFN_vkCmdFillBuffer)(VkCommandBuffer commandBuffer, VkBuffer dstBuffer, VkDeviceSize dstOffset, VkDeviceSize size, uint32_t data); typedef void (VKAPI_PTR *PFN_vkCmdClearColorImage)(VkCommandBuffer commandBuffer, VkImage image, VkImageLayout imageLayout, const VkClearColorValue* pColor, uint32_t rangeCount, const VkImageSubresourceRange* pRanges); typedef void (VKAPI_PTR *PFN_vkCmdClearDepthStencilImage)(VkCommandBuffer commandBuffer, VkImage image, VkImageLayout imageLayout, const VkClearDepthStencilValue* pDepthStencil, uint32_t rangeCount, const VkImageSubresourceRange* pRanges); @@ -3032,7 +3032,7 @@ VKAPI_ATTR void VKAPI_CALL vkCmdUpdateBuffer( VkBuffer dstBuffer, VkDeviceSize dstOffset, VkDeviceSize dataSize, - const uint32_t* pData); + const void* pData); VKAPI_ATTR void VKAPI_CALL vkCmdFillBuffer( VkCommandBuffer commandBuffer,