mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-19 09:47:19 +00:00
b7b1c3a65d
* Bump API patch number and header version number to 67 for this update.
* Update copyright dates to 2018
Github Issues:
* Fix texture lookup functions in `GL_KHR_vulkan_glsl` specification
(public pull request 363).
* Clarify the state waited semaphores are left in when a call to
flink:vkQueuePresentKHR fails (public issue 572).
* Cleanup descriptions of slink:VkObjectTablePushConstantEntryNVX and
slink:VkObjectTableDescriptorSetEntryNVX (public issue 583)
* Remove redundant flink:vkCmdSetDiscardRectangleEXT valid usage
statements (public pull 586).
* Make dynamic state array length valid usage statements implicit for
flink:vkCmdSetViewportWScalingNV, flink:vkCmdSetDiscardRectangleEXT, and
flink:vkCmdSetViewport (public pull 589).
* Clarify meaning of window extent (0,0) in slink:VkSwapchainKHR for the
Windows and X11 platforms, in their respective extensions (public issue
590).
* Allow flink:vkGetPastPresentationTimingGOOGLE to return
ename:VK_INCOMPLETE (public issue 604).
* Add synchronization valid usage statements to flink:vkAcquireNextImage
(public pull 611).
* Fix some broken external links and internal xrefs (public pull 613).
* Clean up slink:VkViewport valid usage statements in the presence or
absence of relevant extensions (public pull 623).
* Remove
ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR
token from VK_KHR_maintenance2 from the non-extension VU path for
slink:VkGraphicsPipelineCreateInfo (public issue 628).
* Miscellaneous minor markup fixes - extension name strings (public pull
631), Notes (pull 633), queue names emitted by generator scripts (pull
634), block formatting in slink:VkDescriptorUpdateTemplateEntryKHR (pull
635), ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG (pull
641), quotes and apostrophes (pull 643),
* Miscellaneous minor grammar fixes (public pull 644).
* Fix markup macros so usage like ptext:*Src* works (public pull 647).
Internal Issues:
* Clarify in the `VK_KHR_surface` and `VK_KHR_swapchain` extensions that
parameter combinations which aren't supported for normal images are also
unsupported for presentable images, even if the parameter values are
individually supported as reported by the surface capability queries
(internal issue 1029).
* Fixed XML typo in the valid value field of the pname:sType member of
slink:VkPhysicalDeviceExternalMemoryHostPropertiesEXT (internal issue
1100).
Other Issues:
* Add memory semantics validity rules to the <<spirvenv-module-validation,
Validation Rules within a Module>> section of the SPIR-V environment
appendix, and specify that sequentiality consistency is not supported.
This forbids certain cases like "`Load+Release`" that we don't expect to
ever be meaningful.
* Document mapping of OpenGL Shading Language barriers to SPIR-V scope and
semantics in the `GL_KHR_vulkan_glsl` specification.
New Extensions:
* `VK_EXT_conservative_rasterization`
129 lines
4.4 KiB
Plaintext
129 lines
4.4 KiB
Plaintext
// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
[appendix]
|
|
[[appendix-vuid]]
|
|
= Valid Usage ID Tags
|
|
|
|
Valid usage statements in the published Vulkan Specification must all be
|
|
given _Valid Usage ID_ or _VUID_ tags.
|
|
These tags are asciidoc anchors, intended for use by the validation layer to
|
|
provide unique names for each validation condition, and a way to link from
|
|
validation layer reports into the corresponding parts of the Specification.
|
|
|
|
|
|
== Format of VUID Tags
|
|
|
|
For implicit valid usage statements, the tags are formatted like this:
|
|
|
|
[source,asciidoc]
|
|
----
|
|
[[VUID-blockname-paramname-category]]
|
|
----
|
|
|
|
_blockname_ is the name of the function or structure for which a valid usage
|
|
statement is being generated.
|
|
|
|
_paramname_ is the name of the parameter being validated.
|
|
In some cases, the statement does not validate a single parameter and this
|
|
portion of the tag is absent.
|
|
|
|
_category_ is the type of statement being generated.
|
|
There are over one dozen types referring to distinct conditions such as
|
|
valid objects, required bitmasks, required array lengths, constraints on
|
|
parent objects, and so on.
|
|
|
|
For explicit valid usage statements, the tags are formatted like this:
|
|
|
|
[source,asciidoc]
|
|
----
|
|
[[VUID-blockname-paramname-number]]
|
|
----
|
|
|
|
_blockname_ is the name of the function or structure for which a valid usage
|
|
statement is being generated.
|
|
|
|
_paramname_ is the name of the parameter being validated.
|
|
In some cases, the statement does not validate a single parameter and this
|
|
portion of the tag is replaced by `-None-`
|
|
|
|
_number_ is a unique five digit, zero-filled number used to disambiguate
|
|
similar tag names.
|
|
|
|
|
|
== Creating VUID Tags
|
|
|
|
For implicit valid usage statements generated automatically from `vk.xml`,
|
|
VUID tags are created automatically by the generator scripts.
|
|
|
|
For explicit valid usage statements, VUID tags are generated by passing
|
|
appropriate options to the script `doc/specs/vulkan/reflow.py`.
|
|
|
|
Since these tags are of use only to the published validation layer, they are
|
|
needed only in the published Specification sources and outputs.
|
|
Therefore, authors of extensions, or other branches adding valid usage
|
|
statements, are not themselves responsible for adding tags in their
|
|
branches.
|
|
The specification editors will take care of this as part of the process of
|
|
publishing updates.
|
|
For reference purposes, this process is described below:
|
|
|
|
First, after integrating all new specification language into the internal
|
|
gitlab branch which contains the canonical Specification source, invoke the
|
|
following command in `doc/specs/vulkan`:
|
|
|
|
[source,sh]
|
|
----
|
|
python3 reflow.py -overwrite -noflow -tagvu chapters/*.txt chapters/*/*.txt
|
|
----
|
|
|
|
This will add VUID tags to all statements in valid usage blocks which don't
|
|
already have them.
|
|
Some diagnostics will be reported, but these are do not in general require
|
|
any action.
|
|
After updating all files, the script will print out a final line like:
|
|
|
|
[source,sh]
|
|
----
|
|
WARN: You must now edit the value of reflow.py:startVUID to 1376 so that future runs will not overwrite existing VUID tags
|
|
----
|
|
|
|
Second, after verifying the updates are correct using e.g. `git diff`, edit
|
|
`reflow.py` and edit the definition of the variable startVUID as directed:
|
|
|
|
[source,python]
|
|
----
|
|
# The value to start tagging VU statements at, unless overridden by -nextvu
|
|
startVUID = 1376
|
|
----
|
|
|
|
Commit the updated source files and `reflow.py` together.
|
|
The next time the script is run, VUID tags will be assigned numbers starting
|
|
from the current startVUID value.
|
|
|
|
|
|
== Updating VUID Tags When Valid Usage Statements Change
|
|
|
|
Valid usage statements have corresponding tests in the Vulkan Validation
|
|
Layer.
|
|
The tests must be changed in response to semantic changes in the VU
|
|
statements, whether for bug-fixing, adding extension interactions, or
|
|
otherwise.
|
|
The rule used when updating explicit VU statements is that the merge request
|
|
or pull request responsible for making the change must remove the existing
|
|
VUID tag, so that a new one can be assigned, _except_ in the following
|
|
cases:
|
|
|
|
* The changes are non-semantic, such as using consistent phrasing or
|
|
markup.
|
|
* The changes consist of changing `KHX` to `KHR` suffixes when promoting a
|
|
Khronos-defined extension.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
This section may need further modification in response to guidelines agreed
|
|
to by the Vulkan Working Group.
|
|
====
|