为 vulkano 的着色器系统提供的进程宏。管理将 GLSL 编译到 SPIR-V 并生成相关 Rust 代码的编译时编译。

基本用法

mod vs {
    vulkano_shaders::shader!{
        ty: "vertex",
        src: r"
            #version 450

            layout(location = 0) in vec3 position;

            void main() {
                gl_Position = vec4(position, 1.0);
            }
        ",
    }
}

详细信息

如果您想查看宏生成的代码，最佳选择是使用 cargo-expand 来查看您自己代码中宏的展开。另一方面，如果您想了解高级概述，可以查看下面的部分。

生成代码概述

该宏生成以下有趣的项目

• load 构造函数。此函数接受一个 Arc<Device>，使用传入的设备和通过宏提供的着色器数据构建一个 ShaderModule，并返回 Result<Arc<ShaderModule>, Validated<VulkanError>>。在这样做之前，它会检查着色器数据中的每个功能指令，验证传入的 Device 是否启用了适当的功能。
• 如果使用 shaders 选项，则不是只有一个 load 构造函数，而是为每个着色器提供一个。它们的名称基于提供的名称，如 load_first、load_second 等。
• 由着色器数据中包含的每个结构体转换而来的 Rust 结构体。默认情况下，每个结构体都有一个 Clone 和一个 Copy 实现。可以通过 custom_derives 宏选项（以下将详细介绍）来定制此行为。每个结构体还有一个 BufferContents 实现，以便可以从/向缓冲区读取/写入。

所有这些生成的项都将通过调用宏的模块来访问。如果您想将 ShaderModule 存储在您自己的结构体中，可以这样做

#
#
#
// ...various use statements...
// ...`vs` module containing a `shader!` call...

pub struct Shaders {
    pub vs: Arc<ShaderModule>,
}

impl Shaders {
    pub fn load(device: Arc<Device>) -> Result<Self, Validated<VulkanError>> {
        Ok(Self {
            vs: vs::load(device)?,
        })
    }
}

选项

可用选项的形式如下字段

ty: "..."

这定义了给定 GLSL 源将被编译成哪种着色器类型。类型可以是以下任何一种

• vertex
• fragment
• geometry
• tess_ctrl
• tess_eval
• compute
• raygen
• anyhit
• closesthit
• miss
• intersection
• callable

有关这些着色器类型的详细信息，请参阅 Vulkano 文档。

src: "..."

提供要编译的原始 GLSL 源代码，形式为一个字符串。不能与 path 或 bytes 字段一起使用。

path: "..."

提供要编译的 GLSL 源文件的路径，相对于您的 Cargo.toml。不能与 src 或 bytes 字段一起使用。

bytes: "..."

提供预编译 SPIR-V 字节码的路径，相对于您的 Cargo.toml。不能与 src 或 path 字段一起使用。这允许使用通过单独的构建系统编译的着色器。

root_path_env: "..."

不是相对于您的 Cargo.toml 搜索，而是相对于由该环境变量指定的其他文件夹搜索。预期用途是使用 OUT_DIR 来加载由您的构建脚本生成的着色器。默认为 CARGO_MANIFEST_DIR，对应于您的 Cargo.toml 文件夹。

有关 cargo 设置的全套环境变量，请参阅 cargo-env-vars。也可以在构建脚本中使用以下方式指定环境变量

println!("cargo:rustc-env=SHADER_OUT_DIR={shader_out_dir}");

shaders: {first: {src: "...",ty: "..." }, ... }

使用这些选项，用户可以在单个宏调用中编译多个着色器。每个条目的键将是生成的 load 函数的后缀（在本例中为 load_first）。然而，所有其他从着色器源代码转换而来的 Rust 结构体都将共享。宏会检查不同着色器之间具有相同名称的源结构体具有相同的声明签名，如果不具有相同的声明签名，则会抛出一个编译时错误。

每个条目期望一个 src、path、bytes 和 ty 的对，与上面相同。

include: ["...", "...", ...]

指定在使用着色器源代码中的#include <...>指令时搜索的标准包含目录。包含目录可以是相对于你的Cargo.toml的绝对路径或相对路径。如果指定了path，也可以使用相对路径（#include "..."），无需指定一个或多个标准包含目录。相对路径相对于声明#include "..."指令的源文件所在的目录。

定义: [("名称", "值"), ...]

将给定的宏定义添加到预处理器。这等价于在命令行上传递-DNAME=VALUE参数。

vulkan_version: "major.minor" 和 spirv_version: "major.minor"

设置要编译的Vulkan和SPIR-V版本。这些直接映射到set_target_env和set_target_spirv编译选项。如果没有指定这些选项，则将生成针对Vulkan 1.0的SPIR-V 1.0代码。

生成的代码必须在运行时由设备支持。如果不支持，则在调用load时将返回错误。

custom_derives: [克隆, 默认, 部分相等, ...]

扩展了添加到表示着色器结构的Rust结构体的derive属性的派生宏列表。

默认情况下，每个生成的结构体都有一个用于Clone和Copy的派生。如果结构体有未指定大小的成员，则不会在结构体上应用任何派生，除了始终派生的BufferContents。

linalg_type: "..."

指定线性代数类型应生成的形式。可以是以下任何一个：

• std
• cgmath
• nalgebra

默认是std，使用数组来表示向量和矩阵。注意，如果选择的crate没有表示某种线性代数类型的类型（例如mat3或矩形矩阵），则宏将默认回退到该类型的数组。

如果你使用第三方crate中的线性代数类型，那么你必须将该crate包含在你的依赖关系中，并启用添加bytemuck支持的适当功能。

dump: true

crate无法编译，但将生成的Rust代码打印到stdout。

Cargo功能