Change log for January 23, 2017 Vulkan 1.0.39 spec update:
* Bump API patch number and header version number to 39 for this update.
Github Issues:
* Clarified that only accesses via the specified buffer/image subresource
ranges are included in the access scopes (public issue 306).
* Add missing valid usage statements for flink:vkCreateComputePipelines
and flink:vkCreateGraphicsPipelines (public issue 427).
Internal Issues:
* Add a Note to the <<invariance,Invariance>> appendix about a difference
between OpenGL and Vulkan with regards to how primitives derived from
offsets are handled (internal issue 355).
* Add the +<<VK_KHR_get_physical_device_properties2>>+,
+<<VK_KHR_maintenance1>>+, and +<<VK_KHR_shader_draw_parameters>>+
extensions (internal issue 448).
* Add the +<<VK_EXT_shader_subgroup_vote>>+ and
+<<VK_EXT_shader_subgroup_ballot>>+ extensions (internal issue 449).
* Update the texture level-of-detail equation in the
<<textures-scale-factor,Scale Factor Operation>> section to better
approximate the ellipse major and minor axes (internal issue 547).
* Forbid non-explicitly allowed uses of interface decorations in the
introduction to the <<interfaces,Shader Interfaces>> chapter (internal
issue 607).
* Replace use of MathJax with KaTeX, for improved load-time performance as
well as avoiding the scrolling-and-scrolling behavior due to MathJax
asynchronous rendering when loading at an anchor inside the spec. This
change also requires moving to HTML5 output for the spec instead of
XHTML, and there is a visible difference in that the chapter navigation
index is now in a scrollable sidebar instead of at the top of the
document. We may or may not retain the nav sidebar based on feedback
(internal issue 613).
* Improve consistency of markup and formatting in extension appendices
(internal issue 631).
Other Issues:
* Add explicit valid usage statements to slink:VkImageCopy requiring that
the source and destination layer ranges be contained in their respective
source and destination images.
* Add valid usage language for swapchain of flink:vkAcquireNextImage. If
the swapchain has been replaced, then it should not be passed to
flink:vkAcquireNextImage.
* Add a valid usage statement to flink:vkCreateImageView, that the image
must have been created with an appropriate usage bit set.
* Noted that slink:VkDisplayPresentInfoKHR is a valid extension of
slink:VkPresentInfoKHR in the <<wsi_swapchain,WSI Swapchain>> section.
* Update valid usage for flink:vkCmdSetViewport and flink:vkCmdSetScissor
to account for the multiple viewport feature. If the feature is not
enabled, the parameters for these functions have required values that
are defined in the <<features-features-multiViewport,multiple
viewports>> section of the spec but were not reflected in the valid
usage text for these functions.
* Add the +<<VK_EXT_swapchain_colorspace>>+ extension defining common
color spaces.
2017-01-17 20:11:25 -08:00
|
|
|
Vulkan<sup>:registered:</sup> API Documentation Project
|
|
|
|
|
=======================================================
|
2016-02-16 01:53:44 -08:00
|
|
|
|
|
|
|
|
This repository contains formal documentation of the Vulkan API. This
|
|
|
|
|
includes the main API Specification, the reference (man) pages, the XML API
|
|
|
|
|
Registry, and related tools and scripts.
|
|
|
|
|
|
2016-08-28 03:47:19 -07:00
|
|
|
Single-Branch Model
|
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
|
|
As of the 1.0.25 release, we have switch to a new 'single-branch' model in
|
|
|
|
|
which all extensions are included in the source of the 1.0 branch of the
|
|
|
|
|
Specification, and can be configured in or out of the build using Makefile
|
|
|
|
|
options.
|
|
|
|
|
|
|
|
|
|
The single-branch model seems to be working for all the spec builds,
|
|
|
|
|
although there are probably a few issues we haven't caught yet. The ref page
|
|
|
|
|
build needs some additional work, as genRef.py is creating reference pages
|
|
|
|
|
for all interfaces, not just those for the API and extensions being built,
|
|
|
|
|
and we'll get to that within a week or two. The validation scripts also need
|
|
|
|
|
to be tweaked further for the single-branch model.
|
|
|
|
|
|
2016-02-16 01:53:44 -08:00
|
|
|
Repository Structure
|
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
|
|
```
|
Change log for March 10, 2016 Vulkan 1.0.6 spec update:
* Bump API patch number and header version number to 6 for this
update.
Github Issues:
* Define 'invocation group' for compute and graphics shaders. Cleanup
definition and use of 'workgroup', and add glossary entries (public
issue 1).
* Various minor editorial fixes (public issue 33).
* Clarify locations for block members in the
<<interfaces-iointerfaces-locations,Location Assignment>>
section (public issue 45).
* Editorial fixes for <<commandbuffer-allocation,Command Buffer
Allocation>> section (public issues 54, 59).
* Clarify behavior of depth test in the <<fragops-depth,Depth
Test>> section (public issues 80, 81).
* Remove discussion of return codes from
flink:vkGetPhysicalDeviceSparseImageFormatProperties and
flink:vkGetImageSparseMemoryRequirements, which don't return values
(public issue 82).
* Allow flink:vkCmdDrawIndirect and flink:vkCmdDrawIndexedIndirect
pname:drawCount of 0, as well as 1, when the multiDrawIndirect
feature is not supported (public issue 88).
* Remove confusing wording in the <<features-limits,Limits>>
section describing the slink:VkPhysicalDeviceLimits
pname:minTexelBufferOffsetAlignment,
pname:minUniformBufferOffsetAlignment, and
pname:minStorageBufferOffsetAlignment members as both minimums and
maximums (public issue 91).
* Clarified that only the RGB components should be affected in places
where sRGB is referred to in the spec, such as ASTC formats. Minor
re-wording to avoid "color space" when actively incorrect, now that
we refer to the Data Format Spec which actually makes a distinction
between color space and transfer function (public issue 94).
* Treat pname:pPropertyCount == 0 consistently in
flink:vkEnumerateInstanceLayerProperties and
flink:vkEnumerateDeviceLayerProperties (public issue 99)
* Cleanup minor editorial issues in chapters 14-17 (public issue 100).
* Clarify definition of flink:vkEnumerateInstanceExtensionProperties
and flink:vkEnumerateDeviceExtensionProperties (public issue 101).
* Define the flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties pname:pLayerName
parameter to be a pointer to a null-terminated UTF-8 string (public
issue 101).
* Rearrange "Missing information" references in mandatory format
tables (public issue 101).
* Clarify that the enumerated extensions returned by
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties will only include
extensions provided by the platform or extensions implemented in
implicitly enabled layers (public issue 101).
* Miscellaneous editorial fixes. Include the Vulkan spec patch number
in the PDF title. Fix label on <<fig-non-strict-lines,Non
strict lines>> diagram. Use more easily distinguished symbols in
tables in the <<features-required-format-support,Required
Format Support>> section. Don't require FQDNs used as layer names be
encoded in lower case if not possible, in the
<<extensions-naming-conventions, Extension and Layer Naming
Conventions>> section (public issues 101, 119, 121).
Internal Issues:
* Fixed excessive spacing in tables in XHTML (internal issue 18).
* Clarify that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
applies to secondary command buffers. Previously spec only referred
to the members of pname:pCommandBuffers being affected by this bit.
Added a separate slink:VkSubmitInfo Valid Usage restriction
specifying that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
also applies to any secondary command buffers that are recorded into
the primary command buffers in pname:pCommandBuffers (internal issue
106).
* Clarify that slink:VkDeviceCreateInfo::pname:pEnabledFeatures can be
NULL (internal issue 117).
* Remove "the value of" where it is redundant (e.g. speaking of an API
parameter, struct member, or SPIR-V variable, but not when speaking
of color components) (internal issue 175).
* Forced patch version to always be 0 in the header. Add a
"VK_API_VERSION_<major>_<minor>" macro for people to use to do the
right thing. Add a VK_HEADER_VERSION which captures the header
release number independent of the spec patch number (internal issue
176).
* Correct description of
slink:VkPipelineShaderStageCreateInfo::pname:pName to "a pointer to
a null-terminated UTF-8 string" (internal issue #197).
Other Commits:
* Updated DataFormat spec reference to the new date for revision 5 of
that spec.
* Fixed KEEP option (to retain LaTeX intermediate files) in the
Makefile to be included when edited there, as well as set on the
command line.
* Reserve and add "VK_IMG_filter_cubic" to the registry, and implement
script functionality to add and remove validity from existing
functions. Includes schema and readme changes.
* Update GL_KHR_vulkan_glsl so push_constants do not have descriptor
sets.
2016-03-10 17:33:02 -08:00
|
|
|
README.md This file
|
|
|
|
|
ChangeLog.txt Change log summary
|
2016-02-16 01:53:44 -08:00
|
|
|
doc/specs/ Main documentation tree
|
|
|
|
|
vulkan/ Vulkan specification
|
|
|
|
|
appendices/ Appendices - one file each
|
|
|
|
|
chapters/ Chapters - one file each
|
|
|
|
|
config/ asciidoc configuration
|
|
|
|
|
images/ Images (figures, diagrams, icons)
|
2016-08-28 03:47:19 -07:00
|
|
|
man/ Reference (manual) pages for API, mostly extracted from the spec source
|
2016-02-16 01:53:44 -08:00
|
|
|
misc/ Related specifications (GL_KHR_vulkan_glsl)
|
|
|
|
|
src/spec/ XML API Registry (vk.xml) and related scripts
|
|
|
|
|
src/vulkan/ Vulkan headers, generated from the Registry
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Building the Specification and Reference Pages
|
|
|
|
|
----------------------------------------------
|
|
|
|
|
|
|
|
|
|
To build the documents, you need to install, at a minimum:
|
|
|
|
|
|
|
|
|
|
* GNU-compatible make
|
|
|
|
|
* asciidoc (http://www.methods.co.nz/asciidoc/)
|
|
|
|
|
|
|
|
|
|
On some systems/build targets you may also need:
|
|
|
|
|
|
|
|
|
|
* dblatex
|
|
|
|
|
* source-highlight
|
|
|
|
|
|
|
|
|
|
These tools are known to work on several varieties of Linux, MacOS X, and
|
|
|
|
|
Cygwin running under Microsoft Windows.
|
|
|
|
|
|
|
|
|
|
There are several make targets in doc/specs/vulkan :
|
|
|
|
|
|
Change log for January 23, 2017 Vulkan 1.0.39 spec update:
* Bump API patch number and header version number to 39 for this update.
Github Issues:
* Clarified that only accesses via the specified buffer/image subresource
ranges are included in the access scopes (public issue 306).
* Add missing valid usage statements for flink:vkCreateComputePipelines
and flink:vkCreateGraphicsPipelines (public issue 427).
Internal Issues:
* Add a Note to the <<invariance,Invariance>> appendix about a difference
between OpenGL and Vulkan with regards to how primitives derived from
offsets are handled (internal issue 355).
* Add the +<<VK_KHR_get_physical_device_properties2>>+,
+<<VK_KHR_maintenance1>>+, and +<<VK_KHR_shader_draw_parameters>>+
extensions (internal issue 448).
* Add the +<<VK_EXT_shader_subgroup_vote>>+ and
+<<VK_EXT_shader_subgroup_ballot>>+ extensions (internal issue 449).
* Update the texture level-of-detail equation in the
<<textures-scale-factor,Scale Factor Operation>> section to better
approximate the ellipse major and minor axes (internal issue 547).
* Forbid non-explicitly allowed uses of interface decorations in the
introduction to the <<interfaces,Shader Interfaces>> chapter (internal
issue 607).
* Replace use of MathJax with KaTeX, for improved load-time performance as
well as avoiding the scrolling-and-scrolling behavior due to MathJax
asynchronous rendering when loading at an anchor inside the spec. This
change also requires moving to HTML5 output for the spec instead of
XHTML, and there is a visible difference in that the chapter navigation
index is now in a scrollable sidebar instead of at the top of the
document. We may or may not retain the nav sidebar based on feedback
(internal issue 613).
* Improve consistency of markup and formatting in extension appendices
(internal issue 631).
Other Issues:
* Add explicit valid usage statements to slink:VkImageCopy requiring that
the source and destination layer ranges be contained in their respective
source and destination images.
* Add valid usage language for swapchain of flink:vkAcquireNextImage. If
the swapchain has been replaced, then it should not be passed to
flink:vkAcquireNextImage.
* Add a valid usage statement to flink:vkCreateImageView, that the image
must have been created with an appropriate usage bit set.
* Noted that slink:VkDisplayPresentInfoKHR is a valid extension of
slink:VkPresentInfoKHR in the <<wsi_swapchain,WSI Swapchain>> section.
* Update valid usage for flink:vkCmdSetViewport and flink:vkCmdSetScissor
to account for the multiple viewport feature. If the feature is not
enabled, the parameters for these functions have required values that
are defined in the <<features-features-multiViewport,multiple
viewports>> section of the spec but were not reflected in the valid
usage text for these functions.
* Add the +<<VK_EXT_swapchain_colorspace>>+ extension defining common
color spaces.
2017-01-17 20:11:25 -08:00
|
|
|
* make html - Build one large HTML specification document.
|
2016-02-16 01:53:44 -08:00
|
|
|
* make pdf - Build one large PDF specification document.
|
|
|
|
|
* make manhtml - Make HTML API reference (all man pages as one big file).
|
|
|
|
|
* make manpdf - Make a one-giant PDF API reference.
|
|
|
|
|
* make manhtmlpages - Make man pages as one-file-per-API.
|
|
|
|
|
* make allchecks - Run the validation rules on the specification.
|
|
|
|
|
|
|
|
|
|
The outputs will be written to $(OUTDIR), which defaults to out/ at the root
|
|
|
|
|
of the checked-out git repository.
|
|
|
|
|
|
2016-08-28 03:47:19 -07:00
|
|
|
To build PDF outputs (make pdf, make manpdf), you need
|
|
|
|
|
dblatex and a LaTeX processor. The PDF builds are
|
|
|
|
|
currently configured to use asciidoc to go from asciidoc markdown to docbook, and
|
2016-02-16 01:53:44 -08:00
|
|
|
then run the result through dblatex to go from there to LaTeX and then
|
|
|
|
|
through your LaTeX processor to PDF.
|
|
|
|
|
|
|
|
|
|
Spec Validation
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
There are a couple of validation tools which look for inconsistencies and
|
|
|
|
|
missing material between the specification and ref pages, and the canonical
|
|
|
|
|
description of the API in vk.xml :
|
|
|
|
|
|
|
|
|
|
* checkinc
|
|
|
|
|
* checklinks
|
|
|
|
|
* allchecks - both checkinc and checklinks
|
|
|
|
|
|
|
|
|
|
They are necessarily heuristic since they're dealing with lots of
|
|
|
|
|
hand-written material. To use them you'll also need to install:
|
|
|
|
|
|
|
|
|
|
* python3
|
|
|
|
|
|
|
|
|
|
The '''checkinc''' target uses Unix filters to determine which autogenerated
|
|
|
|
|
API include files are used (and not used) in the spec. It generates several
|
|
|
|
|
output files, but the only one you're likely to care about is
|
|
|
|
|
'''actual.only'''. This is a list of the include files which are *not*
|
|
|
|
|
referenced anywhere in the spec, and probably correspond to undocumented
|
|
|
|
|
material in the spec.
|
|
|
|
|
|
|
|
|
|
The '''checklinks''' target validates the various internal tagged links in
|
|
|
|
|
the man pages and spec (e.g. the '''fname:vkFuncBlah''',
|
|
|
|
|
'''sname:VkStructBlah''', etc.) against the canonical description of the API
|
|
|
|
|
in vk.xml . It generates two output files, manErrs.txt and specErrs.txt,
|
|
|
|
|
which report problematic tags and the filenames/lines on which those tags
|
|
|
|
|
were found.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Generating Headers and Related Files
|
|
|
|
|
------------------------------------
|
|
|
|
|
|
|
|
|
|
The header file (src/vulkan/vulkan.h) and many parts of the specification
|
|
|
|
|
and reference page documents are generated from descriptions in the XML API
|
2016-08-28 03:47:19 -07:00
|
|
|
Registry (src/spec/vk.xml). The generated files, with the exception
|
|
|
|
|
of vulkan.h, are not checked into the repository. If you change vk.xml, you
|
|
|
|
|
can regenerate the header by going to src/spec and running:
|
|
|
|
|
|
|
|
|
|
* make clobber install
|
2016-02-16 01:53:44 -08:00
|
|
|
|
2016-08-28 03:47:19 -07:00
|
|
|
The other generated files are built as required via dependencies in
|
|
|
|
|
doc/specs/vulkan/Makefile .
|