348990517c
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
|
||
|---|---|---|
| doc/specs | ||
| out | ||
| src | ||
| .gitignore | ||
| COPYING.md | ||
| ChangeLog.txt | ||
| README.md | ||
README.md
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.
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.
Repository Structure
README.md This file
ChangeLog.txt Change log summary
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)
man/ Reference (manual) pages for API, mostly extracted from the spec source
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.
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 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 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
The other generated files are built as required via dependencies in doc/specs/vulkan/Makefile .