picogl.gpu.buffers.glframe
==========================

.. py:module:: picogl.gpu.buffers.glframe

.. autoapi-nested-parse::

   This module provides classes and methods for managing OpenGL frame buffers
   with functionalities for binding, clearing, and managing attachments.

   The primary class, GLFramebuffer, allows creating and managing frame
   buffers with support for color and depth attachments.



Classes
-------

.. autoapisummary::

   picogl.gpu.buffers.glframe.GLFramebuffer


Module Contents
---------------

.. py:class:: GLFramebuffer

   Bases: :py:obj:`picogl.renderer.initializable.Initializable`


   gl Framebuffer


   .. py:attribute:: handle
      :value: None



   .. py:attribute:: color_attachments
      :type:  list[int]
      :value: []



   .. py:attribute:: depth_attachment
      :type:  int | None
      :value: None



   .. py:method:: initialize()

      Initializes the framebuffer object.

      Generates and assigns a new framebuffer handle if one does not already
      exist. This method is used to allocate OpenGL resources for rendering
      operations involving a framebuffer.

      :raises RuntimeError: If there is an issue generating a new framebuffer.



   .. py:method:: _do_initialize()

      Subclass must implement actual initialization.



   .. py:method:: bind()


   .. py:method:: _bind_frame_buffer_handle(handle)


   .. py:method:: unbind()

      Unbinds any currently bound framebuffer by binding to the default framebuffer.

      This static method ensures that the OpenGL state is reset to use the default
      framebuffer, useful for concluding framebuffer operations.

      :returns: None



   .. py:method:: bound()

      Context manager to handle the binding and unbinding of a GLFramebuffer.

      This context manager ensures that when a GLFramebuffer is bound, it is properly
      unbound after the block of code within the context completes, even if an
      exception is raised.

      :Yields: *GLFramebuffer* -- The GLFramebuffer instance being managed.



   .. py:method:: attach_color_texture(tex: picogl.texture.texture2d.Texture2D, index: int = 0)

      Attaches a color texture to the framebuffer at a specified index.

      This method binds a 2D texture to a color attachment point of the framebuffer.
      The `index` parameter specifies the color attachment index to which the texture
      will be attached. The method also keeps track of texture handles attached
      to the framebuffer's color attachments.

      :param tex: The 2D texture to attach to the framebuffer.
      :type tex: Texture2D
      :param index: The color attachment index. Defaults to 0.
      :type index: int

      :returns: None



   .. py:method:: attach_depth_texture(tex: picogl.texture.texture2d.Texture2D)

      Attaches a texture as the depth attachment to the framebuffer.

      This method binds the framebuffer and attaches the given 2D texture to the
      depth attachment point. It updates the depth attachment handle.

      :param tex: The texture to attach as the depth attachment.
      :type tex: Texture2D



   .. py:method:: check_complete()

      Checks the completeness of the currently bound framebuffer.

      This method verifies the status of the currently bound OpenGL framebuffer
      by using the `glCheckFramebufferStatus` function. If the framebuffer is
      not complete, it raises a `RuntimeError` with the corresponding status
      code.

      :raises RuntimeError: If the framebuffer is not complete, with the status code
      :raises indicating the specific issue.:



   .. py:method:: _attach_texture(attachment: float | int, tex: picogl.texture.texture2d.Texture2D)

      Binds a 2D texture to a specified framebuffer attachment point.

      This function is used to attach a 2D texture object to a specific attachment point
      of a framebuffer. The function acts as a wrapper around the OpenGL `glFramebufferTexture2D`
      to simplify the attachment process.

      :param attachment: float | int
                         The attachment point of the framebuffer to which the texture will
                         be bound. This is typically an OpenGL constant value, such as
                         `GL_COLOR_ATTACHMENT0`, `GL_DEPTH_ATTACHMENT`, or `GL_STENCIL_ATTACHMENT`.
      :param tex: Texture2D
                  The texture object to be attached to the framebuffer. The texture
                  must be an instance of `Texture2D` and already have an initialized
                  handle.

      :raises Any exception that might be triggered by the `glFramebufferTexture2D`:
      :raises function or improper argument usage.: