Crate spirv_cross2

Expand description

Safe and sound Rust bindings to SPIRV-Cross.

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

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.

§Strings

Methods on Compiler return and accept CompilerStr instead of a normal string type. A CompilerStr may or may not be owned by the compiler, or may come from Rust. Rust string types can be coerced automatically to CompilerStr as an input, and CompilerStr can easily be copied to a Rust string type.

If a returned CompilerStr is backed by immutable memory, it will have a 'static lifetime.

If instead the underlying string data could possibly be modified by set_ functions, they will only have a lifetime corresponding to the lifetime of the immutable borrow of the Compiler that produced them. References to these short-lived strings can not be alive before calling a mutating function.

Strings will automatically allocate as needed when passed to FFI. Rust String and &str may allocate to create a nul-terminated string. Strings coming from FFI will not reallocate, and the pointer will be passed directly back. Rust &CStr will not reallocate.

If you are just passing in a string constant using a C-string literal will be the most efficient. Otherwise, it is always better to work with Rust String and &str, if you are dynamically building up a string. In particular, String will not reallocate if there is enough capacity to append a nul byte before being passed to FFI.

§Handles

All reflected SPIR-V IDs are returned as Handle<T>, where the u32 ID part can be retrieved with Handle::id. Handles are tagged with the pointer of the compiler instance they came from, and are required to ensure safety such that reflection queries aren’t made between different SPIR-V modules.

Any function that takes or returns SPIR-V handles in the SPIRV-Cross API has been wrapped to accept Handle<T> in this crate.

Handles can be unsafely forged with Compiler::create_handle, but there are very few if any situations where this would be needed.

§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"] }

§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::{Compiler, Module, 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<Glsl>, SpirvCrossError> {
    let module = Module::from_words(words);

    let mut compiler = Compiler::<Glsl>::new(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)
}

Modules§

compile: Compilation of SPIR-V to a textual format.
handle: Handles to SPIR-V IDs from reflection.
reflect: SPIR-V reflection helpers and types.
spirv: SPIR-V types and definitions.
targets: Compiler output targets.

Structs§

Compiler: An instance of a SPIRV-Cross compiler.
CompilerStr: An immutable wrapper around a valid UTF-8 string whose memory contents may or may not be originating from FFI.
Module: A SPIR-V Module represented as SPIR-V words.

Enums§

SpirvCrossError: Error type for SPIR-V Cross.

Traits§

ToStatic: Helper trait to detach objects with lifetimes attached to a compiler or context.

Crate spirv_cross2Copy item path