Crate vulkano_shaders[−][src]
Expand description
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
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.
By default each structure has a
Clone
and aCopy
implemenetations. This behavior could be customized through thetypes_meta
macro option(see below for details). - 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 specified
by mod_name: foo
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: vs::Shader } impl Shaders { pub fn load(device: Arc<Device>) -> Result<Self, OomError> { Ok(Self { vs: vs::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
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
.
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 |