common

Luminance examples

This crate holds several examples you can use to learn how to use luminance.

Each example comes in with a few explanations and how to use them at the top of the .rs file. A shared module is present so that the code can be shared and referenced from all examples. Don’t forget to go visit that file to understand more about how things work.

This crate is also used to implement functional tests. By default, they are not compiled, you need to set the "funtest" feature.

If you think a specific feature is missing, feel free to open a PR and add new examples! The more we have, the better! Also, keep in mind that this example repository is not the proper way to learn luminance as a whole! If you would like to learn from scratch, it is highly recommended to have a look at the book first.

Have fun!

• Prologue: architecture
• Hello World
• Hello World, more
• Render State
• Sliced Tessellation
• Shader Uniforms
• Attributeless Render
• Texture
• Offscreen
• Dynamic Uniform Interface
• Vertex Instancing
• Query texture texels
• Displacement Map
• Interactive triangle
• Skybox and environment mapping
• Texture resize
• Query information
• MRT (Multi Render Target)
• Uniform buffer

Prologue: architecture

Because the examples use a backend-agnostic approach, it is important to explain how they work. The general idea is defined in lib.rs file via several concepts:

• Example: most important trait, this interface defines what an example can actually do. The interface is purposefully general enough to allow the implementations to execute them the way they want.
• Features: a type allowing examples to instruct executors about some features they require and that must be loaded, enabled or checked before running the example.
• InputAction: an abstraction of user interaction. Because examples don’t assume anything about the running executor, we cannot assume a mouse or a keyboard will be used. Those are devices that implement an interface yielding a stream of InputAction.
• LoopFeedback: when a frame has finished rendering or must abort, it returns to the executor a value of type LoopFeedback, allowing to know whether execution should be aborted, and if not, what is the next step of the example.
• PlatformServices: various services provided by the platform executor to the examples, such as fetching textures.

01 – Hello World

Learn how to draw two colored triangles by using vertex colors. This first example is really important as it shows off lots of features that are necessary to wrap your fingers around, especially _namespaces, _vertex type declaration, derive procedural macros, graphics pipelines, etc. etc. All in all, everything is easy to grasp, yet very important.

Polymorphic Hello World

A variant of 01 – Hello World that shows more options for the vertex entities. It will teach you how to use interleaved, deinterleaved and indexed vertex entities (and mix of those!).

Render State

Learn how to change the render state to tweak the way primitives are rendered or how fragment blending happens.

Sliced Tessellation

Learn how to slice a single GPU geometry to dynamically select contiguous regions of it to render!

Shader Uniforms

Send colors and position information to the GPU to add interaction with a simple yet colorful triangle!

Attributeless Render

Render a triangle without sending any vertex data to the GPU!

Texture

Learn how to use a loaded image as a luminance texture on the GPU!

Offscreen

Get introduced to offscreen rendering, a powerful technique used to render frames into memory without directly displaying them on your screen. Offscreen framebuffers can be seen as a generalization of your screen.

Dynamic Uniform Interface

Implement a dynamic lookup for shader program the easy way by using program interfaces to query uniforms on the fly!

Vertex Instancing

Learn how to implement a famous technique known as vertex instancing, allowing to render multiple instances of the same object, each instances having their own properties.

Query texture texels

Query texture texels from a framebuffer and output them as a rendered image on your file system.

Displacement Map

Use a grayscale texture to implement a displacement map effect on a color map.

Interactive triangle

Learn how to move the triangle from the hello world with your mouse or cursor!

Skybox and environment mapping

Load a skybox from a file, display it and render a cube reflecting the sky!

Texture resize

This program is a showcase to demonstrate how you can use texture from an image loaded from the disk and re-use it to load another image with a different size.

Query information

Shows how to get some information about the backend and luminance.

MRT (Multi Render Target)

This program shows how to render a single triangle into an offscreen framebuffer with two target textures, and how to render the contents of these textures into the back buffer (i.e. the screen), combining data from both.

Uniform buffer

This example shows how to use uniform buffers to implement geometry instancing, a technique allowing to quickly render a large number of instances of the same model (here, a simple square). This example shows how to update all the squares’ positions at once in the render loop.