Crate vulkano_shaders

The procedural macro for vulkano’s shader system. Manages the compile-time compilation of GLSL into SPIR-V and generation of assosciated rust code.

Basic usage

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

layout(location = 0) in vec3 position;

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

Details

If you want to take a look at what the macro generates, your best options are to either read through the code that handles the generation (the reflect function in the vulkano-shaders crate) or use a tool such as cargo-expand to view the expansion of the macro in your own code. It is unfortunately not possible to provide a generated_example module like some normal macro crates do since derive macros cannot be used from the crate they are declared in. On the other hand, if you are looking for a high-level overview, you can see the below section.

Generated code overview

The macro generates the following items of interest:

• The load constructor. This method takes an Arc<Device>, calls ShaderModule::new with the passed-in device and the shader data provided via the macro, and returns Result<Arc<ShaderModule>, ShaderCreationError>. Before doing so, it loops through every capability instruction in the shader data, verifying that the passed-in Device has the appropriate features enabled.
• If the shaders option is used, then instead of one load constructor, there is one for each shader. They are named based on the provided names, load_first, load_second etc.
• A Rust struct translated from each struct contained in the shader data. By default each structure has a Clone and a Copy implementations. This behavior could be customized through the types_meta macro option(see below for details).
• The SpecializationConstants struct. This contains a field for every specialization constant found in the shader data. Implementations of Default and SpecializationConstants are also generated for the struct.

All of these generated items will be accessed through the module when the macro was invoked. If you wanted to store the Shader in a struct of your own, you could do something like this:

// various use statements
// `vertex_shader` module with shader derive

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

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

Options

The options available are in the form of the following attributes:

ty: "..."

This defines what shader type the given GLSL source will be compiled into. The type can be any of the following:

• vertex
• fragment
• geometry
• tess_ctrl
• tess_eval
• compute

For details on what these shader types mean, see Vulkano’s documentation.

src: "..."

Provides the raw GLSL source to be compiled in the form of a string. Cannot be used in conjunction with the path or bytes field.

path: "..."

Provides the path to the GLSL source to be compiled, relative to Cargo.toml. Cannot be used in conjunction with the src or bytes field.

bytes: "..."

Provides the path to precompiled SPIR-V bytecode, relative to Cargo.toml. Cannot be used in conjunction with the src or path field. This allows using shaders compiled through a separate build system. Note: If your shader contains multiple entrypoints with different descriptor sets, you may also need to enable exact_entrypoint_interface.

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

With these options the user can compile several shaders at a single macro invocation. Each entry key is a suffix that will be put after the name of the generated load function and SpecializationConstants struct(FirstSpecializationConstants in this case). However all other Rust structs translated from the shader source will be shared between shaders. The macro checks that the source structs with the same names between different shaders have the same declaration signature, and throws a compile-time error if they don’t.

Each entry values expecting src, path, bytes, and ty pairs same as above.

Also SpecializationConstants can all be shared between shaders by specifying shared_constants: true, entry-flag of the shaders map. This feature is turned-off by default.

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

Specifies the standard include directories to be searched through when using the #include <...> directive within a shader source. Include directories can be absolute or relative to Cargo.toml. If path was specified, relative paths can also be used (#include "..."), without the need to specify one or more standard include directories. Relative paths are relative to the directory, which contains the source file the #include "..." directive is declared in.

define: [("NAME", "VALUE"), ...]

Adds the given macro definitions to the pre-processor. This is equivalent to passing -DNAME=VALUE on the command line.

vulkan_version: "major.minor" and spirv_version: "major.minor"

Sets the Vulkan and SPIR-V versions to compile into, respectively. These map directly to the set_target_env and set_target_spirv compile options. If neither option is specified, then SPIR-V 1.0 code targeting Vulkan 1.0 will be generated.

The generated code must be supported by the device at runtime. If not, then an error will be returned when calling Shader::load.

types_meta: { use a::b; #[derive(Clone, Default, PartialEq ...)] impl Eq }

Extends implementations of Rust structs that represent Shader structs.

By default each generated struct has a Clone and a Copy implementations only. If the struct has unsized members none of derives or impls applied on this struct.

The block may have as many use, derive or impl statements as needed and in any order.

Each use declaration will be added to generated ty module. And each derive’s trait and impl statement will be applied to each generated struct inside ty module.

For Default derive implementation fills a struct data with all zeroes. For Display and Debug derive implementation prints all fields except _dummyX. For PartialEq derive implementation all non-_dummyX are checking for equality.

The macro performs trivial checking for duplicate declarations. To see the final output of generated code the user can also use dump macro option(see below).

exact_entrypoint_interface: true

By default, the macro assumes that all resources (Uniforms, Storage Buffers, Images, Samplers, etc) need to be bound into a descriptor set, even if they are not used in the shader code. However, shaders with multiple entrypoints may have conflicting descriptor sets for each entrypoint. Enabling this option will force the macro to only generate descriptor information for resources that are used in each entrypoint.

The macro determines which resources are used by looking at each entrypoint’s interface and bytecode. See src/descriptor_sets.rs for the exact logic.

dump: true

The crate fails to compile but prints the generated rust code to stdout.

Macros

shader