Crate vulkano_shader_derive[][src]

Procedural Macro glue for compile-time compilation of GLSL into SPIR-V

Basic usage

extern crate vulkano_shader_derive;
extern crate vulkano;
mod vertex_shader {
    #[ty = "vertex"]
    #[src = "
#version 450

layout(location = 0) in vec3 position;

void main() {
    gl_Position = vec4(position, 1.0);
    struct Dummy;


Due to the current limitations of procedural shaders in Rust, the current functionality of this crate is to base everything off of deriving VulkanoShader for a dummy struct that never actually gets used. When derived, the unused struct itself will be replaced by the functionality needed to use the shader in a Vulkano application. Due to the fact that a lot of what is generated will never be used, it's a good idea to put #[allow(unused)] on the module itself if you don't want to see irrelevant errors.

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 Shader struct. This contains a single field, shader, which is an Arc<ShaderModule>.
  • The Shader::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<Shader, OomError>. Before doing so, it loops through every capability instruction in the shader data, verifying that the passed-in Device has the appropriate features enabled. This function currently panics if a feature required by the shader is not enabled on the device. At some point in the future it will return an error instead.
  • The Shader::module method. This method simply returns a reference to the Arc<ShaderModule> contained within the shader field of the Shader struct.
  • Methods for each entry point of the shader module. These construct and return the various entry point structs that can be found in the vulkano::pipeline::shader module.
  • A Rust struct translated from each struct contained in the shader data.
  • The Layout newtype. This contains a ShaderStages struct. An implementation of PipelineLayoutDesc is also generated for the newtype.
  • 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 that you wrote to use the derive macro in. 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 vertex_shader: vertex_shader::Shader
impl Shaders {
    pub fn load(device: Arc<Device>) -> Result<Self, OomError> {
        Ok(Self {
            vertex_shader: vertex_shader::Shader::load(device)?,


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] attribute.

#[path = "..."]

Provides the path to the GLSL source to be compiled, relative to Cargo.toml. Cannot be used in conjunction with the #[src] attribute.