Crate saxaboom

🤘 Saxaboom

saxaboom is a small helper library around Metal shader converter to create metal shader libraries from DXIL files (HLSL source code). See also saxaboom-runtime which provides the runtime structures and interop with the metal crate needed to make use of the resulting metallib shaders.

Usage

Add this to your Cargo.toml:

[dependencies]
saxaboom = "0.2.0"

Example to compile DXIL to metallib:

use saxaboom::{ffi, MetalIrConverter};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load the library
    let metal_irconverter =
        MetalIrConverter::new(libloading::library_filename("metalirconverter")).unwrap();
    // Create an instance of IRCompiler
    let mut compiler = metal_irconverter.create_compiler();
    // Create an object containing DXIL bytes, replace &[0u8] with your DXIL data
    let dxil = metal_irconverter.create_object_from_dxil(&[0u8]);

    // See `IRCompiler` docs for possible state that can be set on the compiler before compiling
    // DXIL source, such as a global root signatures and various raytracing parameters.

    // Compile the `dxil` data blob with entrypoint `main` into mtllib
    let mtllib = compiler.alloc_compile_and_link(c"main", &dxil)?;

    let reflection = mtllib.reflection();
    let mtl_binary = mtllib
        .metal_lib_binary()
        .expect("Compiled object should contain a `metallib`");
    let bytecode = mtl_binary.byte_code();

    Ok(())
}

For using the loaded metallib shaders at runtime most effectively, consult saxaboom-runtime.

Re-exports

pub use bindings as ffi;

Modules

bindings

Structs

CompilerError

Captures errors returned by IRCompiler::alloc_compile_and_link().

IRCompiler

This object is not thread-safe, refer to the Metal shader converter documentation, the “Multithreading considerations” chapter.

IRError

IRInputLayoutDescriptor1

IRMetalLibBinary

IRObject

IRRootSignature

IRShaderReflection

IRVersionedASInfo

IRVersionedCSInfo

IRVersionedDSInfo

IRVersionedFSInfo

IRVersionedGSInfo

IRVersionedHSInfo

IRVersionedMSInfo

IRVersionedRTInfo

IRVersionedVSInfo

MetalIrConverter

MetalIrConverter is used to load the metal_irconverter dynamic library and holds its functions in an Arc. Since IRCompiler is not thread-safe, this struct provides an interface to create IRCompiler instances as well as other objects provided by the library (IRObject, IRRootSignature), without needing an IRCompiler instance. This way, the library only has to be loaded once, but each thread can have its own IRCompiler instance.

RootSignatureError

Captures errors returned by MetalIrConverter::create_root_signature_from_descriptor().