by rust-tutorials

rust-tutorials / learn-gfx-hal

Step by step tutorials for gfx-hal

210 Stars 38 Forks Last release: Not found Apache License 2.0 265 Commits 1 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

License:Apache2 AppVeyor travis.ci


Project Status

We're in long term maintenance mode!

This teaches you how to use

, but 99% of the world shouldn't be using
directly in the first place. It's absolutely important to know what's going on, but then you should move to a higher level API. Which API? Well, right now rendy is your best bet. Is there a book you can read for that once you're done with this book? Thanks to
, yes there is.


puts out new releases the tutorials will be updated so that they always work with the latest release of
, and I'll accept submissions if people want to add more examples and the lessons that go with them, but I don't plan on adding new lessons myself.


Step by step tutorials for using the gfx-hal crate.

The tutorials all target the current version on crates.io, not on the master branch of git. At the time of me writing this that means


This is not intended to be a library crate for you to just import into your own projects. It is a series of examples and explanations for you read and learn from.

  • The lessons are in the
    directory in markdown form. They can be rendered to HTML with mdbook, and the GitHub Pages site for this repository hosts a rendered version of the master branch.
  • The fully working examples are in the
    directory. Each example attempts to be a single file that works on its own, so in some cases the code style isn't quite what you'd want on a full project (eg: shader code contained in string literals instead of saved in separate files).

The code examples are not meant to be taken alone. There is effectively zero explanation within the code files themselves. You are absolutely encouraged to read the lesson text that goes with each example.

Learning More

The lessons here mostly focus on the particulars of how to get the output you want with

. Some information on graphical techniques in general will eventually be covered, but I can only cover so much material so fast.

If you want a whole lot more about general graphical stuff there's a large number of free books on the RealTimeRendering.com website. It's mostly their older editions, but the math for ray tracing or lighting or whatever else is all is still accurate enough. Once you know enough about how

does things you should be able to pick any book off of that list and convert the techniques shown (usually C++ and OpenGL) over into your own code (Rust and


Uses shaderc-rs, please follow their setup instructions.

  • Regarding
    on Windows: Note that the first time you run the
    command they list it doesn't install the packages. Instead it actually just installs the latest pacman and msys files. You have to then run the
    command again to make it actually download the stuff (and if you ran it from within the msys2 terminal you have to close that terminal and open a new one).
    • Yes, that is totally stupid, but it is also real advice that you must follow in this, the year of our lord two thousand and nineteen, if you want to program 3D graphics programs on windows.
  • When they say "the msys2 mingw64 binary path" they mean
    (assuming that you installed to


This repo is Apache 2 licensed and all of your contributions must be made under that license.


Hello. The primary ~~author~~ quixotic fool of this project is me, Lokathor. I explain things in a way that beginners can hopefully understand by not actually knowing anything about it myself. I get advice and guidance from the gfx-rs team when writing each lesson, but the final editorial sign off is mine, and and crazy or stupid opinions that you find here are mine alone, not any fault of theirs.

If there are mistakes that have crept in anywhere please file an issue. You can also attempt to contact me interactively on the

channel of the community discord.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.