Skip to content

/ gfx

A low-overhead Vulkan-like GPU API for Rust.
graphics-apis rust gfx opengl vulkan metal dx12 dx11 graphics gpu
Rust Other
  1. Rust 98.6%
  2. Other 1.4%
Branch: master
Find file
Clone or download

Clone with HTTPS

Use Git or checkout with SVN using the web URL.

Open in Desktop Download ZIP

Latest commit

@bors @cwfitzgerald
bors and cwfitzgerald Merge #3272 
3272: [master] Port #3271 to Master r=kvark a=cwfitzgerald

Ports #3271 to master.

This is not a completely trivial port, as I needed to integrate the mesh shader work into the existing extension infrastructure. No major unsafe code was changed however.

Co-authored-by: Connor Fitzgerald <connorwadefitzgerald@gmail.com>
Latest commit b8727da Jun 13, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update CONTRIBUTING.md Jan 31, 2020
examples Move pso::Stage to auxil::ShaderStage Jun 1, 2020
info Add links to tutorials on how to use gfx Apr 10, 2020
src Implement Descriptor Indexing Jun 12, 2020
work Update Warden to refactor features and make queries optional Mar 20, 2020
.gitignore gl: Add instructions for wasm Jun 6, 2019
.monocodus Update .monocodus Apr 28, 2020
.travis.yml [webgpu] Instance creation May 19, 2020
CHANGELOG.md [dx12] implement descriptor pool destruction, bump version May 31, 2020
Cargo.toml Add WebGPU backend using `web-sys` May 15, 2020
LICENSE-APACHE Move to dual license, see #847 Jun 9, 2018
LICENSE-MIT Move to dual license, see #847 Jun 9, 2018
Makefile [webgpu] Instance creation May 19, 2020
README.md Readme update Mar 23, 2020
bors.toml Remove appveyor CI Jan 17, 2019
rustfmt.toml Some long-needed rustfmt changes Jun 25, 2019

README.md

Matrix room gfx-hal on crates.io Travis Build Status
Getting Started | Documentation | Blog

gfx-rs

gfx-rs is a low-level, cross-platform graphics and compute abstraction library in Rust. It consists of the following components:

  • gfx-hal which is gfx's hardware abstraction layer: a Vulkan-ic mostly unsafe API which translates to native graphics backends.
  • gfx-backend-* which contains graphics backends for various platforms:
  • gfx-warden which is a data-driven reference test framework, used to verify consistency across all graphics backends.

gfx-rs is hard to use, it's recommended for performance-sensitive libraries and engines. If that's not your domain, take a look at wgpu-rs for a safe and simple alternative.

The gfx crate

This repository was originally home to the gfx crate, which is now deprecated. You can find the latest versions of the code for that crate in the pre-ll branch of this repository.

The master branch of this repository is now focused on developing gfx-hal and its associated backend and helper libraries, as described above. gfx-hal is a complete rewrite of gfx, but it is not necessarily the direct successor to gfx. Instead, it serves a different purpose than the original gfx crate, by being "lower level" than the original. Hence, the name of gfx-hal was originally ll, which stands for "lower level", and the original gfx is now referred to as pre-ll.

The spiritual successor to the original gfx is actually wgpu, which stands on a similar level of abstraction to the old gfx crate, but with a modernized API that is more fit for being used over Vulkan/DX12/Metal. If you want something similar to the old gfx crate that is being actively developed, wgpu is probably what you're looking for, rather than gfx-hal.

Example

To run an example, simply cd to the examples directory, then use cargo run with --features {backend} to specify the backend (where {backend} is either vulkan, dx12, dx11, metal, or gl). For example:

# Clone the gfx repository
git clone https://github.com/gfx-rs/gfx
# Change directory to `examples`
cd gfx/examples
# Vulkan
cargo run --bin quad --features vulkan
# Metal (macOS/iOS)
cargo run --bin quad --features metal
# DirectX12 (Windows)
cargo run --bin compute --features dx12 1 2 3 4

This runs the quad example using the Vulkan backend, and then the compute example using the DirectX 12 backend.

These examples assume that necessary dependencies for the graphics backend are already installed. For more information about installation and usage, refer to the Getting Started guide.

Hardware Abstraction Layer

The Hardware Abstraction Layer (HAL), is a thin, low-level graphics and compute layer which translates API calls to various backends, which allows for cross-platform support. The API of this layer is based on the Vulkan API, adapted to be more Rust-friendly.

Hardware Abstraction Layer (HAL)

Currently HAL has backends for Vulkan, DirectX 12/11, Metal, and OpenGL/OpenGL ES/WebGL.

The HAL layer is consumed directly by user applications or libraries. HAL is also used in efforts such as gfx-portability.

Previously Released Crates and API (pre-LL)

The code in master is a complete low-level rewrite of gfx based on HAL as described above.

The previously released crates (gfx_core, gfx, gfx_device_*, gfx_window_) are still being developed and published from the pre-ll (pre-low level rewrite) branch.

Contributing

We are actively looking for new contributors and aim to be welcoming and helpful to anyone that is interested! We know the code base can be a bit intimidating in size and depth at first, and to this end we have a label on the issue tracker which marks issues that are new contributor friendly and have some basic direction for completion in the issue comments. If you have any questions about any of these issues (or any other issues) you may want to work on, please comment on GitHub and/or drop a message in our Matrix chat!

License

This repository is licensed under either of

at your option.

Contribution Licensing

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.

You can’t perform that action at this time.