The Vulkan API Specification and related tools
Go to file
Jon Leech 75bbb5f4d5 Change log for April 29, 2016 Vulkan 1.0.12 spec update:
* Bump API patch number and header version number to 12 for this
    update.

Github Issues:

  * Change valid usage statements intended to be "sub-points" to
    be actual sub-points (public issue 66).
  * Replace double negation in description of
    slink:VkRenderPassBeginInfo::pname:pClearValues (based on public
    merge 142).
  * Cleanup minor typos in spec, ref pages and XML, including those
    proposed in public pull requests 144, 150, 151, 167, 168, 181, and
    186.
  * Use *strict subset* in describing the partial order of memory
    property types for slink:VkMemoryType, and update the style guide
    accordingly (public issue 190).
  * Fix various "a image" -> "an image" typos (public issue 191).
  * Note in the <<fundamentals-validusage,Valid Usage>> and
    <<extensions-interactions,Extension Interactions>> sections that
    structures defined by extensions which may be passed in structure
    chains using the ptext:pNext member must: include initial
    ptext:sType and ptext:pNext members (public issue 192).

Internal Issues:

  * Remove duplicate language from the description of the pname:fence
    parameter to flink:vkQueueSubmit and improve validity language
    (internal issue 91).
  * Added documentation for "optional" attribute to XML readme.tex/pdf
    (internal issue 149).
  * Clarify the host-side data validity rules and behavior of
    flink:vkFlushMappedMemoryRanges and
    flink:vkInvalidateMappedMemoryRanges (internal issue 266).

Other Commits:

  * Added clarification to flink:vkCmdFillBuffer regarding the use of
    ename:VK_WHOLE_SIZE.
  * Fixed and documented implementation of "validextensionstructs"
    attribute. in XML processing scripts and readme.tex/pdf.
  * Add missing validity statements to flink:vkResetEvent and
    flink:vkCmdResetEvent.
  * Fix validity for the
    ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag.
    Correct all the draw/dispatch commands to mention optimally tiled
    images as well as linear tiled images, and say image VIEWS instead
    of images. Add validity statement to flink:vkCmdBlitImage
  * Replace the {apiname} macro with hardcoded "Vulkan", now that we've
    committed to that name.
  * Add the VK_AMD_rasterization_order extension to vk.xml.
2016-04-29 14:53:46 +02:00
doc/specs Change log for April 29, 2016 Vulkan 1.0.12 spec update: 2016-04-29 14:53:46 +02:00
out Change log for March 4, 2016 Vulkan 1.0.5 spec update: 2016-03-03 05:06:18 -08:00
src Change log for April 29, 2016 Vulkan 1.0.12 spec update: 2016-04-29 14:53:46 +02:00
.gitignore Vulkan 1.0 branch 1.0 for release 2016-02-16 01:53:44 -08:00
ChangeLog.txt Change log for April 29, 2016 Vulkan 1.0.12 spec update: 2016-04-29 14:53:46 +02:00
README.md Change log for March 10, 2016 Vulkan 1.0.6 spec update: 2016-03-10 17:33:02 -08:00

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:

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.

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)