Documentation | Tutorial | Blog

gfx-rs

gfx is a high-performance, bindless graphics API for the Rust programming language. It aims to be the default API for Rust graphics: for one-off applications, or higher level libraries or engines.

Under Construction

gfx-rs is undergoing severe changes now with transition to the new low-level core. All the following sections apply to the pre-ll branch and will be outdated soon. The new development focus is on zero-cost low-level abstraction of current-gen graphics APIs, such as Vulkan, D3D12, and Metal.

---

Motivation

• Graphics APIs are mostly designed with C and C++ in mind, and hence are dangerous and error prone, with little static safety guarantees.
• Providing type safe wrappers around platform-specific APIs is feasible, but only pushes the problem of platform independence to a higher level of abstraction, often to the game or rendering engine.
• Modern graphics APIs, whilst providing a great degree of flexibility and a high level of performance, often have a much higher barrier to entry than traditional fixed-function APIs.
• Graphics APIs like OpenGL still require the developer to 'bind' and 'unbind' objects in order to perform operations on them. This results in a large amount of boiler plate code, and brings with it the usual problems associated with global state.

Features

Graphics backends:

• OpenGL 2.1+
• OpenGL ES2+ (works on Android)
• Direct3D 11
• Metal (WIP 75%)
• Vulkan (WIP 40%)

Hardware features:

• off-screen render targets
• multisampling
• instancing
• geometry shaders
• tessellation
• computing
• persistent mapping

Who's using it?

Biggest open-source projects are:

• Amethyst engine
• ggez engine
• Piston engine - 2d graphics
• LazyBox engine
• Vange-rs game
• Zemeroth game
• Rust-quake level viewer
• Rust-oids game

Shiny screens, including some older projects:

Getting started

If you want to build your own stand-alone gfx program, add the following to your new Cargo.toml:

[dependencies]
gfx = "0.16"

or, if you want the absolute latest commits to master, you can instead add.

[dependencies]
gfx = { git = "https://github.com/gfx-rs/gfx.git" }

For gfx to work, it needs access to the graphics system of the OS. This is typically provided through some window initialization API. gfx can use a couple of those to acquire graphical contexts. For example; glfw or glutin.

To see how the graphic context is acquired, see the cube example or the triangle example.

To use glutin, for example, your Cargo.toml must be extended with the following dependencies:

[dependencies]
...
glutin ="*"
gfx_window_glutin = "*"

Alternatively, an excellent introduction into gfx and its related crates can be found here.

Running the Examples

The examples directory contains all the examples for GFX, as well as the accompanying documentation for understanding and running those examples.

Structure and current versions

gfx consist of several crates. You can find all of them in this repository.

Core functionality:	Graphic backends:	Window backends:

Note

gfx is still in development. API may change with new backends/features to be implemented. If you are interested in helping out, checkout contrib.md and do not hesitate to contact the developers on Gitter.