The Vulkan API Specification and related tools
Go to file
Jon Leech 7380aee56b Change log for March 4, 2016 Vulkan 1.0.5 spec update:
* Bump API patch number to 5 for this update.

Github Issues:
  * Correctly describe slink:VkPhysicalDeviceProperties pname:deviceName
    member as a string, not a pointer to a string. Also one typo fix for
    "hetereogeneous" (public issue 4).
  * Replace maynot: macro with may: not, and "may: or maynot:" with
    "may:" (public issue 4).
  * Clarify that redundantly setting the state of a fence or event has
    no effect (public issue 4).
  * Minor fixes to ref pages to track descriptions of memory bits that
    changed in the core spec. Fix name of a member in the description of
    sname:sname:VkPipelineMultisampleStateCreateInfo (public issues 8,
    13).
  * Remove redundant validity statement for
    sname:VkGraphicsPipelineCreateInfo::pname:stageCount (public issue
    14).
  * Fix typos in chapters 7-9 (public issue 14).
  * Clarify the example demonstrating the behavior of
    code:OpMemoryBarrier in the
    <<shaders-execution-memory-ordering,shader memory acces
    ordering>> section (public issue 16).
  * Specify that freeing mapped memory implicitly unmaps the memory in
    the description of flink:vkFreeMemory (public issue 17).
  * Forbid allocation callbacks from calling into the API in the
    <<memory-allocation,memory allocation>> section (public issue
    20).
  * Add missing validity rules about size being greater than 0 and
    offset being less than size of object. Fix
    flink:VkMappedMemoryRange's misinterpretation of offset (public
    issues 27, 31).
  * Add validity rule disallowing overlapping source/destination
    descriptors in flink:VkCopyDescriptorSet (public issue 32).
  * Clarify that array and matrix stride has to be a multiple of the
    base alignment of the array or matrix in the
    <<interfaces-resources-layout,Offset and Stride Assignment>>
    section (public issue 38).
  * Correct parenthesis floor nesting error in equation for
    <<textures-RGB-sexp,RGB to shared exponent conversion>>.
    Clarify case of when exp' is forced to 0, avoiding log2(0) undefined
    problem (public issue 40).
  * Remove redundant statement from the code:FragDepth description in
    the <<interfaces-builtin-variables,Built-In Variables>>
    section (public issue 47).
  * Define the clamping of the
    <<textures-level-of-detail-operation,bias added to the scale
    factor>> by linking to the slink:VkPhysicalDevice feature
    pname:maxSamplerLodBias (public issue 64).
  * Fix typo "optimal linear resources" and clarify the set of resources
    <<features-limits-bufferImageGranularity,the
    pname:bufferImageGranularity resource>> applies to (public issue
    67).
  * Replace 'descriptor accessed by a pipeline' language for
    sname:VkDescriptorSetAllocateInfo with more precise phrasing about
    binding a descriptor set before a command that invokes work using
    that set (public issue 69).
  * tstripadj.svg contained an Inkscape tag which caused Firefox and IE
    11 to fail to render it, and was illegal SVG. Generating Plain SVG
    from the Inkscape SVG source fixes this (public issue 70).
  * Fix validity for sname:VkVertexInputBindingDescription and
    sname:VkVertexInputAttributeDescription numbers (public issue 72).

Internal Issues:
  * Clarify the meaning of
    ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT in
    elink:VkFormatFeatureFlagBits with respect to depth compare
    (internal issue 107).
  * Added a note explaining that ename:VK_QUEUE_TRANSFER_BIT may or may
    not be reported for a queue family that already supports
    ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT as the
    former is a strict subset of the latter ones (internal issue 116).
  * Add validity language for sname:VkDescriptorSetAllocateInfo about
    exceeding the descriptor pool capacity (internal issue 140).
  * Add ename:VK_INCOMPLETE success code for
    flink:vkEnumeratePhysicalDevices query (internal issue 163).

Other Commits:
  * Add the VK_NV_glsl_shader extension definitions to the API.
  * Update GL_KHR_vulkan_glsl with 1) origin_upper_left as default 2)
    specialization array constant semantics.
  * Corrected/updated Data Format Specification date.
2016-03-03 05:06:18 -08:00
doc/specs Change log for March 4, 2016 Vulkan 1.0.5 spec update: 2016-03-03 05:06:18 -08: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 March 4, 2016 Vulkan 1.0.5 spec update: 2016-03-03 05:06:18 -08:00
.gitignore Vulkan 1.0 branch 1.0 for release 2016-02-16 01:53:44 -08:00
README.md Vulkan 1.0 branch 1.0 for release 2016-02-16 01:53:44 -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

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)