SPIR-V 头文件

此仓库包含 SPIR-V 注册表 的机器可读文件。 其中包括：

• 多种语言的头文件。
• 描述 SPIR-V 核心指令集和扩展指令集语法的 JSON 文件。
• XML 注册表文件。
• 一个从 JSON 语法构建头文件的工具。

头文件位于 include 目录中，unified1 子目录下包含最新的头文件。旧版头文件则按其版本号存放。

相比之下，XML 注册表文件具有线性历史记录，因此它并不与 SPIR-V 规范版本绑定。

此仓库如何更新？

当 SPIR-V 规范的新版本或修订版发布时，SPIR-V 工作组将向 master 分支推送新的提交，更新 include 目录下的文件。

SPIR-V XML 注册表文件 由 Khronos 在分配新的枚举范围时进行更新。

可提交拉取请求以：

• 请求在 XML 注册表文件中分配新的枚举范围
• 注册新的 SPIR-V 生成器魔数
• 在 JSON 语法中保留特定标记

注册 SPIR-V 生成器魔数

生成 SPIR-V 的工具应在 SPIR-V 中使用魔数，以帮助识别生成器。

在填写保留标记的详细信息时，应注意遵循现有惯例。这包括：

• 保持生成器编号按数字顺序排列
• 填写所有现有字段

在 JSON 语法中保留标记

在填写保留标记的详细信息时，应注意遵循现有惯例。这包括：

• 在可能的情况下，指明哪个扩展包含更多信息
• 保持枚举值按数字顺序排列
• 若存在别名，首选拼写应列在前面
• 添加语句 "version" : "None"

如何安装头文件

mkdir build
cd build
cmake ..
cmake --build . --target install

例如，你将得到 /usr/local/include/spirv/unified1/spirv.h

如果你想将它们安装到其他位置，请在第一条 cmake 命令中使用 -DCMAKE_INSTALL_PREFIX=/other/path。

不安装直接使用头文件

使用 CMake

基于 CMake 的项目可以按以下方式不安装直接使用头文件：

1. 添加 add_subdirectory 指令以包含此源代码树。
2. 在 target_include_directories 指令中使用 ${SPIRV-Headers_SOURCE_DIR}/include}。
3. 在你的 C 或 C++ 源代码中，使用明确包含 spirv 路径组件的 #include 指令。

#include "spirv/unified1/GLSL.std.450.h"
#include "spirv/unified1/OpenCL.std.h"
#include "spirv/unified1/spirv.hpp"

另请参见 示例 子目录。但由于该示例位于此仓库内部，因此它不使用 add_subdirectory 指令。

使用 Bazel

基于 Bazel 的项目无需安装即可使用这些头文件，步骤如下：

1. 将 SPIRV-Headers 作为项目的子模块添加，并在您的 WORKSPACE 文件中添加一个 local_repository。例如，如果您将 SPIRV-Headers 放置在 external/spirv-headers 下，则在您的 WORKSPACE 文件中添加以下内容：

local_repository(
    name = "spirv_headers",
    path = "external/spirv-headers",
)

2. 根据您的需求，在构建目标的 deps 属性中添加以下内容之一：

@spirv_headers//:spirv_c_headers
@spirv_headers//:spirv_cpp_headers
@spirv_headers//:spirv_cpp11_headers

例如：

cc_library(
  name = "project",
  srcs = [
    # Path to project sources
  ],
  hdrs = [
    # Path to project headers
  ],
  deps = [
    "@spirv_tools//:spirv_c_headers",
    # Other dependencies,
  ],
)

3. 在您的 C 或 C++ 源代码中，使用明确提及 spirv 路径组件的 #include 指令。

#include "spirv/unified1/GLSL.std.450.h"
#include "spirv/unified1/OpenCL.std.h"
#include "spirv/unified1/spirv.hpp"

从 SPIR-V 核心指令集的 JSON 语法生成头文件

通常，当 JSON 语法发生变更时，此操作将由 Khronos 完成。 不过，用于执行此操作的工具项目已包含在本仓库中，可用于测试 PR，甚至将结果包含到 PR 中。 但这并非必需步骤。

头文件生成项目位于 tools/buildHeaders 目录下。 使用 CMake 在 build 子目录（位于 tools/buildHeaders 下）中构建并安装该项目。 随后，bin/makeHeaders 目录下有一个 bash 脚本，展示了如何使用构建好的头文件生成器二进制文件从 JSON 语法生成头文件。 （需从 tools/buildHeaders 目录执行 bin/makeHeaders。） 以下是完整示例：

cd tools/buildHeaders
mkdir build
cd build
cmake ..
cmake --build . --target install
cd ..
./bin/makeHeaders

注意：

• 出于历史原因，此生成器在 Khronos 内部更广泛的上下文中用于生成规范，这会影响所使用的语言。
• 出于相同原因，构建的 C++ 结构可能同样包含超出严格必要的内容。

为扩展指令集生成 C 头文件

GLSL.std.450.h 和 OpenCL.std.h 扩展指令集头文件是手动维护的。

其他每个扩展指令集的 C/C++ 头文件均从相应的 JSON 语法文件生成。例如，OpenCLDebugInfo100.h 头文件由 extinst.opencl.debuginfo.100.grammar.json 语法文件生成。

要生成这些 C/C++ 头文件，请首先确保 python3 在您的 PATH 中，然后按如下方式调用构建脚本：

cd tools/buildHeaders
python3 bin/makeExtinstHeaders.py

常见问题

• 不同版本是如何发布的？

  多个版本的头文件已简化为单一的 unified1 视图。JSON 语法包含一个“version”字段，用于说明各项内容首次出现的版本。

• 如何处理扩展指令集的演进？

  扩展指令集的演进独立于核心规范。目前，GLSL 和 OpenCL 头文件均只有单一版本。因此，我们尚未遇到需要解决的问题案例。

许可证

Copyright (c) 2015-2024 The Khronos Group Inc.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and/or associated documentation files (the
"Materials"), to deal in the Materials without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Materials, and to
permit persons to whom the Materials are furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Materials.

MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
   https://www.khronos.org/registry/

THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.