Crate luminance

What is this?

luminance is an effort to make graphics rendering simple and elegant.

The aims of luminance are:

• Making the unsafe and stateful OpenGL API safe and stateless.
• Providing a simple and easy interface; that is, exposing core concepts without anything extra – just the bare stuff.
• Easy to read with a good documentation and set of tutorials, so that new comers don’t have to learn a lot of new concepts to get their feet wet.
• Need-driven: every piece of code added in the project must come from a real use case. If you feel something is missing, feel free to open an issue or even contribute!

What’s included?

luminance is a rendering framework, not a 3D engine nor a video game framework. As so, it doesn’t include specifics like lights, materials, asset management nor scene description. It only provides a rendering library you can plug in whatever you want to.

There are several so-called 3D-engines out there on crates.io. Feel free to have a look around.

Features set

• Buffers: buffers are way to communicate with the GPU; they represent regions of memory you can write to and read from. There’re several kinds of buffers you can create, among vertex and index buffers, shader buffers, uniform buffers, and so on and so forth….
• Framebuffers: framebuffers are used to hold renders. Each time you want to perform a render, you need to perform it into a framebuffer. Framebuffers can then be combined with each other to produce effects.
• Shaders: luminance supports five kinds of shader stages:
  • Tessellation control shaders.
  • Tessellation evaluation shaders.
  • Vertex shaders.
  • Geometry shaders.
  • Fragment shaders.
• Vertices, indices, primitives and tessellations: those are used to define a shape you can render into a framebuffer.
• Textures: textures represent information packed into arrays on the GPU, and can be used to customize a visual aspect or pass information around in shaders.
• Blending: blending is the process of taking two colors from two framebuffers and mixing them between each other.
• And a lot of other cool things like GPU commands, pipelines, uniform interfaces and so on…

How to dig in?

luminance is written to be fairly simple. The documentation is very transparent about what the library does and several articles will appear as the development goes on. Keep tuned! The online documentation is also a good link to have around.

Current implementation

Currently, luminance is powered by OpenGL 3.3. It might change, but it’ll always be in favor on supporting more devices and technologies – a shift to Vulkan is planned, for instance.

Windowing

luminance does not provide a way to create windows because it’s important that it not depend on windowing libraries – so that end-users can use whatever they like. Furthermore, such libraries typically implement windowing and events features, which have nothing to do with our initial purpose.

User-guide and contributor-guide

If you just plan to use luminance, just read the User-guide section.

If you plan to contribute to luminance (by writing a windowing crate or hacking on luminance directly), feel free to read the Contributor-guide section after having read the User-guid section as well.

User-guide

In order to get started, you need to create an object which type implements GraphicsContext. luminance ships with the trait but no implementor. You need to head over crates.io and search for luminance crates to find a windowing backend first.

Such a backend should expose a type which implements GraphicsContext. You can create one per thread. This limitation enables luminance not to perform plenty of runtime branching, minimizing the runtime overhead.

If you really want several contexts, you will need several OS threads.

GraphicsContext is the entry-point of everything luminance provides. Feel free to dig in its documentation for further information on how to use luminance. Most objects you can create will need a mutable reference to such a context object.

Contributor-guide

You want to hack around luminance or provide a windowing crate? Everything you have to know is described in this section.

GraphicsContext, GraphicsState and TLS

In order to implement GraphicsContext, you need to know several points:

• You can get a GraphicsState with the GraphicsState::new function. You have to match the return value. Depending on whether your implementation is the first asking a GraphicsState on the current thread, you might get (or not) an Ok(state). If not, a descriptive error is returned.
• You’re advised to map and map_err over the GraphicsState::new returned value to implement your own new function for your backend type because of the restriction of having only one context per thread in luminance.

Modules

blending	That module exports blending-related types and functions.
buffer	Static GPU typed arrays.
context	Graphics context.
depth_test	Depth test related features.
face_culling	Face culling is the operation of removing triangles if they’re facing the screen in a specific direction with a specific mode.
framebuffer	Framebuffers and utility types and functions.
gtup	Generalized free tuples.
linear	Aliases types used to make it easier using long linear algebra types.
pipeline	Dynamic rendering pipelines.
pixel	Pixel formats types and function manipulation.
render_state	GPU render state.
shader	Shader-related modules.
state	Graphics state.
tess	Tessellation features.
texture	This module provides texture features.
vertex	Vertex formats, associated types and functions.

Macros

gtup	Generalized free tuple macro.
gtup_ty
gtup_value
uniform_interface	Create a new struct that represents a uniform interface and automatically derive the impl for UniformInterface.
uniform_interface_build_struct
uniform_interface_impl_trait
uniform_interface_impl_trait_map