status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-01-11 06:25:59 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/README.md
Jon Leech 1f875738fd Change log for March 10, 2016 Vulkan 1.0.6 spec update: 
* Bump API patch number and header version number to 6 for this
    update.

Github Issues:
  * Define 'invocation group' for compute and graphics shaders. Cleanup
    definition and use of 'workgroup', and add glossary entries (public
    issue 1).
  * Various minor editorial fixes (public issue 33).
  * Clarify locations for block members in the
    <<interfaces-iointerfaces-locations,Location Assignment>>
    section (public issue 45).
  * Editorial fixes for <<commandbuffer-allocation,Command Buffer
    Allocation>> section (public issues 54, 59).
  * Clarify behavior of depth test in the <<fragops-depth,Depth
    Test>> section (public issues 80, 81).
  * Remove discussion of return codes from
    flink:vkGetPhysicalDeviceSparseImageFormatProperties and
    flink:vkGetImageSparseMemoryRequirements, which don't return values
    (public issue 82).
  * Allow flink:vkCmdDrawIndirect and flink:vkCmdDrawIndexedIndirect
    pname:drawCount of 0, as well as 1, when the multiDrawIndirect
    feature is not supported (public issue 88).
  * Remove confusing wording in the <<features-limits,Limits>>
    section describing the slink:VkPhysicalDeviceLimits
    pname:minTexelBufferOffsetAlignment,
    pname:minUniformBufferOffsetAlignment, and
    pname:minStorageBufferOffsetAlignment members as both minimums and
    maximums (public issue 91).
  * Clarified that only the RGB components should be affected in places
    where sRGB is referred to in the spec, such as ASTC formats. Minor
    re-wording to avoid "color space" when actively incorrect, now that
    we refer to the Data Format Spec which actually makes a distinction
    between color space and transfer function (public issue 94).
  * Treat pname:pPropertyCount == 0 consistently in
    flink:vkEnumerateInstanceLayerProperties and
    flink:vkEnumerateDeviceLayerProperties (public issue 99)
  * Cleanup minor editorial issues in chapters 14-17 (public issue 100).
  * Clarify definition of flink:vkEnumerateInstanceExtensionProperties
    and flink:vkEnumerateDeviceExtensionProperties (public issue 101).
  * Define the flink:vkEnumerateInstanceExtensionProperties and
    flink:vkEnumerateDeviceExtensionProperties pname:pLayerName
    parameter to be a pointer to a null-terminated UTF-8 string (public
    issue 101).
  * Rearrange "Missing information" references in mandatory format
    tables (public issue 101).
  * Clarify that the enumerated extensions returned by
    flink:vkEnumerateInstanceExtensionProperties and
    flink:vkEnumerateDeviceExtensionProperties will only include
    extensions provided by the platform or extensions implemented in
    implicitly enabled layers (public issue 101).
  * Miscellaneous editorial fixes. Include the Vulkan spec patch number
    in the PDF title. Fix label on <<fig-non-strict-lines,Non
    strict lines>> diagram. Use more easily distinguished symbols in
    tables in the <<features-required-format-support,Required
    Format Support>> section. Don't require FQDNs used as layer names be
    encoded in lower case if not possible, in the
    <<extensions-naming-conventions, Extension and Layer Naming
    Conventions>> section (public issues 101, 119, 121).

Internal Issues:
  * Fixed excessive spacing in tables in XHTML (internal issue 18).
  * Clarify that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
    applies to secondary command buffers. Previously spec only referred
    to the members of pname:pCommandBuffers being affected by this bit.
    Added a separate slink:VkSubmitInfo Valid Usage restriction
    specifying that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
    also applies to any secondary command buffers that are recorded into
    the primary command buffers in pname:pCommandBuffers (internal issue
    106).
  * Clarify that slink:VkDeviceCreateInfo::pname:pEnabledFeatures can be
    NULL (internal issue 117).
  * Remove "the value of" where it is redundant (e.g. speaking of an API
    parameter, struct member, or SPIR-V variable, but not when speaking
    of color components) (internal issue 175).
  * Forced patch version to always be 0 in the header. Add a
    "VK_API_VERSION_<major>_<minor>" macro for people to use to do the
    right thing. Add a VK_HEADER_VERSION which captures the header
    release number independent of the spec patch number (internal issue
    176).
  * Correct description of
    slink:VkPipelineShaderStageCreateInfo::pname:pName to "a pointer to
    a null-terminated UTF-8 string" (internal issue #197).

Other Commits:
  * Updated DataFormat spec reference to the new date for revision 5 of
    that spec.
  * Fixed KEEP option (to retain LaTeX intermediate files) in the
    Makefile to be included when edited there, as well as set on the
    command line.
  * Reserve and add "VK_IMG_filter_cubic" to the registry, and implement
    script functionality to add and remove validity from existing
    functions. Includes schema and readme changes.
  * Update GL_KHR_vulkan_glsl so push_constants do not have descriptor
    sets.
2016-03-10 17:33:02 -08:00

4.3 KiB
Raw Blame History

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.

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)