Procedural Macro glue for compile-time compilation of GLSL into SPIR-V
Basic usage
#[macro_use]
extern crate vulkano_shader_derive;
extern crate vulkano;
# fn main() {}
#[allow(unused)]
mod vertex_shader {
#[derive(VulkanoShader)]
#[ty = "vertex"]
#[src = "
#version 450
layout(location = 0) in vec3 position;
void main() {
gl_Position = vec4(position, 1.0);
}
"]
struct Dummy;
}
Details
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 anArc<ShaderModule>
. - The
Shader::load
constructor. This method takes anArc<Device>
, callsShaderModule::new
with the passed-in device and the shader data provided via the macro, and returnsResult<Shader, OomError>
. Before doing so, it loops through every capability instruction in the shader data, verifying that the passed-inDevice
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 theArc<ShaderModule>
contained within theshader
field of theShader
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 aShaderStages
struct. An implementation ofPipelineLayoutDesc
is also generated for the newtype. - The
SpecializationConstants
struct. This contains a field for every specialization constant found in the shader data. Implementations ofDefault
andSpecializationConstants
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:
# #[macro_use]
# extern crate vulkano_shader_derive;
# extern crate vulkano;
# fn main() {}
# use std::sync::Arc;
# use vulkano::OomError;
# use vulkano::device::Device;
#
# #[allow(unused)]
# mod vertex_shader {
# #[derive(VulkanoShader)]
# #[ty = "vertex"]
# #[src = "
# #version 450
#
# layout(location = 0) in vec3 position;
#
# void main() {
# gl_Position = vec4(position, 1.0);
# }
# "]
# struct Dummy;
# }
// 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)?,
})
}
}
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]
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.