• Home
Name
Date
Size
#Lines
LOC

..--

cmake/03-May-2024-53

example/03-May-2024-9125

include/spirv/03-May-2024-71,68169,184

tools/buildHeaders/03-May-2024-9,2116,458

.gitattributesD03-May-202472 87

.gitignoreD03-May-202420 43

Android.bpD03-May-20241.2 KiB3631

BUILD.bazelD03-May-20242.9 KiB125104

CMakeLists.txtD03-May-20244.2 KiB128107

CODE_OF_CONDUCT.mdD03-May-2024280 21

LICENSED03-May-20241.3 KiB2621

README.mdD03-May-20246.2 KiB183143

WORKSPACED03-May-20240

README.md

1# SPIR-V Headers
2
3This repository contains machine-readable files for 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 the extended instruction sets.
10* The XML registry file.
11* A tool to build the headers from the JSON grammar.
12
13Headers are provided in the [include](include) directory, with up-to-date
14headers in the `unified1` subdirectory. Older headers are provided according to
15their version.
16
17In contrast, the XML registry file has a linear history, so it is
18not tied to SPIR-V specification versions.
19
20## How is this repository updated?
21
22When a new version or revision of the SPIR-V specification is published,
23the SPIR-V Working Group will push new commits onto master, updating
24the files under [include](include).
25
26The SPIR-V XML registry file is updated by Khronos whenever a new enum range is allocated.
27
28Pull requests can be made to
29- request allocation of new enum ranges in the XML registry file
30- reserve specific tokens in the JSON grammar
31
32### Reserving tokens in the JSON grammar
33
34Care should be taken to follow existing precedent in populating the details of reserved tokens. This includes:
35- pointing to what extension has more information, when possible
36- keeping enumerants in numeric order
37- when there are aliases, listing the preferred spelling first
38- adding the statement `"version" : "None"`
39
40## How to install the headers
41
42```
43mkdir build
44cd build
45cmake ..
46cmake --build . --target install
47```
48
49Then, for example, you will have `/usr/local/include/spirv/unified1/spirv.h`
50
51If you want to install them somewhere else, then use
52`-DCMAKE_INSTALL_PREFIX=/other/path` on the first `cmake` command.
53
54## Using the headers without installing
55
56### Using CMake
57A CMake-based project can use the headers without installing, as follows:
58
591. Add an `add_subdirectory` directive to include this source tree.
602. Use `${SPIRV-Headers_SOURCE_DIR}/include}` in a `target_include_directories`
61   directive.
623. In your C or C++ source code use `#include` directives that explicitly mention
63   the `spirv` path component.
64```
65#include "spirv/unified1/GLSL.std.450.h"
66#include "spirv/unified1/OpenCL.std.h"
67#include "spirv/unified1/spirv.hpp"
68```
69
70See also the [example](example/) subdirectory.  But since that example is
71*inside* this repostory, it doesn't use and `add_subdirectory` directive.
72
73### Using Bazel
74A Bazel-based project can use the headers without installing, as follows:
75
761. Add SPIRV-Headers as a submodule of your project, and add a
77`local_repository` to your `WORKSPACE` file. For example, if you place
78SPIRV-Headers under `external/spirv-headers`, then add the following to your
79`WORKSPACE` file:
80
81```
82local_repository(
83    name = "spirv_headers",
84    path = "external/spirv-headers",
85)
86```
87
882. Add one of the following to the `deps` attribute of your build target based
89on your needs:
90```
91@spirv_headers//:spirv_c_headers
92@spirv_headers//:spirv_cpp_headers
93@spirv_headers//:spirv_cpp11_headers
94```
95
96For example:
97
98```
99cc_library(
100  name = "project",
101  srcs = [
102    # Path to project sources
103  ],
104  hdrs = [
105    # Path to project headers
106  ],
107  deps = [
108    "@spirv_tools//:spirv_c_headers",
109    # Other dependencies,
110  ],
111)
112```
113
1143. In your C or C++ source code use `#include` directives that explicitly mention
115   the `spirv` path component.
116```
117#include "spirv/unified1/GLSL.std.450.h"
118#include "spirv/unified1/OpenCL.std.h"
119#include "spirv/unified1/spirv.hpp"
120```
121
122## Generating the headers from the JSON grammar
123
124This will generally be done by Khronos, for a change to the JSON grammar.
125However, the project for the tool to do this is included in this repository,
126and can be used to test a PR, or even to include the results in the PR.
127This is not required though.
128
129The header-generation project is under the `tools/buildHeaders` directory.
130Use CMake to build the project, in a `build` subdirectory (under `tools/buildHeaders`).
131There is then a bash script at `bin/makeHeaders` that shows how to use the built
132header-generator binary to generate the headers from the JSON grammar.
133(Execute `bin/makeHeaders` from the `tools/buildHeaders` directory.)
134
135Notes:
136- this generator is used in a broader context within Khronos to generate the specification,
137  and that influences the languages used, for legacy reasons
138- the C++ structures built may similarly include more than strictly necessary, for the same reason
139
140## FAQ
141
142* *How are different versions published?*
143
144  The multiple versions of the headers have been simplified into a
145  single `unified1` view. The JSON grammar has a "version" field saying
146  what version things first showed up in.
147
148* *How do you handle the evolution of extended instruction sets?*
149
150  Extended instruction sets evolve asynchronously from the core spec.
151  Right now there is only a single version of both the GLSL and OpenCL
152  headers.  So we don't yet have a problematic example to resolve.
153
154## License
155<a name="license"></a>
156```
157Copyright (c) 2015-2018 The Khronos Group Inc.
158
159Permission is hereby granted, free of charge, to any person obtaining a
160copy of this software and/or associated documentation files (the
161"Materials"), to deal in the Materials without restriction, including
162without limitation the rights to use, copy, modify, merge, publish,
163distribute, sublicense, and/or sell copies of the Materials, and to
164permit persons to whom the Materials are furnished to do so, subject to
165the following conditions:
166
167The above copyright notice and this permission notice shall be included
168in all copies or substantial portions of the Materials.
169
170MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
171KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
172SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
173   https://www.khronos.org/registry/
174
175THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
176EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
177MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
178IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
179CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
180TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
181MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
182```
183