107 lines
4.3 KiB
Markdown
107 lines
4.3 KiB
Markdown
|
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
|
||
|
|
--------------------
|
||
|
|
|
||
|
|
```
|
||
|
|
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)
|