1# SPIR-V Headers 2 3This repository contains machine-readable files from the 4[SPIR-V Registry](https://www.khronos.org/registry/spir-v/). 5This includes: 6 7* Header files for various languages. 8* JSON files describing the grammar for the SPIR-V core instruction set, 9 and for the GLSL.std.450 extended instruction set. 10* The XML registry file. 11 12Under the [include](include) directory, header files are provided according to 13their own version. Only major and minor version numbers count. 14For example, the headers for SPIR-V 1.1 are in 15[include/spirv/1.1](include/spirv/1.1). Also, the headers for the 1.0 versions 16of the GLSL.std.450 and OpenCL extended instruction sets are in 17[include/spirv/1.0](include/spirv/1.0). 18 19In contrast, the XML registry file has a linear history, so it is 20not tied to SPIR-V specification versions. 21 22## How is this repository updated? 23 24When a new version or revision of the SPIR-V header files are published, 25the SPIR Working Group will push new commits onto master, updating 26the files under [include](include). 27A newer revision of a header file always replaces an older revision of 28the same version. For example, verison 1.0 Rev 4 of `spirv.h` is placed in 29`include/spirv/1.0/spirv.h` and if there is a Rev 5, then it will be placed 30in the same location. 31 32The SPIR-V XML registry file is updated by the Khronos registrar whenever 33a new enum range is allocated. 34 35In particular, pull requests that update header files will not be accepted. 36Issues with the header files should be filed in the [issue 37tracker](https://github.com/KhronosGroup/SPIRV-Headers/issues). 38 39## How to install the headers 40 41``` 42mkdir build 43cd build 44cmake .. 45# Linux 46cmake --build . --target install-headers 47# Windows 48cmake --build . --config Debug --target install-headers 49``` 50 51Then, for example, you will have `/usr/local/include/spirv/1.0/spirv.h` 52 53If you want to install them somewhere else, then use 54`-DCMAKE_INSTALL_PREFIX=/other/path` on the first `cmake` command. 55 56## Using the headers without installing 57 58A CMake-based project can use the headers without installing, as follows: 59 601. Add an `add_subdirectory` directive to include this source tree. 612. Use `${SPIRV-Headers_SOURCE_DIR}/include}` in a `target_include_directories` 62 directive. 633. In your C or C++ source code use `#include` directives that explicitly mention 64 the `spirv` path component. For example the following uses SPIR-V 1.1 65 core instructions, and the 1.0 versions of the GLSL.std.450 and OpenCL 66 extended instructions. 67``` 68#include "spirv/1.0/GLSL.std.450.h" 69#include "spirv/1.0/OpenCL.std.h" 70#include "spirv/1.1/spirv.hpp" 71``` 72 73See also the [example](example/) subdirectory. But since that example is 74*inside* this repostory, it doesn't use and `add_subdirectory` directive. 75 76## FAQ 77 78* *How are different versions published?* 79 80 All versions are present in the master branch of the repository. 81 They are located in different subdirectories under 82 [include/spirv](include/spirv), where the subdirectory at that 83 level encodes the major and minor version number of the relevant spec. 84 85 An application should consciously select the targeted spec version 86 number, by naming the specific version in its `#include` directives, 87 as above and in the examples. 88 89* *How do you handle the evolution of extended instruction sets?* 90 91 Extended instruction sets evolve asynchronously from the core spec. 92 Right now there is only a single version of both the GLSL and OpenCL 93 headers. So we don't yet have a problematic example to resolve. 94 95## License 96<a name="license"></a> 97``` 98Copyright (c) 2015-2016 The Khronos Group Inc. 99 100Permission is hereby granted, free of charge, to any person obtaining a 101copy of this software and/or associated documentation files (the 102"Materials"), to deal in the Materials without restriction, including 103without limitation the rights to use, copy, modify, merge, publish, 104distribute, sublicense, and/or sell copies of the Materials, and to 105permit persons to whom the Materials are furnished to do so, subject to 106the following conditions: 107 108The above copyright notice and this permission notice shall be included 109in all copies or substantial portions of the Materials. 110 111MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS 112KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS 113SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT 114 https://www.khronos.org/registry/ 115 116THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 117EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 118MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 119IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 120CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 121TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 122MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS. 123``` 124