52 releases (32 breaking)
0.34.0 | Oct 25, 2023 |
---|---|
0.33.0 | Apr 3, 2023 |
0.32.0 | Oct 31, 2022 |
0.30.0 | Jul 20, 2022 |
0.2.0 | Jul 28, 2016 |
#801 in Graphics APIs
4,299 downloads per month
Used in 63 crates
(47 directly)
4.5MB
91K
SLoC
The procedural macro for vulkano's shader system. Manages the compile-time compilation of GLSL into SPIR-V and generation of associated Rust code.
Basic usage
mod vs {
vulkano_shaders::shader!{
ty: "vertex",
src: r"
#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 option is to use cargo-expand to view the expansion of the macro in your own code. 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 function takes anArc<Device>
, constructs aShaderModule
with the passed-in device and the shader data provided via the macro, and returnsResult<Arc<ShaderModule>, Validated<VulkanError>>
. Before doing so, it checks every capability instruction in the shader data, verifying that the passed-inDevice
has the appropriate features enabled. - If the
shaders
option is used, then instead of oneload
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 aCopy
implementation. This behavior could be customized through thecustom_derives
macro option (see below for details). Each struct also has an implementation ofBufferContents
, so that it can be read from/written to a buffer.
All of these generated items will be accessed through the module where the macro was invoked.
If you wanted to store the ShaderModule
in a struct of your own, you could do something like
this:
#
#
#
// ...various use statements...
// ...`vs` module containing a `shader!` call...
pub struct Shaders {
pub vs: Arc<ShaderModule>,
}
impl Shaders {
pub fn load(device: Arc<Device>) -> Result<Self, Validated<VulkanError>> {
Ok(Self {
vs: vs::load(device)?,
})
}
}
Options
The options available are in the form of the following fields:
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
raygen
anyhit
closesthit
miss
intersection
callable
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 your Cargo.toml
. Cannot be
used in conjunction with the src
or bytes
field.
bytes: "..."
Provides the path to precompiled SPIR-V bytecode, relative to your Cargo.toml
. Cannot be used
in conjunction with the src
or path
field. This allows using shaders compiled through a
separate build system.
root_path_env: "..."
Instead of searching relative to your Cargo.toml
, search relative to some other folder
specified by this env variable. The intended use case is using OUT_DIR
to be able to load
shaders generated by your build script. Defaults to CARGO_MANIFEST_DIR
corresponding to the
folder of your Cargo.toml
.
See cargo-env-vars
for a full set of env variables set by cargo. It is also possible to
specify env variables from within the build script using the following:
println!("cargo:rustc-env=SHADER_OUT_DIR={shader_out_dir}");
shaders: { first: { src: "...", ty: "..." }, ... }
With these options the user can compile several shaders in a single macro invocation. Each
entry key will be the suffix of the generated load
function (load_first
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 expects a src
, path
, bytes
, and ty
pairs same as above.
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 your 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 the
-DNAME=VALUE
argument 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 load
.
custom_derives: [Clone, Default, PartialEq, ...]
Extends the list of derive macros that are added to the derive
attribute of Rust structs that
represent shader structs.
By default each generated struct has a derive for Clone
and Copy
. If the struct has unsized
members none of the derives are applied on the struct, except BufferContents
, which is
always derived.
linalg_type: "..."
Specifies the way that linear algebra types should be generated. It can be any of the following:
std
cgmath
nalgebra
The default is std
, which uses arrays to represent vectors and matrices. Note that if the
chosen crate doesn't have a type that represents a certain linear algebra type (e.g. mat3
, or
a rectangular matrix) then the macro will default back to arrays for that type.
If you use linear algebra types from a third-party crate, then you have to have the crate in
your dependencies with the appropriate feature enabled that adds bytemuck
support.
dump: true
The crate fails to compile but prints the generated Rust code to stdout.
Cargo features
Feature | Description |
---|---|
shaderc-build-from-source |
Build the shaderc library from source when compiling. |
shaderc-debug |
Compile shaders with debug information included. |
Dependencies
~41MB
~813K SLoC