status-im
/
Vulkan-Docs
mirror of https://github.com/status-im/Vulkan-Docs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch '1.0' into 1.0-VK_KHR_wayland_surface

This commit is contained in:
Jon Leech 2016-06-10 15:57:23 -07:00
parent 799e7d6e2f 5de77cf663
commit 13f4efddda
28 changed files with 321 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
ChangeLog.txt
View File

@ -694,3 +694,61 @@ Internal Issues:
* Update the <<sparsememory-sparse-memory-aliasing,Sparse Resource
Implementation Guidelines>> 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
<<textures-format-conversion,Format Conversion>> and
<<textures-texel-replacement,Texel Replacement>> 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
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section, and in the
<<glossary,Glossary>> 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
<<interfaces-builtin-variables,Built-in Variables>> 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
<<features-extentperimagetype,Allowed Extent Values>> section
(internal issue 343).
* Disallow recursion under SPIR-V entry points in the
<<spirvenv-module-validation,Validation Rules within a Module>>
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.

14
doc/specs/vulkan/Makefile
View File

@ -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

10
doc/specs/vulkan/appendices/glossary.txt
View File

@ -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

1
doc/specs/vulkan/appendices/spirvenv.txt
View File

@ -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*

10
doc/specs/vulkan/chapters/clears.txt
View File

@ -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 <<clears-values,Clear Values>> 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

70
doc/specs/vulkan/chapters/extensions.txt
View File

@ -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.
====

12
doc/specs/vulkan/chapters/features.txt
View File

@ -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

4
doc/specs/vulkan/chapters/framebuffer.txt
View File

@ -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

32
doc/specs/vulkan/chapters/interfaces.txt
View File

@ -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.

2
doc/specs/vulkan/chapters/shaders.txt
View File

@ -53,7 +53,7 @@ include::../protos/vkCreateShaderModule.txt[]
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> 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[]

12
doc/specs/vulkan/chapters/textures.txt
View File

@ -527,7 +527,8 @@ elink:VkFormat), using the appropriate equations in
<<fundamentals-fp11,Unsigned 11-Bit Floating-Point Numbers>>,
<<fundamentals-fp10,Unsigned 10-Bit Floating-Point Numbers>>,
<<fundamentals-fixedconv,Fixed-Point Data Conversion>>, and
<<textures-sexp-RGB,Shared Exponent to RGB>>.
<<textures-sexp-RGB,Shared Exponent to RGB>>. 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

2
doc/specs/vulkan/validity/protos/vkCmdExecuteCommands.txt
View File

@ -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 <<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

1
doc/specs/vulkan/validity/protos/vkCmdSetBlendConstants.txt
View File

@ -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[]

1
doc/specs/vulkan/validity/protos/vkCmdSetDepthBias.txt
View File

@ -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 <<features-features-depthBiasClamp,depth bias clamping>> feature is not enabled, pname:depthBiasClamp must: be code:0.0
ifndef::doctype-manpage[]
********************************************************************************

1
doc/specs/vulkan/validity/protos/vkCmdSetDepthBounds.txt
View File

@ -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[]

1
doc/specs/vulkan/validity/protos/vkCmdSetLineWidth.txt
View File

@ -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 <<features-features-wideLines,wide lines>> feature is not enabled, pname:lineWidth must: be `1.0`
ifndef::doctype-manpage[]
********************************************************************************

1
doc/specs/vulkan/validity/protos/vkCmdSetScissor.txt
View File

@ -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`

1
doc/specs/vulkan/validity/protos/vkCmdSetStencilCompareMask.txt
View File

@ -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[]

1
doc/specs/vulkan/validity/protos/vkCmdSetStencilReference.txt
View File

@ -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[]

1
doc/specs/vulkan/validity/protos/vkCmdSetStencilWriteMask.txt
View File

@ -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[]

1
doc/specs/vulkan/validity/protos/vkCmdSetViewport.txt
View File

@ -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[]

2
doc/specs/vulkan/validity/protos/vkEndCommandBuffer.txt
View File

@ -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 <<queries-operation-active,active>> during the recording of pname:commandBuffer must: have been made inactive
ifndef::doctype-manpage[]
********************************************************************************

16
src/spec/README
View File

@ -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.

4
src/spec/generator.py
View File

@ -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 @@ class OutputGenerator:
# For typedefs, add (APIENTRY *<name>) around the name and
# use the PFN_cmdnameproc naming convention.
# Done by walking the tree for <proto> 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)

3
src/spec/readme.tex
View File

@ -71,7 +71,7 @@ branch.
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 @@ package names are noted, Ubuntu package names are probably the same).
\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}

32
src/spec/reg.py
View File

@ -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 @@ class Registry:
# Add additional enums defined only in <extension> tags
# to the corresponding core type.
# When seen here, a copy, processed to contain the numeric enum
# value, is added to the corresponding <enums> element, as well
# as adding to the enum dictionary. Also add a 'extnumber'
# attribute containing the extension number.
# When seen here, the <enum> element, processed to contain the
# numeric enum value, is added to the corresponding <enums>
# element, as well as adding to the enum dictionary. It is
# *removed* from the <require> 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 <require> tag, leading
# to the nested loop traversal of <require>/<enum> elements
# below.
#
# This code also adds a 'extnumber' attribute containing the
# extension number, used for enumerant value calculation.
#
# For <enum> 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 @@ class Registry:
# 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 @@ class Registry:
# groupName, 'found, adding element...')
gi = self.groupdict[groupName]
gi.elem.append(enum)
# Remove element from parent <require> 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.')

80
src/spec/vk.xml
View File

@ -101,7 +101,7 @@ maintained in the master branch of the Khronos Vulkan Github project.
<type category="define">// Vulkan 1.0 version number
#define <name>VK_API_VERSION_1_0</name> <type>VK_MAKE_VERSION</type>(1, 0, 0)</type> <!-- The patch version here should never be set to anything other than 0 -->
<type category="define">// Version of this file
#define <name>VK_HEADER_VERSION</name> 15</type>
#define <name>VK_HEADER_VERSION</name> 16</type>
<type category="define">
#define <name>VK_DEFINE_HANDLE</name>(object) typedef struct object##_T* object;</type>
@ -3790,7 +3790,7 @@ maintained in the master branch of the Khronos Vulkan Github project.
<param externsync="true"><type>VkCommandBuffer</type> <name>commandBuffer</name></param>
<validity>
<usage>pname:commandBuffer must: be in the recording state</usage>
<usage>fname:vkEndCommandBuffer mustnot: be called inside a render pass instance</usage>
<usage>If pname:commandBuffer is a primary command buffer, there mustnot: be an active render pass instance</usage>
<usage>All queries made &lt;&lt;queries-operation-active,active&gt;&gt; during the recording of pname:commandBuffer must: have been made inactive</usage>
</validity>
</command>
@ -3823,6 +3823,7 @@ maintained in the master branch of the Khronos Vulkan Github project.
<param><type>uint32_t</type> <name>viewportCount</name></param>
<param len="viewportCount">const <type>VkViewport</type>* <name>pViewports</name></param>
<validity>
<usage>The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_VIEWPORT dynamic state enabled</usage>
<usage>pname:firstViewport must: be less than sname:VkPhysicalDeviceLimits::pname:maxViewports</usage>
<usage>The sum of pname:firstViewport and pname:viewportCount must: be between `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive</usage>
</validity>
@ -3834,6 +3835,7 @@ maintained in the master branch of the Khronos Vulkan Github project.
<param><type>uint32_t</type> <name>scissorCount</name></param>
<param len="scissorCount">const <type>VkRect2D</type>* <name>pScissors</name></param>
<validity>
<usage>The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_SCISSOR dynamic state enabled</usage>
<usage>pname:firstScissor must: be less than sname:VkPhysicalDeviceLimits::pname:maxViewports</usage>
<usage>The sum of pname:firstScissor and pname:scissorCount must: be between `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive</usage>
<usage>The pname:x and pname:y members of pname:offset must: be greater than or equal to `0`</usage>
@ -3846,6 +3848,7 @@ maintained in the master branch of the Khronos Vulkan Github project.
<param externsync="true"><type>VkCommandBuffer</type> <name>commandBuffer</name></param>
<param><type>float</type> <name>lineWidth</name></param>
<validity>
<usage>The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_LINE_WIDTH dynamic state enabled</usage>
<usage>If the &lt;&lt;features-features-wideLines,wide lines&gt;&gt; feature is not enabled, pname:lineWidth must: be `1.0`</usage>
</validity>
</command>
@ -3856,6 +3859,7 @@ maintained in the master branch of the Khronos Vulkan Github project.
<param><type>float</type> <name>depthBiasClamp</name></param>
<param><type>float</type> <name>depthBiasSlopeFactor</name></param>
<validity>
<usage>The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_DEPTH_BIAS dynamic state enabled</usage>
<usage>If the &lt;&lt;features-features-depthBiasClamp,depth bias clamping&gt;&gt; feature is not enabled, pname:depthBiasClamp must: be code:0.0</usage>
</validity>
</command>
@ -3863,6 +3867,9 @@ maintained in the master branch of the Khronos Vulkan Github project.
<proto><type>void</type> <name>vkCmdSetBlendConstants</name></proto>
<param externsync="true"><type>VkCommandBuffer</type> <name>commandBuffer</name></param>
<param>const <type>float</type> <name>blendConstants</name>[4]</param>
<validity>
<usage>The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS dynamic state enabled</usage>
</validity>
</command>
<command queues="graphics" renderpass="both" cmdbufferlevel="primary,secondary">
<proto><type>void</type> <name>vkCmdSetDepthBounds</name></proto>
@ -3870,6 +3877,7 @@ maintained in the master branch of the Khronos Vulkan Github project.
<param><type>float</type> <name>minDepthBounds</name></param>
<param><type>float</type> <name>maxDepthBounds</name></param>
<validity>
<usage>The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS dynamic state enabled</usage>
<usage>pname:minDepthBounds must: be between `0.0` and `1.0`, inclusive</usage>
<usage>pname:maxDepthBounds must: be between `0.0` and `1.0`, inclusive</usage>
</validity>
@ -3879,18 +3887,27 @@ maintained in the master branch of the Khronos Vulkan Github project.
<param externsync="true"><type>VkCommandBuffer</type> <name>commandBuffer</name></param>
<param><type>VkStencilFaceFlags</type> <name>faceMask</name></param>
<param><type>uint32_t</type> <name>compareMask</name></param>
<validity>
<usage>The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK dynamic state enabled</usage>
</validity>
</command>
<command queues="graphics" renderpass="both" cmdbufferlevel="primary,secondary">
<proto><type>void</type> <name>vkCmdSetStencilWriteMask</name></proto>
<param externsync="true"><type>VkCommandBuffer</type> <name>commandBuffer</name></param>
<param><type>VkStencilFaceFlags</type> <name>faceMask</name></param>
<param><type>uint32_t</type> <name>writeMask</name></param>
<validity>
<usage>The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK dynamic state enabled</usage>
</validity>
</command>
<command queues="graphics" renderpass="both" cmdbufferlevel="primary,secondary">
<proto><type>void</type> <name>vkCmdSetStencilReference</name></proto>
<param externsync="true"><type>VkCommandBuffer</type> <name>commandBuffer</name></param>
<param><type>VkStencilFaceFlags</type> <name>faceMask</name></param>
<param><type>uint32_t</type> <name>reference</name></param>
<validity>
<usage>The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled</usage>
</validity>
</command>
<command queues="graphics,compute" renderpass="both" cmdbufferlevel="primary,secondary">
<proto><type>void</type> <name>vkCmdBindDescriptorSets</name></proto>
@ -4466,14 +4483,14 @@ maintained in the master branch of the Khronos Vulkan Github project.
<param externsync="true"><type>VkCommandBuffer</type> <name>commandBuffer</name></param>
<param><type>VkSubpassContents</type> <name>contents</name></param>
<validity>
<usage>The current subpass index must: be less than the number of subpasses in the render pass minus one</usage>
<usage>The current subpass index must: be less than the number of subpasses in the render pass minus one</usage>
</validity>
</command>
<command queues="graphics" renderpass="inside" cmdbufferlevel="primary">
<proto><type>void</type> <name>vkCmdEndRenderPass</name></proto>
<param externsync="true"><type>VkCommandBuffer</type> <name>commandBuffer</name></param>
<validity>
<usage>The current subpass index must: be equal to the number of subpasses in the render pass minus one</usage>
<usage>The current subpass index must: be equal to the number of subpasses in the render pass minus one</usage>
</validity>
</command>
<command queues="transfer,graphics,compute" renderpass="both" cmdbufferlevel="primary">
@ -4491,7 +4508,7 @@ maintained in the master branch of the Khronos Vulkan Github project.
<usage>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</usage>
<usage>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</usage>
<usage>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 &lt;&lt;renderpass-compatibility&gt;&gt;</usage>
<usage>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</usage>
<usage>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</usage>
<usage>If the &lt;&lt;features-features-inheritedQueries,inherited queries&gt;&gt; feature is not enabled, pname:commandBuffer mustnot: have any queries &lt;&lt;queries-operation-active,active&gt;&gt;</usage>
<usage>If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query &lt;&lt;queries-operation-active,active&gt;&gt;, then each element of pname:pCommandBuffers must: have been recorded with sname:VkCommandBufferInheritanceInfo::pname:occlusionQueryEnable set to ename:VK_TRUE</usage>
<usage>If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query &lt;&lt;queries-operation-active,active&gt;&gt;, 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</usage>
@ -4795,9 +4812,8 @@ maintained in the master branch of the Khronos Vulkan Github project.
<proto><type>void</type> <name>vkCmdDebugMarkerEndEXT</name></proto>
<param><type>VkCommandBuffer</type> <name>commandBuffer</name></param>
<validity>
<usage>There must: be an outstanding flink:vkCmdDebugMarkerBeginEXT command prior to the fname:vkCmdDebugMarkerEndEXT on the queue that pname:commandBuffer is submitted to.</usage>
<usage>If the matching flink:vkCmdDebugMarkerBeginEXT command was in a secondary command buffer, the fname:vkCmdDebugMarkerEndEXT must be in the same pname:commandBuffer.</usage>
<usage>There must: be an outstanding flink:vkCmdDebugMarkerBeginEXT command prior to the fname:vkCmdDebugMarkerEndEXT on the queue that pname:commandBuffer is submitted to.</usage>
<usage>If the matching flink:vkCmdDebugMarkerBeginEXT command was in a secondary command buffer, the fname:vkCmdDebugMarkerEndEXT must be in the same pname:commandBuffer.</usage>
</validity>
</command>
<command queues="graphics,compute" renderpass="both" cmdbufferlevel="primary,secondary">
@ -5260,16 +5276,16 @@ maintained in the master branch of the Khronos Vulkan Github project.
<enum value="&quot;VK_AMD_extension_4&quot;" name="VK_AMD_EXTENSION_4_EXTENSION_NAME"/>
</require>
</extension>
<extension name="VK_AMD_extension_5" number="21" author="AMD" contact="Daniel Rakos @aqnuep" supported="disabled">
<extension name="VK_AMD_shader_trinary_minmax" number="21" author="AMD" contact="quentin.lin@amd.com" supported="vulkan">
<require>
<enum value="0" name="VK_AMD_EXTENSION_5_SPEC_VERSION"/>
<enum value="&quot;VK_AMD_extension_5&quot;" name="VK_AMD_EXTENSION_5_EXTENSION_NAME"/>
<enum value="1" name="VK_AMD_SHADER_TRINARY_MINMAX_SPEC_VERSION"/>
<enum value="&quot;VK_AMD_shader_trinary_minmax&quot;" name="VK_AMD_SHADER_TRINARY_MINMAX_EXTENSION_NAME"/>
</require>
</extension>
<extension name="VK_AMD_extension_6" number="22" author="AMD" contact="Daniel Rakos @aqnuep" supported="disabled">
<extension name="VK_AMD_shader_explicit_vertex_parameter" number="22" author="AMD" contact="quentin.lin@amd.com" supported="vulkan">
<require>
<enum value="0" name="VK_AMD_EXTENSION_6_SPEC_VERSION"/>
<enum value="&quot;VK_AMD_extension_6&quot;" name="VK_AMD_EXTENSION_6_EXTENSION_NAME"/>
<enum value="1" name="VK_AMD_SHADER_EXPLICIT_VERTEX_PARAMETER_SPEC_VERSION"/>
<enum value="&quot;VK_AMD_shader_explicit_vertex_parameter&quot;" name="VK_AMD_SHADER_EXPLICIT_VERTEX_PARAMETER_EXTENSION_NAME"/>
</require>
</extension>
<extension name="VK_EXT_debug_marker" number="23" author="Baldur Karlsson" contact="baldurk@baldurk.org" supported="vulkan">
@ -5301,10 +5317,40 @@ maintained in the master branch of the Khronos Vulkan Github project.
<enum value="&quot;VK_AMD_extension_8&quot;" name="VK_AMD_EXTENSION_8_EXTENSION_NAME"/>
</require>
</extension>
<extension name="VK_AMD_extension_9" number="26" author="AMD" contact="Daniel Rakos @aqnuep" supported="disabled">
<extension name="VK_AMD_gcn_shader" number="26" author="AMD" contact="dominik.witczak@amd.com" supported="vulkan">
<require>
<enum value="0" name="VK_AMD_EXTENSION_9_SPEC_VERSION"/>
<enum value="&quot;VK_AMD_extension_9&quot;" name="VK_AMD_EXTENSION_9_EXTENSION_NAME"/>
<enum value="1" name="VK_AMD_GCN_SHADER_SPEC_VERSION"/>
<enum value="&quot;VK_AMD_gcn_shader&quot;" name="VK_AMD_GCN_SHADER_EXTENSION_NAME"/>
</require>
</extension>
<extension name="VK_NV_extension_27" number="27" author="NVIDIA" contact="Jeff Bolz @jbolz" supported="disabled">
<require>
<enum value="0" name="VK_NV_EXTENSION_27_SPEC_VERSION"/>
<enum value="&quot;VK_NV_extension_27&quot;" name="VK_NV_EXTENSION_27_EXTENSION_NAME"/>
</require>
</extension>
<extension name="VK_EXT_extension_28" number="28" author="NVIDIA" contact="Piers Daniell @pdaniell" supported="disabled">
<require>
<enum value="0" name="VK_EXT_EXTENSION_28_SPEC_VERSION"/>
<enum value="&quot;VK_NV_extension_28&quot;" name="VK_EXT_EXTENSION_28_EXTENSION_NAME"/>
</require>
</extension>
<extension name="VK_NVX_extension_29" number="29" author="NVIDIA" contact="Jeff Juliano @jjuliano" supported="disabled">
<require>
<enum value="0" name="VK_NVX_EXTENSION_29_SPEC_VERSION"/>
<enum value="&quot;VK_NVX_extension_29&quot;" name="VK_NVX_EXTENSION_29_EXTENSION_NAME"/>
</require>
</extension>
<extension name="VK_NVX_extension_30" number="30" author="NVIDIA" contact="Jeff Juliano @jjuliano" supported="disabled">
<require>
<enum value="0" name="VK_NVX_EXTENSION_30_SPEC_VERSION"/>
<enum value="&quot;VK_NVX_extension_30&quot;" name="VK_NVX_EXTENSION_30_EXTENSION_NAME"/>
</require>
</extension>
<extension name="VK_NVX_extension_31" number="31" author="NVIDIA" contact="Jeff Juliano @jjuliano" supported="disabled">
<require>
<enum value="0" name="VK_NVX_EXTENSION_31_SPEC_VERSION"/>
<enum value="&quot;VK_NVX_extension_31&quot;" name="VK_NVX_EXTENSION_31_EXTENSION_NAME"/>
</require>
</extension>
</extensions>

17
src/vulkan/vulkan.h
View File

@ -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
@ -3855,6 +3855,16 @@ typedef struct VkPipelineRasterizationStateRasterizationOrderAMD {
#define VK_AMD_shader_trinary_minmax 1
#define VK_AMD_SHADER_TRINARY_MINMAX_SPEC_VERSION 1
#define VK_AMD_SHADER_TRINARY_MINMAX_EXTENSION_NAME "VK_AMD_shader_trinary_minmax"
#define VK_AMD_shader_explicit_vertex_parameter 1
#define VK_AMD_SHADER_EXPLICIT_VERTEX_PARAMETER_SPEC_VERSION 1
#define VK_AMD_SHADER_EXPLICIT_VERTEX_PARAMETER_EXTENSION_NAME "VK_AMD_shader_explicit_vertex_parameter"
#define VK_EXT_debug_marker 1
#define VK_EXT_DEBUG_MARKER_SPEC_VERSION 3
#define VK_EXT_DEBUG_MARKER_EXTENSION_NAME "VK_EXT_debug_marker"
@ -3912,6 +3922,11 @@ VKAPI_ATTR void VKAPI_CALL vkCmdDebugMarkerInsertEXT(
VkDebugMarkerMarkerInfoEXT* pMarkerInfo);
#endif
#define VK_AMD_gcn_shader 1
#define VK_AMD_GCN_SHADER_SPEC_VERSION 1
#define VK_AMD_GCN_SHADER_EXTENSION_NAME "VK_AMD_gcn_shader"
#ifdef __cplusplus
}
#endif