[−][src]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 implementDimensionable
. 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. |