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.1.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("libmetalirconverter.dylib").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
• IRMetalLibBinary
• IRObject
• IRRootSignature
• IRShaderReflection
• 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().