Module luminance::framebuffer

Framebuffers and render targets.

A framebuffer is a GPU object which responsibility is to hold renders — i.e. a rasterized scene. Currently, a framebuffer is the only support of rendering: you cannot render directly into a texture. Instead, you have to use a Framebuffer, which automatically handles for you the texture creation, mapping and handling to receive renders.

Framebuffer creation

Framebuffers are created via the Framebuffer::new method. Creating framebuffers require a bit of explanation as it highly depends on refinement types. When you create a new framebuffer, you are required to provide types to drive the creation and subsequent possible operations you will be able to perform. Framebuffers have three important type variables:

• D, a type representing a dimension and that must implement Dimensionable. That types gives information on what kind of sizes and offsets a framebuffer will operate on/with.
• CS, a color slot. Color slots are described in the backend::color_slot module.
• DS, a depth slot. Depth slots are described in the backend::depth_slot module.

You are limited in which types you can choose — the list is visible as implementors of traits in backend::color_slot and backend::depth_slot.

Once a Framebuffer is created, you can do basically two main operations on it:

• Render things to it.
• Retreive color and depth slots to perform further operations.

Rendering to a framebuffer

Rendering is pretty straightforward: you have to use a PipelineGate to initiate a render by passing a reference on your Framebuffer. Once the pipeline is done, the Framebuffer contains the result of the render.

Manipulating slots

Slots’ types depend entirely on the types you choose in Framebuffer. The rule is that any type that implements ColorSlot will be associated another type: that other type (in this case, ColorSlot::ColorTextures will be the type you can use to manipulate textures. The same applies to DepthSlot with DepthSlot::DepthTexture.

You can access to the color slot via Framebuffer::color_slot. You can access to the depth slot via Framebuffer::depth_slot. Once you get textures from the color slots, you can use them as regular textures as input of next renders, for instance.

Note on type generation

Because framebuffers are highly subject to refinement typing, types are transformed at compile-time by using the type-system to provide you with a good and comfortable experience. If you use a single pixel format as color slot, for instance, you will get a single texture (whose pixel format will be the same as the type variable you set). The dimension of the texture will be set to the same as the framebuffer, too.

Now if you use a tuple of pixel formats, you will get a tuple of textures, each having the correct pixel format. That feature allows to generate complex types by using a pretty simple input type. This is what we call type constructors — type families in functional languages. All this look a bit magical but the type-system ensures it’s total and not as magic as you might think.

Structs

Framebuffer

Typed framebuffers.

Enums

FramebufferError	Framebuffer error.
IncompleteReason	Reason a framebuffer is incomplete.