Graphics.Rendering.OpenGL.GL.Framebuffer

OpenGL-2.13.1.0: A binding for the OpenGL graphics system

Copyright | (c) Sven Panne 2002-2015
License | BSD3
Maintainer | Sven Panne <svenpanne@gmail.com>
Stability | stable
Portability | portable
Safe Haskell | None
Language | Haskell2010

Graphics.Rendering.OpenGL.GL.Framebuffer

Contents

- Selecting a Buffer for Writing
- Fine Control of Buffer Updates
- Clearing the Buffers
- Invalidating Framebuffer Contents
- The Accumulation Buffer
- Querying the Buffer Configuration

Description

This module corresponds to section 17.4 (Whole Framebuffer Operations) of the OpenGL 4.5 specs.

Synopsis

- data BufferMode
  - = NoBuffers
  - | FrontLeftBuffer
  - | FrontRightBuffer
  - | BackLeftBuffer
  - | BackRightBuffer
  - | FrontBuffers
  - | BackBuffers
  - | LeftBuffers
  - | RightBuffers
  - | FrontAndBackBuffers
  - | AuxBuffer GLsizei
  - | FBOColorAttachment GLsizei
- drawBuffer :: StateVar BufferMode
- namedFramebufferDrawBuffer :: FramebufferObject -> SettableStateVar BufferMode
- drawBuffers :: StateVar [BufferMode]
- namedFramebufferDrawBuffers :: FramebufferObject -> SettableStateVar [BufferMode]
- type DrawBufferIndex = GLuint
- drawBufferi :: DrawBufferIndex -> GettableStateVar BufferMode
- maxDrawBuffers :: GettableStateVar GLsizei
- indexMask :: StateVar GLuint
- colorMask :: StateVar (Color4 Capability)
- colorMaski :: DrawBufferIndex -> StateVar (Color4 Capability)
- depthMask :: StateVar Capability
- stencilMask :: StateVar GLuint
- stencilMaskSeparate :: Face -> StateVar GLuint
- data ClearBuffer
  - = ColorBuffer
  - | AccumBuffer
  - | StencilBuffer
  - | DepthBuffer
- clear :: [ClearBuffer] -> IO ()
- clearColor :: StateVar (Color4 GLfloat)
- clearIndex :: StateVar (Index1 GLfloat)
- clearDepth :: StateVar GLdouble
- clearDepthf :: StateVar GLfloat
- clearStencil :: StateVar GLint
- clearAccum :: StateVar (Color4 GLfloat)
- data ClearBufferCommand
  - = ClearColorBufferInt DrawBufferIndex (Color4 GLint)
  - | ClearColorBufferFloat DrawBufferIndex (Color4 GLfloat)
  - | ClearColorBufferUint DrawBufferIndex (Color4 GLuint)
  - | ClearDepthBuffer GLfloat
  - | ClearStencilBuffer GLint
  - | ClearDepthAndStencilBuffers GLfloat GLint
- clearBuffer :: ClearBufferCommand -> IO ()
- clearNamedFramebuffer :: FramebufferObject -> ClearBufferCommand -> IO ()
- invalidateSubFramebuffer :: FramebufferTarget -> [FramebufferObjectAttachment] -> (Position, Size) -> IO ()
- invalidateNamedFramebufferSubData :: FramebufferObject -> [FramebufferObjectAttachment] -> (Position, Size) -> IO ()
- invalidateFramebuffer :: FramebufferTarget -> [FramebufferObjectAttachment] -> IO ()
- invalidateNamedFramebufferData :: FramebufferObject -> [FramebufferObjectAttachment] -> IO ()
- data AccumOp
  - = Accum
  - | Load
  - | Return
  - | Mult
  - | Add
- accum :: AccumOp -> GLfloat -> IO ()
- auxBuffers :: GettableStateVar GLsizei
- doubleBuffer :: GettableStateVar Bool
- stereoBuffer :: GettableStateVar Bool
- rgbaBits :: GettableStateVar (Color4 GLsizei)
- stencilBits :: GettableStateVar GLsizei
- depthBits :: GettableStateVar GLsizei
- accumBits :: GettableStateVar (Color4 GLsizei)
- rgbaSignedComponents :: GettableStateVar (Color4 Bool)

# Selecting a Buffer for Writing

data BufferMode

The set of color buffers which are selected for reading and writing. Note that `FBOColorAttachment` can only be used with framebuffer objects, while the rest can only be used with the default framebuffer. Furthermore, OpenGL 3.0 deprecated auxiliary buffers, so avoid `AuxBuffer` in modern code.

Constructors

NoBuffers | No color buffers are selected.
FrontLeftBuffer | Only the front left color buffer is selected.
FrontRightBuffer | Only the front right color buffer is selected.
BackLeftBuffer | Only the back left color buffer is selected.
BackRightBuffer | Only the back right color buffer is selected.
FrontBuffers | Only the front left and front right color buffers are selected. If there is no front right color buffer, only the front left color buffer is selected.
BackBuffers | Only the back left and back right color buffers are selected. If there is no back right color buffer, only the back left color buffer is selected.
LeftBuffers | Only the front left and back left color buffers are selected. If there is no back left color buffer, only the front left color buffer is selected.
RightBuffers | Only the front right and back right color buffers are selected. If there is no back right color buffer, only the front right color buffer is selected.
FrontAndBackBuffers | All the front and back color buffers (front left, front right, back left, back right) are selected. If there are no back color buffers, only the front left and front right color buffers are selected. If there are no right color buffers, only the front left and back left color buffers are selected. If there are no right or back color buffers, only the front left color buffer is selected.
AuxBuffer GLsizei | Only the given auxiliary color buffer no. i is selected.
FBOColorAttachment GLsizei | Only the given color attachment of the bound framebufferobject is selected for reading or writing.

Instances

Eq BufferMode |
Ord BufferMode |
Show BufferMode |
FramebufferAttachment BufferMode |

drawBuffer :: StateVar BufferMode

When colors are written to the framebuffer, they are written into the color buffers specified by `drawBuffer`.

If more than one color buffer is selected for drawing, then blending or logical operations are computed and applied independently for each color buffer and can produce different results in each buffer.

Monoscopic contexts include only left buffers, and stereoscopic contexts include both left and right buffers. Likewise, single-buffered contexts include only front buffers, and double-buffered contexts include both front and back buffers. The context is selected at GL initialization.

The initial value is `FrontBuffers` for single-buffered contexts, and `BackBuffers` for double-buffered contexts.

namedFramebufferDrawBuffer :: FramebufferObject -> SettableStateVar BufferMode

The direct-state-access version of `drawBuffer`.

drawBuffers :: StateVar [BufferMode]

`drawBuffers` defines the draw buffers to which all fragment colors are written. The draw buffers being defined correspond in order to the respective fragment colors. The draw buffer for fragment colors beyond those specified is set to `NoBuffers`.

Except for `NoBuffers`, a buffer may not appear more then once in the given list. Specifying a buffer more then once will result in an `InvalidOperation`.

If fixed-function fragment shading is being performed, `drawBuffers` specifies a set of draw buffers into which the fragment color is written.

If a fragment shader writes to `gl_FragColor`, `drawBuffers` specifies a set of draw buffers into which the single fragment color defined by `gl_FragColor` is written. If a fragment shader writes to `gl_FragData`, `drawBuffers` specifies a set of draw buffers into which each of the multiple fragment colors defined by `gl_FragData` are separately written. If a fragment shader writes to neither `gl_FragColor` nor `gl_FragData`, the values of the fragment colors following shader execution are undefined, and may differ for each fragment color.

namedFramebufferDrawBuffers :: FramebufferObject -> SettableStateVar [BufferMode]

The direct-state-access version of `drawBuffers`.

type DrawBufferIndex = GLuint

The index of the draw buffer.

drawBufferi :: DrawBufferIndex -> GettableStateVar BufferMode

`drawBufferi` is a fast query function. For indices in the range 0..`maxDrawBuffers`-1 its results is the same as selecting the corresponding element from the list returned by `drawBuffers`, but this function uses only one GL function call instead of `maxDrawBuffers` ones.

maxDrawBuffers :: GettableStateVar GLsizei

Contains the maximum number of buffers that can activated via `drawBuffers` or which can be simultaneously written into from within a fragment shader using the special output variable array `gl_FragData`. This constant effectively defines the size of the `gl_FragData` array. The minimum legal value is 1.

# Fine Control of Buffer Updates

indexMask :: StateVar GLuint

Controls the writing of individual bits in the color index buffers. The least significant n bits of its value, where n is the number of bits in a color index buffer, specify a mask. Where a 1 appears in the mask, it is possible to write to the corresponding bit in the color index buffer (or buffers). Where a 0 appears, the corresponding bit is write-protected.

This mask is used only in color index mode, and it affects only the buffers currently selected for writing (see `drawBuffer`). Initially, all bits are enabled for writing.

colorMask :: StateVar (Color4 Capability)

Controls whether the individual color components in the framebuffer can or cannot be written. If the red flag is `Disabled`, for example, no change is made to the red component of any pixel in any of the color buffers, regardless of the drawing operation attempted. Initially, all color components can be written.

Changes to individual bits of components cannot be controlled. Rather, changes are either enabled or disabled for entire color components. Furthermore, this mask is used only in RGBA mode.

colorMaski :: DrawBufferIndex -> StateVar (Color4 Capability)

`colorMaski` is a version of `colorMask` that only applies to the specified draw buffer.

depthMask :: StateVar Capability

Controls whether the depth buffer is enabled for writing. The initial state is `Enabled`.

stencilMask :: StateVar GLuint

Controls the writing of individual bits in the stencil planes. The least significant n bits of its value, where n is the number of bits in the stencil buffer, specify a mask. Where a 1 appears in the mask, it is possible to write to the corresponding bit in the stencil buffer. Where a 0 appears, the corresponding bit is write-protected. Initially, all bits are enabled for writing.

stencilMaskSeparate :: Face -> StateVar GLuint

A per-face version of `stencilMask`.

# Clearing the Buffers

data ClearBuffer

The buffers which can be cleared with `clear`.

Constructors

ColorBuffer | The buffers currently enabled for color writing.
AccumBuffer | The accumulation buffer.
StencilBuffer | The stencil buffer.
DepthBuffer | The depth buffer.

Instances

Eq ClearBuffer |
Ord ClearBuffer |
Show ClearBuffer |

clear :: [ClearBuffer] -> IO ()

Set the bitplane area of the window to values previously selected by `clearColor`, `clearIndex`, `clearDepth`, `clearStencil`, and `clearAccum`. Multiple color buffers can be cleared simultaneously by selecting more than one buffer at a time using `drawBuffer`.

The pixel ownership test, the scissor test, dithering, and the buffer writemasks affect the operation of `clear`. The scissor box bounds the cleared region. Alpha function, blend function, logical operation, stenciling, texure mapping, and depth-buffering are ignored by `clear`.

`clear` takes a list of buffers, indicating which buffers are to be cleared. If a buffer is not present, then a `clear` directed at that buffer has no effect.

The value to which each buffer is cleared depends on the setting of the clear value for that buffer.

clearColor :: StateVar (Color4 GLfloat)

Controls the red, green, blue, and alpha values used by `clear` to clear the color buffers. Initially, all values are 0.

clearIndex :: StateVar (Index1 GLfloat)

Controls the index c used by `clear` to clear the color index buffers. c is not clamped. Rather, c is converted to a fixed-point value with unspecified precision to the right of the binary point. The integer part of this value is then masked with 2^m-1, where m is the number of bits in a color index stored in the framebuffer. Initially, the value is 0.

clearDepth :: StateVar GLdouble

Controls the depth value used by `clear` to clear the depth buffer. The initial value is 1.

clearDepthf :: StateVar GLfloat

A variant of `clearDepth` with a `GLfloat` argument.

clearStencil :: StateVar GLint

Controls the value s used by `clear` to clear the stencil buffer. s is masked with 2^m-1, where m is the number of bits in the stencil buffer. Initially, the value is 0.

clearAccum :: StateVar (Color4 GLfloat)

Controls the red, green, blue, and alpha values used by `clear` to clear the accumulation buffer. Values written into `clearAccum` are clamped to the range [-1, 1]. The initial values are all 0.

data ClearBufferCommand

Describes which buffer(s) to clear and the value to use.

Constructors

ClearColorBufferInt DrawBufferIndex (Color4 GLint) | Clear the signed integer color buffer(s) at the given index.
ClearColorBufferFloat DrawBufferIndex (Color4 GLfloat) | Clear the fixed- or floating-point color buffer(s) at the given index.
ClearColorBufferUint DrawBufferIndex (Color4 GLuint) | Clear the unsigned color buffer(s) at the given index.
ClearDepthBuffer GLfloat | Clear the depth buffer.
ClearStencilBuffer GLint | Clear the stencil buffer.
ClearDepthAndStencilBuffers GLfloat GLint | Clear the depth buffer and the stencil buffer.

Instances

Eq ClearBufferCommand |
Ord ClearBufferCommand |
Show ClearBufferCommand |

clearBuffer :: ClearBufferCommand -> IO ()

Clear the given buffer(s).

clearNamedFramebuffer :: FramebufferObject -> ClearBufferCommand -> IO ()

The direct-state-access version of `clearBuffer`.

# Invalidating Framebuffer Contents

invalidateSubFramebuffer :: FramebufferTarget -> [FramebufferObjectAttachment] -> (Position, Size) -> IO ()

Invalidate a region of the attachments bound to the given target.

invalidateNamedFramebufferSubData :: FramebufferObject -> [FramebufferObjectAttachment] -> (Position, Size) -> IO ()

The direct-state-access version of `invalidateSubFramebuffer`.

invalidateFramebuffer :: FramebufferTarget -> [FramebufferObjectAttachment] -> IO ()

A version of `invalidateSubFramebuffer` affecting the whole viewport.

invalidateNamedFramebufferData :: FramebufferObject -> [FramebufferObjectAttachment] -> IO ()

The direct-state-access version of `invalidateFramebuffer`.

# The Accumulation Buffer

data AccumOp

An operation on the accumulation buffer.

Constructors

Accum | Obtains R, G, B, and A values from the buffer currently selected for reading (see `readBuffer`). Each component value is divided by 2^n-1, where n is the number of bits allocated to each color component in the currently selected buffer. The result is a floating-point value in the range [0, 1], which is multiplied by the value given to `accum` and added to the corresponding pixel component in the accumulation buffer, thereby updating the accumulation buffer.
Load | Similar to `Accum`, except that the current value in the accumulation buffer is not used in the calculation of the new value. That is, the R, G, B, and A values from the currently selected buffer are divided by 2^n-1, multiplied by the value given to `accum`, and then stored in the corresponding accumulation buffer cell, overwriting the current value.
Return | Transfers accumulation buffer values to the color buffer or buffers currently selected for writing. Each R, G, B, and A component is multiplied by the value given to `accum`, then multiplied by 2^n-1, clamped to the range [0, 2^n-1], and stored in the corresponding display buffer cell. The only fragment operations that are applied to this transfer are pixel ownership, scissor, dithering, and color writemasks.
Mult | Multiplies each R, G, B, and A in the accumulation buffer by the value given to `accum` and returns the scaled component to its corresponding accumulation buffer location.
Add | Adds the value given to `accum` to each R, G, B, and A in the accumulation buffer.

Instances

Eq AccumOp |
Ord AccumOp |
Show AccumOp |

accum :: AccumOp -> GLfloat -> IO ()

The accumulation buffer is an extended-range color buffer. Images are not rendered into it. Rather, images rendered into one of the color buffers are added to the contents of the accumulation buffer after rendering. Effects such as antialiasing (of points, lines, and polygons), motion blur, and depth of field can be created by accumulating images generated with different transformation matrices.

Each pixel in the accumulation buffer consists of red, green, blue, and alpha values. The number of bits per component in the accumulation buffer depends on the implementation (see `accumBits`). Regardless of the number of bits per component, the range of values stored by each component is [-1, 1]. The accumulation buffer pixels are mapped one-to-one with frame buffer pixels.

`accum` operates on the accumulation buffer. The first argument selects an accumulation buffer operation. The second argument, is a floating-point value to be used in that operation, see `AccumOp`.

All accumulation buffer operations are limited to the area of the current scissor box and applied identically to the red, green, blue, and alpha components of each pixel. If an `accum` operation results in a value outside the range [-1, 1], the contents of an accumulation buffer pixel component are undefined.

To clear the accumulation buffer, use `clearAccum` to specify the clear value, then call `clear` with the accumulation buffer enabled.

# Querying the Buffer Configuration

auxBuffers :: GettableStateVar GLsizei

The implementation and context dependent number of auxiliary buffers.

doubleBuffer :: GettableStateVar Bool

`True` if front and back buffers exist.

stereoBuffer :: GettableStateVar Bool

`True` if left and right buffers exist.

rgbaBits :: GettableStateVar (Color4 GLsizei)

stencilBits :: GettableStateVar GLsizei

depthBits :: GettableStateVar GLsizei

accumBits :: GettableStateVar (Color4 GLsizei)

rgbaSignedComponents :: GettableStateVar (Color4 Bool)