Usage examples
A
framebuffer
in OpenGL is an
opaque structure with one or more
attachments.
Currently, attachments can only be
textures.
Textures are useful when the result of rendering to a framebuffer is
going to be read back at some point, or perhaps used to texture
other objects. For example, some 3D engines implement so-called
"procedural textures" by rendering a generated pattern to a texture
and then applying that texture to objects in the scene.
Attachments are attached at specific points to
any given framebuffer: Framebuffers can have a
depth
attachment, a
stencil
attachment, a
depth+stencil
attachment, and an implementation-defined maximum number of
color
attachments.
When rendering to a framebuffer, a
shading program
will write values
to one or moredraw buffers, and
each
draw buffer
is mapped to a
color attachments. Multiple
draw buffers cannot be mapped to the same color attachment.
In jcanephora, framebuffers
are created via mutable builders which are then passed to the
API functions, resulting in immutable framebuffers
.
To attach allocated textures/buffers to a framebuffer, the API requires
the programmer to first obtain a list of the available attachment
points:
Similarly, the API requires the programmer to obtain a list of the
available draw buffers:
The programmer must pass values of type
JCGLFramebufferColorAttachmentPointType
to various attachment functions and is therefore statically prevented
from
trying to use more color attachments than the OpenGL implementation
allows.
After allocating a color and depth/stencil texture, the textures must
be attached at the relevant attachment points and draw buffers mapped
to the color attachments.
All unspecified draw buffers are mapped to
GL_NONE
(meaning that any data
written to the other draw buffers will go nowhere). The builders
also raise exceptions if the programmer attempts to, for example,
specify a non-color-renderable format for a color attachment.
To actually allocate a framebuffer, the mutable builder is passed to
an allocation function:
The function validates the framebuffer configuration upon allocation,
raising an exception if the framebuffer is not usable on the current
OpenGL implementation.
To render to the framebuffer, the framebuffer must be bound: