# OpenGL configuration options

When configuring or selecting a Config, you do so based on the properties of that config. pyglet supports a fixed subset of the options provided by AGL, GLX, WGL and their extensions. In particular, these constraints are placed on all OpenGL configs:

- Buffers are always component (RGB or RGBA) color, never palette indexed.
- The "level" of a buffer is always 0 (this parameter is largely unsupported by modern OpenGL drivers anyway).
- There is no way to set the transparent color of a buffer (again, this GLX-specific option is not well supported).
- There is no support for pbuffers (equivalent functionality can be achieved much more simply and efficiently using framebuffer objects).

The visible portion of the buffer, sometimes called the color buffer, is configured with the following attributes:

> `buffer_size`

>   Number of bits per sample. Common values are 24 and 32, which each dedicate 8 bits per color component. A buffer size of 16 is also possible, which usually corresponds to 5, 6, and 5 bits of red, green and blue, respectively.

>   Usually there is no need to set this property, as the device driver will select a buffer size compatible with the current display mode by default.

> `red_size`, `blue_size`, `green_size`, `alpha_size`

>   These each give the number of bits dedicated to their respective color component. You should avoid setting any of the red, green or blue sizes, as these are determined by the driver based on the `buffer_size` property.

>   If you require an alpha channel in your color buffer (for example, if you are compositing in multiple passes) you should specify `alpha_size=8` to ensure that this channel is created.

> `sample_buffers` and `samples`

>   Configures the buffer for multisampling, in which more than one color sample is used to determine the color of each pixel, leading to a higher quality, antialiased image.

>   Enable multisampling by setting `sample_buffers=1`, then give the number of samples per pixel to use in `samples`. For example, `samples=2` is the fastest, lowest-quality multisample configuration. A higher-quality buffer (with a compromise in performance) is possible with `samples=4`.

>   Not all video hardware supports multisampling; you may need to make this a user-selectable option, or be prepared to automatically downgrade the configuration if the requested one is not available.

> `stereo`
>   Creates separate left and right buffers, for use with stereo hardware. Only specialised video hardware such as stereoscopic glasses will support this option. When used, you will need to manually render to each buffer, for example using glDrawBuffers.
> `double_buffer`

>   Create separate front and back buffers. Without double-buffering, drawing commands are immediately visible on the screen, and the user will notice a visible flicker as the image is redrawn in front of them.

>   It is recommended to set `double_buffer=True`, which creates a separate hidden buffer to which drawing is performed. When the Window.flip is called, the buffers are swapped, making the new drawing visible virtually instantaneously.

In addition to the color buffer, several other buffers can optionally be created based on the values of these properties:

> `depth_size`
>   A depth buffer is usually required for 3D rendering. The typical depth size is 24 bits. Specify `0` if you do not require a depth buffer.
> `stencil_size`
>   The stencil buffer is required for masking the other buffers and implementing certain volumetric shadowing algorithms. The typical stencil size is 8 bits; or specify `0` if you do not require it.
> `accum_red_size`, `accum_blue_size`, `accum_green_size`, `accum_alpha_size`

>   The accumulation buffer can be used for simple antialiasing, depth-of-field, motion blur and other compositing operations. Its use nowadays is being superceded by the use of floating-point textures, however it is still a practical solution for implementing these effects on older hardware.

>   If you require an accumulation buffer, specify `8` for each of these attributes (the alpha component is optional, of course).

> `aux_buffers`

>   Each auxilliary buffer is configured the same as the colour buffer. Up to four auxilliary buffers can typically be created. Specify `0` if you do not require any auxilliary buffers.

>   Like the accumulation buffer, auxilliary buffers are used less often nowadays as more efficient techniques such as render-to-texture are available. They are almost universally available on older hardware, though, where the newer techniques are not possible.

# The default configuration

If you create a Window without specifying the context or config, pyglet will use a template config with the following properties:

> Attribute | Value
> --- | ---
> double_buffer | True
> depth_size | 24