Module processing::framebuffer

Framebuffers allow you to customize the color, depth and stencil buffers you will draw on.

In order to draw on a texture, use a SimpleFrameBuffer. This framebuffer is compatible with shaders that write to gl_FragColor.

let framebuffer = glium::framebuffer::SimpleFrameBuffer::new(&display, &texture);
// framebuffer.draw(...);    // draws over `texture`

If, however, your shader wants to write to multiple color buffers at once, you must use a MultiOutputFrameBuffer.

let output = [ ("output1", &texture1), ("output2", &texture2) ];
let framebuffer = glium::framebuffer::MultiOutputFrameBuffer::new(&display, output.iter().cloned());
// framebuffer.draw(...);

// example shader:
//
//     out vec4 output1;
//     out vec4 output2;
//
//     void main() {
//         output1 = vec4(0.0, 0.0, 0.5, 1.0);
//         output2 = vec4(1.0, 0.7, 1.0, 1.0);
//     }

Note: depth-stencil attachments are not yet implemented.

A note on restrictions

Some restrictions apply when you use framebuffers:

• All textures must have an internal format that is renderable. Not all formats are supported.

• All attachments must have the same number of samples, or must all have multisampling disabled. For example you can't create a texture with 4x multisampling, another texture with 2x multisampling, and draw on them simultaneously.

• On old hardware all the framebuffer attachments must have the same dimensions (on more recent hardware the intersection between all the attachments is taken if all attachments don't have the same dimensions). You can use the is_dimensions_mismatch_supported function to check what the hardware supports.

• You will get undefined results if you try to sample to a texture mipmap attached to the framebuffer that you are using. This is not enforced by glium as it depends on your shader's source code.

Empty framebuffers

Modern OpenGL implementations support empty framebuffers. This is handled by glium with the EmptyFrameBuffer struct.

You can check whether they are supported by calling EmptyFrameBuffer::is_supported(&display).

Layered framebuffers

Not yet supported

Structs

DefaultFramebuffer	A framebuffer which has only one color attachment.
DepthRenderBuffer	A render buffer is similar to a texture, but is optimized for usage as a draw target.
DepthStencilRenderBuffer	A render buffer is similar to a texture, but is optimized for usage as a draw target.
EmptyFrameBuffer	A framebuffer with no attachment at all.
MultiOutputFrameBuffer	This struct is useless for the moment.
RenderBuffer	A render buffer is similar to a texture, but is optimized for usage as a draw target.
RenderBufferAny	A RenderBuffer of indeterminate type.
SimpleFrameBuffer	A framebuffer which has only one color attachment.
StencilRenderBuffer	A render buffer is similar to a texture, but is optimized for usage as a draw target.

Enums

ColorAttachment	Describes an attachment for a color buffer.
DefaultFramebufferAttachment	One of the color attachments on the default framebuffer.
DepthAttachment	Describes an attachment for a depth buffer.
DepthStencilAttachment	Describes an attachment for a depth and stencil buffer.
RenderBufferCreationError	Error while creating a render buffer.
StencilAttachment	Describes an attachment for a stencil buffer.
ValidationError	An error that can happen while validating attachments.

Traits

ToColorAttachment	Trait for objects that can be used as color attachments.
ToDepthAttachment	Trait for objects that can be used as depth attachments.
ToDepthStencilAttachment	Trait for objects that can be used as depth and stencil attachments.
ToStencilAttachment	Trait for objects that can be used as stencil attachments.

Functions

is_dimensions_mismatch_supported

Returns true if the backend supports attachments with varying dimensions.