8c3c9b4c85
* Bump API patch number and header version number to 7 for this
update.
Github Issues:
* Fix slink:VkSpecializationMapEntry example to avoid C/C++ strict
aliasing issues (public issue 14).
* Clarify the meaning of "matching" in flink:vkCmdBindDescriptorSets
validity language (public issue 33).
* Add stub reference pages so xrefs to not-yet-written pages don't
generate 404 errors. However, the actual content of these pages
still needs to be filled in as time allows (public issue 44, but
does not close that issue out).
* Remove incorrect validity statement for
flink:vkGetImageSparseMemoryRequirements (public issue 85).
* Reword the
<<features-limits-bufferImageGranularity,bufferImageGranularity>>
feature in terms of "aliasing", and clarify that it applies to
bindings in the same memory object (public issue 90).
* Clarify the relationship of the slink:VkPhysicalDeviceLimits
pname:maxViewportDimensions and pname:viewportBoundsRange limits
(public issue 92).
* Specify sparse unbound texture replacement in the
<<textures-texel-replacement,Texel Replacement>> section
independently of robust buffer access language (public issue 100).
* Add the <<fundamentals-architecture-model,Architecture Model>>
section to explain architecture constraints Vulkan has chosen to
accept in order to enable portable and performant code (public issue
122).
* State that an object must not be destroyed until *all* (not *any*)
uses of that object have completed (public issue 123).
* Minor editorial cleanup (public issues 129, 134, 146, 148).
* Add validity language for layer and extension names to
slink:VkDeviceCreateInfo matching that used for
slink:VkInstanceCreateInfo (public issue 130).
* Clean up terminology for the case when the bits set in one bitmask
are a subset of the bits set in another bitmask (public issue 138).
* Document that input attachments are UniformConstant not Input, in
the <<interfaces-inputattachment,Fragment Input Attachment
Interface>> section (public glslang bug 169).
Internal Issues:
* Add max enum values to "flag bits" enums (internal issue #136).
* Clarify language around the various uses of the term "block" in the
<<appendix-compressedtex-bc,Block Compressed Image Formats>> section
(internal issue #202).
* Removed "expand" dependency from <enums> groups in vk.xml and added
auto-generation code in the scripts to infer it instead, to ensure
consistency. This caused renaming of sname:VkColorSpaceKHR and
sname:VkPresentModeKHR etext:BEGIN_RANGE (etc.) tokens, but those
tokens are metadata, not part of the API, and the Vulkan WG is OK
with this change. This change adds ranges to two additional enums
that were missing them due to not defining the "expand" attribute
(internal issue 217).
* Tweak makefile to generate ref page nroff (.3) files in the right
output directory, working around an a2x limitation (internal issue
223).
Other Commits:
* Add validity requirements for flink:vkCmdCopyQueryPoolResults
pname:dstBuffer parameter.
* Fix ref page build to generate .3 targets in the right output
directory.
|
||
|---|---|---|
| doc/specs | ||
| out | ||
| src | ||
| .gitignore | ||
| 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.
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
enums/ Includeable snippets for enumerations from vk.xml
flags/ Includeable snippets for flags from vk.xml
protos/ Includeable snippets for prototypes from vk.xml
structs/ Includeable snippets for structures from vk.xml
validity/ Includeable validity language from vk.xml
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 a2x (part of the asciidoc) package, dblatex and a LaTeX processor. The PDF builds are currently configured to use a2x 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). All the generated files are checked into the repository, and should not be modified directly. If you change vk.xml, you can regenerated these files by going to src/spec and running:
- make clobber (get rid of all old generated files)
- make full_install (regenerate all the files)