Buffer images

pyglet provides a basic representation of the framebuffer as components of the AbstractImage hierarchy. At this stage this representation is based off OpenGL 1.1, and there is no support for newer features such as framebuffer objects. Of course, this doesn't prevent you using framebuffer objects in your programs -- pyglet.gl provides this functionality -- just that they are not represented as AbstractImage types.

A framebuffer consists of

• One or more colour buffers, represented by ColorBufferImage
• An optional depth buffer, represented by DepthBufferImage
• An optional stencil buffer, with each bit represented by BufferImageMask
• Any number of auxilliary buffers, also represented by ColorBufferImage

You cannot create the buffer images directly; instead you must obtain instances via the BufferManager. Use get_buffer_manager to get this singleton:

buffers = image.get_buffer_manager()

Only the back-left color buffer can be obtained (i.e., the front buffer is inaccessible, and stereo contexts are not supported by the buffer manager):

color_buffer = buffers.get_color_buffer()

This buffer can be treated like any other image. For example, you could copy it to a texture, obtain its pixel data, save it to a file, and so on. Using the texture attribute is particularly useful, as it allows you to perform multipass rendering effects without needing a render-to-texture extension.

The depth buffer can be obtained similarly:

depth_buffer = buffers.get_depth_buffer()

When a depth buffer is converted to a texture, the class used will be a DepthTexture, suitable for use with shadow map techniques.

The auxilliary buffers and stencil bits are obtained by requesting one, which will then be marked as "in-use". This permits multiple libraries and your application to work together without clashes in stencil bits or auxilliary buffer names. For example, to obtain a free stencil bit:

mask = buffers.get_buffer_mask()

The buffer manager maintains a weak reference to the buffer mask, so that when you release all references to it, it will be returned to the pool of available masks.

Similarly, a free auxilliary buffer is obtained:

aux_buffer = buffers.get_aux_buffer()

When using the stencil or auxilliary buffers, make sure you explicitly request these when creating the window. See OpenGL configuration options for details.