{"id":13731921,"url":"https://github.com/KhronosGroup/SPIRV-Headers","last_synced_at":"2025-05-08T05:31:55.744Z","repository":{"id":37742923,"uuid":"56254015","full_name":"KhronosGroup/SPIRV-Headers","owner":"KhronosGroup","description":"SPIRV-Headers","archived":false,"fork":false,"pushed_at":"2025-05-06T12:50:37.000Z","size":3350,"stargazers_count":299,"open_issues_count":35,"forks_count":275,"subscribers_count":37,"default_branch":"main","last_synced_at":"2025-05-07T10:17:20.438Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KhronosGroup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-04-14T16:44:07.000Z","updated_at":"2025-05-06T12:50:41.000Z","dependencies_parsed_at":"2023-10-11T19:13:22.545Z","dependency_job_id":"ecc5d609-fbc9-4751-8d3b-1160d45808d9","html_url":"https://github.com/KhronosGroup/SPIRV-Headers","commit_stats":{"total_commits":360,"total_committers":98,"mean_commits":3.673469387755102,"dds":0.8055555555555556,"last_synced_commit":"cfbe4feef20c3c0628712c2792624f0221e378ac"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KhronosGroup%2FSPIRV-Headers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KhronosGroup%2FSPIRV-Headers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KhronosGroup%2FSPIRV-Headers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KhronosGroup%2FSPIRV-Headers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KhronosGroup","download_url":"https://codeload.github.com/KhronosGroup/SPIRV-Headers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253008834,"owners_count":21839700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T02:01:41.597Z","updated_at":"2025-05-08T05:31:55.667Z","avatar_url":"https://github.com/KhronosGroup.png","language":"C++","funding_links":[],"categories":["Graphics"],"sub_categories":[],"readme":"# SPIR-V Headers\n\nThis repository contains machine-readable files for the\n[SPIR-V Registry](https://www.khronos.org/registry/spir-v/).\nThis includes:\n\n* Header files for various languages.\n* JSON files describing the grammar for the SPIR-V core instruction set\n  and the extended instruction sets.\n* The XML registry file.\n* A tool to build the headers from the JSON grammar.\n\nHeaders are provided in the [include](include) directory, with up-to-date\nheaders in the `unified1` subdirectory. Older headers are provided according to\ntheir version.\n\nIn contrast, the XML registry file has a linear history, so it is\nnot tied to SPIR-V specification versions.\n\n## How is this repository updated?\n\nWhen a new version or revision of the SPIR-V specification is published,\nthe SPIR-V Working Group will push new commits onto master, updating\nthe files under [include](include).\n\n[The SPIR-V XML registry file](include/spirv/spir-v.xml)\nis updated by Khronos whenever a new enum range is allocated.\n\nPull requests can be made to\n- request allocation of new enum ranges in the XML registry file\n- register a new magic number for a SPIR-V generator\n- reserve specific tokens in the JSON grammar\n\n### Registering a SPIR-V Generator Magic Number\n\nTools that generate SPIR-V should use a magic number in the SPIR-V to help identify the\ngenerator.\n\nCare should be taken to follow existing precedent in populating the details of reserved tokens.\nThis includes:\n- keeping generator numbers in numeric order\n- filling out all the existing fields\n\n### Reserving tokens in the JSON grammar\n\nCare should be taken to follow existing precedent in populating the details of reserved tokens.\nThis includes:\n- pointing to what extension has more information, when possible\n- keeping enumerants in numeric order\n- when there are aliases, listing the preferred spelling first\n- adding the statement `\"version\" : \"None\"`\n\n## How to install the headers\n\n```\nmkdir build\ncd build\ncmake ..\ncmake --build . --target install\n```\n\nThen, for example, you will have `/usr/local/include/spirv/unified1/spirv.h`\n\nIf you want to install them somewhere else, then use\n`-DCMAKE_INSTALL_PREFIX=/other/path` on the first `cmake` command.\n\n## Using the headers without installing\n\n### Using CMake\nA CMake-based project can use the headers without installing, as follows:\n\n1. Add an `add_subdirectory` directive to include this source tree.\n2. Use `${SPIRV-Headers_SOURCE_DIR}/include}` in a `target_include_directories`\n   directive.\n3. In your C or C++ source code use `#include` directives that explicitly mention\n   the `spirv` path component.\n```\n#include \"spirv/unified1/GLSL.std.450.h\"\n#include \"spirv/unified1/OpenCL.std.h\"\n#include \"spirv/unified1/spirv.hpp\"\n```\n\nSee also the [example](example/) subdirectory.  But since that example is\n*inside* this repostory, it doesn't use and `add_subdirectory` directive.\n\n### Using Bazel\nA Bazel-based project can use the headers without installing, as follows:\n\n1. Add SPIRV-Headers as a submodule of your project, and add a\n`local_repository` to your `WORKSPACE` file. For example, if you place\nSPIRV-Headers under `external/spirv-headers`, then add the following to your\n`WORKSPACE` file:\n\n```\nlocal_repository(\n    name = \"spirv_headers\",\n    path = \"external/spirv-headers\",\n)\n```\n\n2. Add one of the following to the `deps` attribute of your build target based\non your needs:\n```\n@spirv_headers//:spirv_c_headers\n@spirv_headers//:spirv_cpp_headers\n@spirv_headers//:spirv_cpp11_headers\n```\n\nFor example:\n\n```\ncc_library(\n  name = \"project\",\n  srcs = [\n    # Path to project sources\n  ],\n  hdrs = [\n    # Path to project headers\n  ],\n  deps = [\n    \"@spirv_tools//:spirv_c_headers\",\n    # Other dependencies,\n  ],\n)\n```\n\n3. In your C or C++ source code use `#include` directives that explicitly mention\n   the `spirv` path component.\n```\n#include \"spirv/unified1/GLSL.std.450.h\"\n#include \"spirv/unified1/OpenCL.std.h\"\n#include \"spirv/unified1/spirv.hpp\"\n```\n\n## Generating headers from the JSON grammar for the SPIR-V core instruction set\n\nThis will generally be done by Khronos, for a change to the JSON grammar.\nHowever, the project for the tool to do this is included in this repository,\nand can be used to test a PR, or even to include the results in the PR.\nThis is not required though.\n\nThe header-generation project is under the `tools/buildHeaders` directory.\nUse CMake to build and install the project, in a `build` subdirectory (under `tools/buildHeaders`).\nThere is then a bash script at `bin/makeHeaders` that shows how to use the built\nheader-generator binary to generate the headers from the JSON grammar.\n(Execute `bin/makeHeaders` from the `tools/buildHeaders` directory.)\nHere's a complete example:\n\n```\ncd tools/buildHeaders\nmkdir build\ncd build\ncmake ..\ncmake --build . --target install\ncd ..\n./bin/makeHeaders\n```\n\nNotes:\n- this generator is used in a broader context within Khronos to generate the specification,\n  and that influences the languages used, for legacy reasons\n- the C++ structures built may similarly include more than strictly necessary, for the same reason\n\n## Generating C headers for extended instruction sets\n\nThe [GLSL.std.450.h](include/spirv/unified1/GLSL.std.450.h)\nand [OpenCL.std.h](include/spirv/unified1/OpenCL.std.h) extended instruction set headers\nare maintained manually.\n\nThe C/C++ header for each of the other extended instruction sets\nis generated from the corresponding JSON grammar file.  For example, the\n[OpenCLDebugInfo100.h](include/spirv/unified1/OpenCLDebugInfo100.h) header\nis generated from the\n[extinst.opencl.debuginfo.100.grammar.json](include/spirv/unified1/extinst.opencl.debuginfo.100.grammar.json)\ngrammar file.\n\nTo generate these C/C++ headers, first make sure `python3` is in your PATH, then\ninvoke the build script as follows:\n```\ncd tools/buildHeaders\npython3 bin/makeExtinstHeaders.py\n```\n\n## FAQ\n\n* *How are different versions published?*\n\n  The multiple versions of the headers have been simplified into a\n  single `unified1` view. The JSON grammar has a \"version\" field saying\n  what version things first showed up in.\n\n* *How do you handle the evolution of extended instruction sets?*\n\n  Extended instruction sets evolve asynchronously from the core spec.\n  Right now there is only a single version of both the GLSL and OpenCL\n  headers.  So we don't yet have a problematic example to resolve.\n\n## License\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n```\nCopyright (c) 2015-2024 The Khronos Group Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and/or associated documentation files (the\n\"Materials\"), to deal in the Materials without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Materials, and to\npermit persons to whom the Materials are furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be included\nin all copies or substantial portions of the Materials.\n\nMODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS\nKHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS\nSPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT\n   https://www.khronos.org/registry/\n\nTHE MATERIALS ARE PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nMATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKhronosGroup%2FSPIRV-Headers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKhronosGroup%2FSPIRV-Headers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKhronosGroup%2FSPIRV-Headers/lists"}