picogl.buffers.upload
=====================

.. py:module:: picogl.buffers.upload

.. autoapi-nested-parse::

   OpenGL Geometry Buffer Upload
   =============================

   This module provides utilities for uploading vertex and element data to OpenGL buffers,
   including VAOs (Vertex Array Objects), VBOs (Vertex Buffer Objects), and optionally EBOs
   (Element Buffer Objects). It supports interleaved vertex attributes and automatic binding
   of attribute pointers.

   Functions:
   ----------

   .. autofunction:: upload_geometry_buffers
       General-purpose function to upload vertex and optional index data to OpenGL buffers.
       Automatically binds attribute pointers and stores buffer handles in a user-defined object.

   .. autofunction:: upload_vertex_buffer
       Uploads a simple vertex buffer and computes proximity-based index pairs for rendering.

   Parameters:
   -----------
   - `vao_target`: Name of the VAO attribute in the target object.
   - `vbo_target`: Name of the VBO attribute in the target object.
   - `render_buffers`: Object or dataclass holding OpenGL buffer handles.
   - `vertex_data`: Interleaved vertex attributes (e.g., positions, normals).
   - `attributes`: List of tuples (location, size, offset) for attribute pointers.
   - `element_data`: Optional index data for indexed rendering.
   - `ebo_target`: Name of the EBO attribute in the target object.
   - `usage`: Buffer usage hint (e.g., GL_STATIC_DRAW).

   Usage Example:
   --------------

   .. code-block:: python

       upload_geometry_buffers(
           vao_target="mesh_vao",
           vbo_target="mesh_vbo",
           render_buffers=my_buffers,
           vertex_data=vertices,
           attributes=[(0, 3, 0), (1, 3, 12)],
           element_data=indices,
           ebo_target="mesh_ebo"
       )



Functions
---------

.. autoapisummary::

   picogl.buffers.upload.upload_geometry_buffers
   picogl.buffers.upload.upload_vertex_buffer


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

.. py:function:: upload_geometry_buffers(vao_target: str, vbo_target: str, render_buffers: object, vertex_data: numpy.ndarray, attributes: list[tuple[int, int, int]], *, element_data: numpy.ndarray = None, ebo_target: str = None, usage: int = GL_STATIC_DRAW) -> None

   upload_geometry_buffers

   :param vao_target: Name of the VAO attribute in render_buffers (e.g. "calpha_vao")
   :param vbo_target: Name of the VBO attribute in render_buffers (e.g. "calpha_buffer_group")
   :param render_buffers: Any object or dataclass holding OpenGL buffer handles
   :param vertex_data: Interleaved vertex attributes (e.g. position_array + normal)
   :param attributes: List of tuples (location, size, offset) for glVertexAttribPointer
   :param element_data: Optional index data (e.g. for GL_TRIANGLES)
   :param ebo_target: Name of the EBO attribute in render_buffers
   :param usage: GL_STATIC_DRAW or GL_DYNAMIC_DRAW

   General-purpose VAO/VBO upload function for vertex geometry.


.. py:function:: upload_vertex_buffer(vao: int, vbo: int, points: numpy.ndarray)

   upload_vertex_buffer

   :param vao: int
   :param vbo: int
   :param points: np.ndarray
   :return: list indices