ash-molten/README.md
Marijn Suijten 2d8c62373f
lib: Provide entrypoint through Ash loader w.o. implementing Entry (#56)
* lib: Provide entrypoint through Ash loader w.o. implementing Entry

Ash recently [dropped all traits](1) to simplify `ash::Device` usage,
but this also disallows ash-molten from overriding the `EntryV1_0` trait
to provide a static entrypoint intead.

Fortunately ash-molten can simply pass a library loading closure that
returns the static address of `vkGetInstanceProcAddr` to
`EntryCustom::new_custom`, getting rid of the copied `fn
create_instance` implementation at the same time.

[1]: https://github.com/MaikKlein/ash/pull/412

* cargo: Disable unneeded `libloading` feature in Ash

The entry-point is statically linked from `MoltenVK` and does not need
any dlopen nor dlsym functionality.

* Fix some typos
2021-10-14 09:46:24 +00:00

4.7 KiB

🌋 ash-molten

Embark Embark Crates.io Docs dependency status Build status

ash-molten is built on top of ash and exposes a new entry point to statically link with MoltenVK.

Requires Xcode 12 and Mac OS 10.15 (Catalina) to compile.

Why?

  • You want to compile down to a single binary that doesn't need any environment variables to bet set.

  • You just want to try out MoltenVK without needing to setup the SDK.

Why not?

  • ash already supports MoltenVK via runtime linking. Runtime linking is the preferred way of using Vulkan because the loader can be updated at anytime without needing to recompile.

  • ash-molten doesn't have access to the validation layers and therefore can not output any debug information.

How?

let entry = ash_molten::MoltenEntry::load().expect("Unable to load Molten");
let app_name = CString::new("Hello Static Molten").unwrap();

let appinfo = vk::ApplicationInfo::builder()
    .application_name(&app_name)
    .application_version(0)
    .engine_name(&app_name)
    .engine_version(0)
    .api_version(vk_make_version!(1, 0, 0));

let create_info = vk::InstanceCreateInfo::builder().application_info(&appinfo);
let instance = entry.create_instance(&create_info, None).expect("Instance");
let devices = instance.enumerate_physical_devices();
println!("{:?}", devices);

You can run the example with cargo run.

How does it work?

ash-molten links statically with MoltenVK, it then uses vkGetInstanceProcAddr to resolve all the function pointers at runtime.

Features

cargo build will clone a specific release of MoltenVK compile and statically link it with your application. cargo build --features pre-built will download a pre-built version of MoltenVK from a release of ash-molten. cargo build --features external provide own MoltenVK library.

If you want to compile MoltenVK yourself, you can use the external feature. cargo build --features external requires libMoltenVK to be visible (LD_LIBRARY_PATH).

How to update

To update the version of MoltenVK uses, change the following:

  • In build.rs, change static VERSION = "1.1.0" to the new MoltenVK release tag name
  • Update the crate version in Cargo.toml
    • Bump the patch version
    • Set the version metadata to the MoltenVK release.
    • E.g. 0.2.0+37 -> 0.2.1+38.

Updating pre-built version

To update the prebuilt version uses, change the following:

  • Follow the steps mentioned above.
  • Download the MoltenVK XCFramework from, for example, the Vulkan SDK for Mac or build MoltenVK yourself.
    • in the case of downloading it from an external source make sure MoltenVK version matches static VERSION.
  • From the XCFramework folder, from the built version of MoltenVK, zip the folders of platforms that need to be supported individually.
  • Create a release with the tag: MoltenVK-{version number}.
  • Upload the zip files to the release with the MoltenVK-{version number} tag.

Contributing

Contributor Covenant

We welcome community contributions to this project.

Please read our Contributor Guide for more information on how to get started.

License

Licensed under either of

at your option.

Contribution

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 as above, without any additional terms or conditions.