8 releases (4 breaking)

0.4.3+e670b39 Oct 15, 2024
0.4.2+b28b355 Sep 25, 2024
0.3.0 Sep 4, 2024
0.2.0 Sep 2, 2024
0.0.1 Feb 9, 2024

#346 in Graphics APIs

Download history 155/week @ 2024-08-25 887/week @ 2024-09-01 850/week @ 2024-09-08 1645/week @ 2024-09-15 1267/week @ 2024-09-22 1088/week @ 2024-09-29 750/week @ 2024-10-06 386/week @ 2024-10-13 486/week @ 2024-10-20 738/week @ 2024-10-27 656/week @ 2024-11-03 872/week @ 2024-11-10 978/week @ 2024-11-17 574/week @ 2024-11-24 606/week @ 2024-12-01

3,111 downloads per month
Used in 11 crates (2 directly)

MIT/Apache

11MB
265K SLoC

GLSL 211K SLoC // 0.0% comments C++ 49K SLoC // 0.1% comments Rust 4K SLoC // 0.0% comments Python 1K SLoC // 0.0% comments C 192 SLoC Shell 91 SLoC // 0.1% comments Swift 60 SLoC // 0.1% comments Assembly 55 SLoC // 0.1% comments AsciiDoc 6 SLoC // 0.3% comments

spirv-cross2

Safe and sound Rust bindings to SPIRV-Cross.

Latest Version Docs Crates.io MSRV License

All backends exposed by the SPIRV-Cross C API are fully supported, including

  • GLSL
  • HLSL
  • MSL
  • JSON
  • C++
  • Reflection Only

The API provided is roughly similar to the SPIRV-Cross Compiler C++ API, with some inspiration from naga. A best effort has been made to ensure that these bindings are sound, and that mutations occur strictly within Rust's borrow rules.

Usage

Here is an example of using the API to do some reflection and compile to GLSL.

use spirv_cross2::compile::{CompilableTarget, CompiledArtifact};
use spirv_cross2::{Module, SpirvCrossContext, SpirvCrossError};
use spirv_cross2::compile::glsl::GlslVersion;
use spirv_cross2::reflect::{DecorationValue, ResourceType};
use spirv_cross2::spirv;
use spirv_cross2::targets::Glsl;

fn compile_spirv(words: &[u32]) -> Result<CompiledArtifact<'static, Glsl>, SpirvCrossError> {
    let module = Module::from_words(words);
    let context = SpirvCrossContext::new()?;

    let mut compiler = context.into_compiler::<Glsl>(module)?;

    let resources = compiler.shader_resources()?;

    for resource in resources.resources_for_type(ResourceType::SampledImage)? {
        let Some(DecorationValue::Literal(set)) =
                compiler.decoration(resource.id,  spirv::Decoration::DescriptorSet)? else {
            continue;
        };
        let Some(DecorationValue::Literal(binding)) =
            compiler.decoration(resource.id,  spirv::Decoration::Binding)? else {
            continue;
        };

        println!("Image {} at set = {}, binding = {}", resource.name, set, binding);

        // Modify the decoration to prepare it for GLSL.
        compiler.set_decoration(resource.id, spirv::Decoration::DescriptorSet,
                DecorationValue::unset())?;

        // Some arbitrary remapping if we want.
        compiler.set_decoration(resource.id, spirv::Decoration::Binding,
            Some(set * 16 + binding))?;
    }

    let mut options = Glsl::options();
    options.version = GlslVersion::Glsl300Es;

    compiler.compile(&options)
}

Features

By default, the glsl, hlsl, and msl features are enabled by default. The cpp and json targets can be enabled in Cargo.toml

 [dependencies]
 spirv-cross2 = { features = ["cpp", "json"] }

SPIRV-Cross will only be built with support for enabled targets. If you want to only perform reflection and shrink the binary size, you can disable all but the None target.

 [dependencies]
 spirv-cross2 = { default-features = false }

To enable all features, including f16 and vector constant support, use the full feature.

 [dependencies]
 spirv-cross2 = { features = ["full"] }

f16 and vector specialization constants support

When querying specialization constants, spirv-cross2 includes optional support for f16 via half and vector and matrix types via glam and gfx-maths.

 [dependencies]
 spirv-cross2 = { features = ["f16", "gfx-maths-types", "glam-types"] }

License

This project is licensed under either of Apache License, Version 2.0 or MIT license, at your option.

Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed under the terms of both the Apache License, Version 2.0 and the MIT license without any additional terms or conditions.

Dependencies