2016-02-16 09:53:44 +00:00
|
|
|
Vulkan API Documentation Project
|
|
|
|
|
================================
|
|
|
|
|
|
|
|
|
|
This repository contains formal documentation of the Vulkan API. This
|
|
|
|
|
includes the main API Specification, the reference (man) pages, the XML API
|
|
|
|
|
Registry, and related tools and scripts.
|
|
|
|
|
|
2016-08-28 10:47:19 +00: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 09:53:44 +00: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-11 01:33:02 +00:00
|
|
|
README.md This file
|
|
|
|
|
ChangeLog.txt Change log summary
|
2016-02-16 09:53:44 +00: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 10:47:19 +00:00
|
|
|
man/ Reference (manual) pages for API, mostly extracted from the spec source
|
2016-02-16 09:53:44 +00: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 :
|
|
|
|
|
|
|
|
|
|
* make xhtml - Build one large HTML specification document.
|
|
|
|
|
* make pdf - Build one large PDF specification document.
|
|
|
|
|
* make chunked - Build an HTML document broken into one file per chapter.
|
|
|
|
|
* 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 manpages - Make man pages as nroff Unix-style (real) man pages.
|
|
|
|
|
* 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 10:47:19 +00: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 09:53:44 +00: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 10:47:19 +00: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 09:53:44 +00:00
|
|
|
|
2016-08-28 10:47:19 +00:00
|
|
|
The other generated files are built as required via dependencies in
|
|
|
|
|
doc/specs/vulkan/Makefile .
|