Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# Framebuffer

class Framebuffer

  Returned by `Context.framebuffer()`

  A `Framebuffer` is a collection of buffers that can be used as the destination for rendering.

  The buffers for Framebuffer objects reference images from either Textures or Renderbuffers.

## Methods

Framebuffer.clear(red: float = 0.0, green: float = 0.0, blue: float = 0.0, alpha: float = 0.0, depth: float = 1.0, viewport=..., color=...) → None

  Clear the framebuffer.

  If a viewport passed in, a scissor test will be used to clear the given viewport. This viewport take presence over the framebuffers `scissor`. Clearing can still be done with scissor if no viewport is passed in.

  This method also respects the `color_mask` and `depth_mask`. It can for example be used to only clear the depth or color buffer or specific components in the color buffer.

  If the viewport is a 2-tuple it will clear the `(0, 0, width, height)` where `(width, height)` is the 2-tuple.

  If the viewport is a 4-tuple it will clear the given viewport.

  Parameters:

    - red (float) – color component.

    - green (float) – color component.

    - blue (float) – color component.

    - alpha (float) – alpha component.

    - depth (float) – depth value.

    - viewport (tuple) – The viewport.

    - color (tuple) – Optional tuple replacing the red, green, blue and alpha arguments

Framebuffer.read(viewport=..., components: int = 3, attachment: int = 0, alignment: int = 1, dtype: str = 'f1', clamp: bool = False) → bytes

  Read the content of the framebuffer.

  Parameters:

    - viewport (tuple) – The viewport.

    - components (int) – The number of components to read.

    - attachment (int) – The color attachment number. -1 for the depth attachment

    - alignment (int) – The byte alignment of the pixels.

    - dtype (str) – Data type.

    - clamp (bool) – Clamps floating point values to `[0.0, 1.0]`

      # Read the first color attachment's RGBA data
      data = fbo.read(components=4)
      # Read the second color attachment's RGB data
      data = fbo.read(attachment=1)
      # Read the depth attachment
      data = fbo.read(attachment=-1)
      # Read the lower left 10 x 10 pixels from the first color attachment
      data = fbo.read(viewport=(0, 0, 10, 10))

Framebuffer.read_into(buffer, viewport, components: int = 3, attachment: int = 0, alignment: int = 1, dtype: str = 'f1', write_offset: int = 0) → None

  Read the content of the framebuffer into a buffer.

  Parameters:

    - buffer (bytearray) – The buffer that will receive the pixels.

    - viewport (tuple) – The viewport.

    - components (int) – The number of components to read.

    - attachment (int) – The color attachment.

    - alignment (int) – The byte alignment of the pixels.

    - dtype (str) – Data type.

    - write_offset (int) – The write offset.

Framebuffer.use()

  Bind the framebuffer.

Framebuffer.release()

## Attributes

Framebuffer.viewport: tuple

  Get or set the viewport of the framebuffer.

Framebuffer.scissor: tuple

  Get or set the scissor box of the framebuffer.

  When scissor testing is enabled fragments outside the defined scissor box will be discarded. This applies to rendered geometry or `Framebuffer.clear()`.

  Setting is value enables scissor testing in the framebuffer. Setting the scissor to `None` disables scissor testing and reverts the scissor box to match the framebuffer size.

  Example:

      # Enable scissor testing
      >>> ctx.scissor = 100, 100, 200, 100
      # Disable scissor testing
      >>> ctx.scissor = None

Framebuffer.color_mask: tuple

  The color mask of the framebuffer.

  Color masking controls what components in color attachments will be affected by fragment write operations. This includes rendering geometry and clearing the framebuffer.

  Default value: `(True, True, True, True)`.

  Examples:

      # Block writing to all color components (rgba) in color attachments
      fbo.color_mask = False, False, False, False

      # Re-enable writing to color attachments
      fbo.color_mask = True, True, True, True

      # Block fragment writes to alpha channel
      fbo.color_mask = True, True, True, False

Framebuffer.depth_mask: bool

  The depth mask of the framebuffer.

  Depth mask enables or disables write operations to the depth buffer. This also applies when clearing the framebuffer. If depth testing is enabled fragments will still be culled, but the depth buffer will not be updated with new values. This is a very useful tool in many rendering techniques.

  Default value: `True`

Framebuffer.width: int

  The width of the framebuffer.

  Framebuffers created by a window will only report its initial size. It’s better get size information from the window itself.

Framebuffer.height: int

  The height of the framebuffer.

  Framebuffers created by a window will only report its initial size. It’s better get size information from the window itself.

Framebuffer.size: Tuple[int, int]

  The size of the framebuffer.

  Framebuffers created by a window will only report its initial size. It’s better get size information from the window itself.

Framebuffer.samples: int

  The samples of the framebuffer.

Framebuffer.bits: int

  The bits of the framebuffer.

Framebuffer.color_attachments: tuple

Framebuffer.depth_attachment: tuple

Framebuffer.ctx: Context

  The context this object belongs to

Framebuffer.glo: int

  The internal OpenGL object. This values is provided for interoperability and debug purposes only.

Framebuffer.extra: Any

  User defined data.