Rafx is a multi-backend renderer that prioritizes performance, flexibility, and productivity. It optionally integrates
with the distill
asset pipeline to provide workflows and tools suitable
for real-world projects with multidisciplinary teams.
This crate contains several layers:
rafx-api
: Low-level graphics API abstractionrafx-visibility
: Low-level retained API for visibility determinationrafx-framework
: Mid-level framework that eases resource management, lifetime handling, and draw call dispatchingrafx-assets
: Asset layer that integrates with distill
rafx-renderer
: A pipelined renderer with a plugin system for customizing itrafx-plugins
: Implementations of many basic and advanced rendering techniques and featuresRafx also provides tools for building shaders and assets.
Amazon Lumberyard Bistro scene (Original assets: https://developer.nvidia.com/orca/amazon-lumberyard-bistro)
[^ Video of this renderer running on iOS hardware](https://www.youtube.com/watch?v=Ks_HQbejHE4)
(Tilemap screenshot is an imported ldtk project file)
Rafx supports most mainstream platforms. Proprietary platforms can be supported by adding an additional backend.
Platform | Vulkan | Metal | DX12 | GL ES 3.0 (4,5,6) |
---|---|---|---|---|
Windows | ✅ | ✅ | ✅ | |
macOS | ✅ | ✅ | ✅ | |
Linux | ✅ (1) | ✅ (1) | ||
iOS | ✅ | ✅ | 🟥 (3) | |
Android | 🟨 (2) | 🟥 (3) | ||
WebGL (6) | ✅ |
Caveats:
Please keep in mind, this crate is still in pre-0.1.0 status!
cargo doc --no-deps --open
in the root of the crate (docs.rs is incomplete because it does not build with features)rafx-api
is unlikely to change significantlyThis crate will use semantic versioning rules after 0.1.0 of this project has been published. The 0.0.x versions do not follow semantic versioning rules.
Rafx is unsafe because hardware-accelerated rendering is fundamentally unsafe. However, we reserve usage of the unsafe keyword for when an operation can produce undefined behavior for reasons other than interacting with the GPU. Please see these documents for more detail:
CMake must be available on your path. It is used by SDL2 in the demo and by upstream crates used within the shader pipeline.
The demo should be run from within the demo directory of the repository. These commands should clone the repo and run the demo.
git clone https://github.com/aclysma/rafx.git
cd rafx
cd demo
cargo run --bin demo --release --features "[BACKEND_FEATURE]"
BACKEND_FEATURE should either be rafx-vulkan
, rafx-metal
, or some other backend.
Running in release reduces logging and disables GPU validation. The first time it will load more slowly because it has to import the assets, including a GLTF mesh with large textures. Using profile overrides to optimize upstream crates is highly recommeneded. Asset processing is extremely slow in debug mode. (i.e. 30s instead of 2s)
The renderer includes a few tools for processing shaders and packing data in a binary blob.
There is also a blender add-on that works, but is still being prototyped and is not yet documented.
This tool parses GLSL and produces matching rust code. This makes working with descriptor sets easier and safer!
shaders
crate to compile the generated rust code. It’s located at /demo/shaders.
Just the rust code is auto-generated, not the Cargo.toml.cargo install rafx-shader-processor
. Be sure to install the same version as you include in your project.
Also, don’t forget to update it if you update your project’s dependencies!The shader processor produces the following assets artifacts
The shader package can be loaded as an asset and contains everything needed to load a compiled shader.
This tool currently is only useful for packing assets.
run --package cli -- --pack out.pack
run --package demo -- --packfile out.pack
There is also a blender addon that implements workflows for larger levels and exports a custom format that avoids duplicating shared asset data. While it functions, it is still early in implementation and not yet documented.
[^ Video of slice-based level editing in Blender](https://www.youtube.com/watch?v=N6s40XwAghE)
This video shows a scene with >5k objects, 1M+ verts being loaded at once in blender and sliced into multiple smaller pieces on an M1 mac mini.
rafx-vulkan
: Use the vulkan backendrafx-metal
: Use the metal backendframework
: Include and re-export rafx-framework from the rafx crateassets
: Include and re-export rafx-assets from the rafx craterenderer
: Include and re-export rafx-renderer from the rafx craterafx-base
- Shared helpers/data structures. Nothing excitingrafx-api
- Rendering API abstraction layer.
rafx-visibility
- Retained visibility API.
rafx-framework
- Resource management for images, buffers, descriptor sets, etc.
rafx-visibility
rafx-assets
- An asset loading and management system.
rafx-renderer
- A pipelined renderer with a plugin system for customizing itQ: Why am I getting mysterious panics from a bincode serializer
A: Assets are imported and serialized via serde to bincode. If any of these structs are modified, the asset needs to be reimported. The “proper” fix is to bump the importer’s version, which will force re-importing affected assets. However, deleting .assets_db is an easy fix. In general to avoid this, we should not commit modifications to these structs without also bumping the importer version numbers.
Licensed under either of
at your option.
The demo/fonts directory contains several fonts under their own licenses:
mplus-1p-regular.ttf
, available under its own license.The assets/blender directory contains some shaders from from https://freepbr.com, available under its own license
The skyboxes are from:
assets/ldtk contains sample data from LDTK level editor (MIT):
Some dependencies may be licensed under other terms. These licenses include “ISC”, “CC0-1.0”, “BSD-2-Clause”, “BSD-3-Clause”, and “Zlib”. This is validated on a best-effort basis in every CI run using cargo-deny.
Rafx benefits from many great ideas and projects!
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.
See LICENSE-APACHE and LICENSE-MIT.