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);
}"
}
}
# fn main() {}
```
# 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`][reflect] function in the `vulkano-shaders` crate) or use a tool
such as [cargo-expand][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`.
* The `Shader::load` constructor. This method takes an `Arc`, calls
[`ShaderModule::new`][ShaderModule::new] with the passed-in device and the
shader data provided via the macro, and returns `Result`.
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` 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][pipeline::shader] module.
* A Rust struct translated from each struct contained in the shader data.
By default each structure has a `Clone` and a `Copy` implemenetations. This
behavior could be customized through the `types_meta` macro option(see below
for details).
* The `Layout` newtype. This contains a [`ShaderStages`][ShaderStages] struct.
An implementation of [`PipelineLayoutDesc`][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`][SpecializationConstants] 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:
```
# fn main() {}
# use std::sync::Arc;
# use vulkano::OomError;
# use vulkano::device::Device;
#
# mod vs {
# vulkano_shaders::shader!{
# ty: "vertex",
# src: "
# #version 450
#
# layout(location = 0) in vec3 position;
#
# void main() {
# gl_Position = vec4(position, 1.0);
# }"
# }
# }
// various use statements
// `vertex_shader` module with shader derive
pub struct Shaders {
pub vs: vs::Shader
}
impl Shaders {
pub fn load(device: Arc) -> Result {
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][pipeline].
## `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.
## `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`][descriptor_sets]
for the exact logic.
## `dump: true`
The crate fails to compile but prints the generated rust code to stdout.
[reflect]: https://github.com/vulkano-rs/vulkano/blob/master/vulkano-shaders/src/lib.rs#L67
[cargo-expand]: https://github.com/dtolnay/cargo-expand
[ShaderModule::new]: https://docs.rs/vulkano/*/vulkano/pipeline/shader/struct.ShaderModule.html#method.new
[OomError]: https://docs.rs/vulkano/*/vulkano/enum.OomError.html
[pipeline::shader]: https://docs.rs/vulkano/*/vulkano/pipeline/shader/index.html
[descriptor]: https://docs.rs/vulkano/*/vulkano/descriptor/index.html
[ShaderStages]: https://docs.rs/vulkano/*/vulkano/descriptor/descriptor/struct.ShaderStages.html
[PipelineLayoutDesc]: https://docs.rs/vulkano/*/vulkano/descriptor/pipeline_layout/trait.PipelineLayoutDesc.html
[SpecializationConstants]: https://docs.rs/vulkano/*/vulkano/pipeline/shader/trait.SpecializationConstants.html
[pipeline]: https://docs.rs/vulkano/*/vulkano/pipeline/index.html
[descriptor_sets]: https://github.com/vulkano-rs/vulkano/blob/master/vulkano-shaders/src/descriptor_sets.rs#L142