luminance, the elegant, safe, type-safe, stateless and simple graphics crate
luminance is an effort to make graphics rendering simple and elegant. It was originally imagined,
designed and implemented by @phaazon in Haskell (here)
and eventually ported to Rust in 2016. The core concepts remained the same and the crate has been
slowly evolving ever since. At first, used only by @phaazon for his Rust demoscene productions
(example here and
spectra) and a bunch of curious peeps, it now has more visibility
among the graphics ecosystem of Rust.
Currently, that ecosystem is spread into several crates, ideas and people. It is highly
recommended to read the great article about the ecosystem by @Icefoxen, here.
However, luminance is a bit different from what it was initially imagined for. People are
looking for an easy-to-use crate, with good abstractions and safe-guards against all the bad and
dangerous graphics API caveats. luminance has always been about providing a safe, type-safe
and elegant API (being Haskell-based makes it heavily use the type system, for instance) but it now
has a more unique niche in the ecosystem. Where gfx-hal provides an experience focused
on down-to-metal performance and an API very similar to Vulkan’s, luminance provides an API
that is, for sure, a bit higher-level, and not Vulkan-based — and hence, yes, it likely won't give
you the same performances as with gfx-hal (though no benchmarks have been done so far) — but
easier to start with, especially if you don’t already have a background experience with OpenGL or Vulkan.
The strengths of luminance are:
- Easy to learn: the concepts, based on OpenGL, are applied to graphics, not general-purpose
programming on GPU. Using luminance will help you wrap your fingers around what graphics
programming is about and it will help you, perhaps, to jump to lower abstractions like
gfx-hal, if you ever need to.
- Performant: by using Rust and being designed around the concept of good performances,
luminance should allow you to build nice and fast simulations, animations and video games.
Remember that games you played years ago didn’t have Vulkan and were impressive nonetheless.
It’s unlikely you will get 100% out of your GPU by using luminance since it’s built over
technologies that are not using 100% of your GPU. Unless you need and know exactly why you need
100% of your GPU, you should be just fine™.
- Elegant: the design is heavily based on functional programming concepts such as typeclasses,
associated types, singleton types, existentials, contravariant resources, procedural macros,
strong typing, etc. Plus, every bit of possible stateful computations is hidden behind a
system of smart state, removing the need to worry about side-effects. luminance still has
mutation (unless its Haskell version) but the Rust type system and borrow checker allows for
- Modern: the whole luminance ecosystem tries its best to stay up-to-date with Rust evolutions
and features. On the same level, the underlying technologies are kept up-to-date and might even
be replaced if modern, better-suited alternatives emerge (similarly, Vulkan support might
eventually get added, though there are no immediate plans to do so).
Opinionated enough: a big bet with luminance was to make it opinionated, but not too much.
It needs to be opinionated to allow for some design constructs to be possible, optimize
performance and allow for extra safety. However, it must not be too opinionated, lest it become
a framework. luminance is a library, not a framework, meaning that it will adapt to
how you think you should design your software, not the other way around (within the limits of
safe design). luminance won't tie your hands.
The luminance ecosystem
It is currently composed of several different crates:
luminance: the core crate, exposing a graphics API that aims to be easy to learn, safe,
type-safe, stateless and fun!
luminance-derive: a companion crate to luminance you’re very likely to enjoy; it will help
you derive important traits for your application or library to work. You should definitely
invest some time in the documentation of this crate; it’s easy and well explained.
luminance-front: a front facing set of luminance re-exports to make it easy to use the
library as a end-user developer by picking a backend type at compile-time, most of the time
based on your compilation target.
luminance-gl: a crate gathering OpenGL backends. Several versions might be supported.
luminance-webgl: a crate gathering WebGL backends. Several versions might be supported.
examples: a combination of examples to show off some features / techniques.
luminance has two main and official resources to learn:
- The book. It contains various chapters,
including tutorials and onboarding newcomers. It will not provide you with the best description
of a given feature as it focuses more on the overall comprehension and explaining than code
directly. It also fits people who don’t know anything about rendering.
- The examples. They are like unit tests: each introduces and focuses on a very specific aspect
or feature. You should read them if you are interested in a specific feature. They’re not well
suited to learn from scratch and they are weaker than a structured tutorial but more concise.
They also provide functional tests as the backend-agnostic architecture allow to very easily add
You should try both ways and see which one fits the best for you!
Please read the CONTRIBUTING document.
Those projects use luminance:
luminance is licensed under BSD-3-Clause and the logo is under CC BY-ND.