Skip to content

Latest commit

 

History

History
207 lines (178 loc) · 8.1 KB

README.adoc

File metadata and controls

207 lines (178 loc) · 8.1 KB
Raw

Vulkan® API Registry Build Instructions and Notes

Introduction

This is the Vulkan XML API Registry. It is used to generate the canonical Vulkan header files, the API Asciidoc include files used by the Vulkan Specification and Reference Pages, and many other types of generated files.

When changes to generated files are needed, follow this workflow. Normally changes are needed only when defining a new extension or core version of the API.

  • Clone the repository and create a branch to work in locally

  • Edit vk.xml

  • make validate install test

    • This validates the XML files against the schema description; generates headers in ../gen/include/vulkan including vulkan_core.h and a set of platform-dependent headers vulkan_<platform>.h; and runs a simple compilation test of the headers.

  • (cd .. && make generated)

    • This uses vk.xml to generate asciidoc includes and other intermediate files in ../gen for the specification build. There are many ways to invoke the Makefile in ... This simple recipe only generates includes for the core Vulkan API without any extensions. See ../BUILD.adoc for more.

  • Repeat until the headers and/or includes are correct

  • Commit your changes to your local git branch, push to your upstream git server (your personal repository clone of KhronosGroup/Vulkan-Docs on GitHub, for people outside Khronos; the Khronos member gitlab server, otherwise), and create a pull or merge request against the default branch (currently main) or other appropriate target.

For a detailed description of the schema, go to .. and make registry, which generates gen/out/registry.html. This document also includes some examples of how to make simple changes in the API via the XML.

The generator scripts are written in Python 3, using the etree package for processing XML. See ../scripts/README.adoc for script descriptions.

Video Headers

In addition to vk.xml this directory also includes video.xml. This is a similarly structured XML file used to produce headers for structures and other types (StdVideo*) associated with externally defined video standards. While these data types are passed into some of the Vulkan Video extension APIs, they are not treated as part of the Vulkan API. This is why they are defined in a separate XML file.

The validate and install targets described above also generate the StdVideo* headers in ../gen/include/vk_video. A separate test target, vtest, can be used as a simple compilation test of the StdVideo* headers.

Build Environment

We strongly recommend using the Khronos-provided Docker image, which has all needed build tools pre-installed. See ../BUILD.adoc for details.

It is possible to construct your own build environment on Linux, Windows, or MacOS by following the recipe in the Dockerfile for the Khronos-provided Docker image.

Files

  • vk.xml - XML API description.

  • registry.rnc - RelaxNG compact schema for validating XML against the schema.

  • Makefile - generates headers from vk.xml (see Makefile Targets below).

  • ../gen/include/vulkan/vulkan_core.h - Generated Vulkan non-platform API header.

  • ../gen/include/vulkan/vulkan_<platform>.h - Generated Vulkan platform API headers.

  • video.xml - StdVideo* API description.

  • ../gen/include/vk_video/vulkan_video*.h - Generated StdVideo* API headers.

Makefile Targets

  • install (default target) - regenerate Vulkan and StdVideo* header files in ../gen/include/.

  • test - make sure Vulkan headers compile. Important! Can also be used to test if platform headers compile by specifying make TESTDEFS=-DVK_USE_PLATFORM_<PLATFORM>_<AUTHORID> test.

  • vtest - make sure StdVideo* headers compile.

  • validate - validate vk.xml and video.xml against the schema. Requires installing jing (see Software Dependencies below). Also important!

  • clean_dirt - remove intermediate files.

  • clean - remove generated files.

Generated files can be created in a directory other than the default ../gen/ by setting the Makefile variable GENERATED to that directory path.

If you have trouble running the Makefile on your platform, the following steps will build the Vulkan headers and test that vulkan_core.h compiles:

# Regenerate header from XML
python3 ../scripts/genvk.py -registry vk.xml -o ../gen/include/vulkan vulkan_core.h
# Verify that the resulting header compiles
gcc -Wall -std=c99 -c -I../gen/include -I../tests ../tests/htest.c
g++ -Wall -std=c++98 -c -I../gen/include -I../tests ../tests/htest.c
rm -f htest.o

Revision History

  • 2021-12-13 - Add video.xml for StdVideo* APIs and headers.

  • 2020-08-25 - Update for new default branch (main).

  • 2019/05/12 - Bring up to date with changes in file paths and build tools.

  • 2019/03/10 - Update for script reorganization.

  • 2018/05/21 - Do not generate vulkan_ext.[ch] from the install target. Add a new shortcut extloader target for people still using this code and needing to regenerate it.

  • 2018/03/13 - Update for new directory structure.

  • 2018/03/06 - Update for Vulkan 1.1 release and new default branch.

  • 2015/09/18 - Split platform-specific headers into their own vulkan_<platform>.h files, move vulkan.h to vulkan_core.h, and add a new (static) vulkan.h which includes appropriate combinations of the other headers.

  • 2015/06/01 - The header that is generated has been improved relative to the first version. Function arguments are indented like the hand-generated header, enumerant BEGIN/END_RANGE enums are named the same, etc. The ordering of declarations is unlike the hand-generated header, and probably always will because it results from a type/enum/function dependency analysis. Some of this can be forced by being more explicit about it, if that is a big deal.

  • 2015/06/02 - Per WG signoff, converted hex constant values to decimal (for non-bitmasks) and VK_BIT macros to 'bitpos' attributes in the XML and hex constants in the header. Updated schema to match. Changed <ptype> tag to <type>.

  • 2015/06/03 - Moved into new 'vulkan' tree (did not bother preserving history in previous repo). Added semantic knowledge about structs and unions to <type> tags instead of just imbedding C struct definitions. Improved registry.rnc schema a bit.

  • 2015/06/07 - Incorporate feedback from F2F including Python 3 and Windows fixes to the scripts. Add documentation to readme.pdf. Fold in multiple merge requests resulting from action items agreed at the F2F, to prepare for everyone moving to XML instead of directly editing the header.

  • 2015/06/20 - Add vulkan-docs target and instructions for installing python3 and python-lxml for Windows.

  • 2015/08/13 - Bring documentation up to date with Makefile targets (default is now ../include/vulkan.h).

  • 2015/09/02 - Update README with required (or known working) versions of toolchain components.

  • 2015/09/02 - Move include/vulkan.h to vulkan/vulkan.h so #include "vulkan/vulkan.h" is the normal usage (Bug 14576).

  • 2016/02/12 - Update README and remove old files to stage for public release.

  • 2016/05/31 - Remove dependency on lxml.

  • 2016/07/27 - Update documentation for changes to schema and generator scripts.

  • 2016/08/26 - Move README to an asciidoc file and update for the single-branch model. Use 'clean' target to remove generated files in both spec source and registry Makefiles.

  • 2017/02/20 - Move registry.txt (schema documentation) to the Vulkan spec source directory and update the README here.