GL module docs and docstrings (#2300)

* Initial work + doc revamp

* enums

* framebuffer

* geometry

* glsl

* framebuffer and program docstrings

* vertex_array

* add utils to docs

* uniform

* types

* texture

* query

* Lingering issues

* Various docstring improvements.

* Fix Buffer.orphan

Author: einarf

arcade/gl/__init__.py

@@ -1,13 +1,13 @@
 """
-A wrapper over OpenGL 3.3 core making OpenGL more reasonable to work with and easier to learn.
-The API is based on `ModernGL <https://github.com/moderngl/moderngl>`_ implementing
-a subset of the features.
-We use pyglet's OpenGL bindings based on ctypes.
+A wrapper over OpenGL 3.3 core making OpenGL more reasonable to work with and easier
+to learn. The API is based on `ModernGL <https://github.com/moderngl/moderngl>`_
+implementing a subset of the features. We use pyglet's OpenGL bindings based on ctypes.
 
 Creating OpenGL resources such as buffers, framebuffers, programs (shaders) and textures
 should be done through methods in a context.
 
-* Arcade users should access :py:attr:`arcade.Window.ctx` exposing an :py:class:`arcade.ArcadeContext`
+* Arcade users should access :py:attr:`arcade.Window.ctx` exposing an
+  :py:class:`arcade.ArcadeContext`
 * Pyglet users can instantiate an :py:class:`arcade.gl.Context` for the window or
   extend this class with more features if needed.
 
@@ -17,12 +17,11 @@
 
 from __future__ import annotations
 
-# flake8: noqa
 from .context import Context
 from .types import BufferDescription
 from .compute_shader import ComputeShader
 from .exceptions import ShaderException
-from .enums import *
+from .enums import *  # noqa
 from .buffer import Buffer
 from .vertex_array import Geometry, VertexArray
 from .texture import Texture2D

arcade/gl/buffer.py

@@ -10,7 +10,7 @@
 
 from .utils import data_to_ctypes
 
-if TYPE_CHECKING:  # handle import cycle caused by type hinting
+if TYPE_CHECKING:
     from arcade.gl import Context
 
 
@@ -30,12 +30,16 @@ class Buffer:
 
     .. warning:: Buffer objects should be created using :py:meth:`arcade.gl.Context.buffer`
 
-    :param ctx: The context this buffer belongs to
-    :param data: The data this buffer should contain.
-                                It can be a ``bytes`` instance or any
-                                object supporting the buffer protocol.
-    :param reserve: Create a buffer of a specific byte size
-    :param usage: A hit of this buffer is ``static`` or ``dynamic`` (can mostly be ignored)
+    Args:
+        ctx:
+            The context this buffer belongs to
+        data:
+            The data this buffer should contain. It can be a ``bytes`` instance or any
+            object supporting the buffer protocol.
+        reserve:
+            Create a buffer of a specific byte size
+        usage:
+            A hit of this buffer is ``static`` or ``dynamic`` (can mostly be ignored)
     """
 
     __slots__ = "_ctx", "_glo", "_size", "_usage", "__weakref__"
@@ -47,7 +51,7 @@ class Buffer:
 
     def __init__(
         self,
-        ctx: "Context",
+        ctx: Context,
         data: BufferProtocol | None = None,
         reserve: int = 0,
         usage: str = "static",
@@ -93,38 +97,40 @@ def __del__(self):
 
     @property
     def size(self) -> int:
-        """
-        The byte size of the buffer.
-        """
+        """The byte size of the buffer."""
         return self._size
 
     @property
     def ctx(self) -> "Context":
-        """
-        The context this resource belongs to.
-        """
+        """The context this resource belongs to."""
         return self._ctx
 
     @property
     def glo(self) -> gl.GLuint:
-        """
-        The OpenGL resource id
-        """
+        """The OpenGL resource id."""
         return self._glo
 
-    def delete(self):
+    def delete(self) -> None:
         """
         Destroy the underlying OpenGL resource.
-        Don't use this unless you know exactly what you are doing.
+
+        .. warning:: Don't use this unless you know exactly what you are doing.
         """
         Buffer.delete_glo(self._ctx, self._glo)
         self._glo.value = 0
 
     @staticmethod
-    def delete_glo(ctx: "Context", glo: gl.GLuint):
+    def delete_glo(ctx: Context, glo: gl.GLuint):
         """
         Release/delete open gl buffer.
+
         This is automatically called when the object is garbage collected.
+
+        Args:
+            ctx:
+                The context the buffer belongs to
+            glo:
+                The OpenGL buffer id
         """
         # If we have no context, then we are shutting down, so skip this
         if gl.current_context is None:
@@ -139,8 +145,11 @@ def delete_glo(ctx: "Context", glo: gl.GLuint):
     def read(self, size: int = -1, offset: int = 0) -> bytes:
         """Read data from the buffer.
 
-        :param size: The bytes to read. -1 means the entire buffer (default)
-        :param offset: Byte read offset
+        Args:
+            size:
+                The bytes to read. -1 means the entire buffer (default)
+            offset:
+                Byte read offset
         """
         if size == -1:
             size = self._size - offset
@@ -183,9 +192,12 @@ def write(self, data: BufferProtocol, offset: int = 0):
         truncated to fit. If the supplied data is smaller than the
         buffer, the remaining bytes will be left unchanged.
 
-        :param data: The byte data to write. This can be bytes or any object
-            supporting the buffer protocol.
-        :param offset: The byte offset
+        Args:
+            data:
+                The byte data to write. This can be bytes or any object
+                supporting the buffer protocol.
+            offset:
+                The byte offset
         """
         gl.glBindBuffer(gl.GL_ARRAY_BUFFER, self._glo)
         size, data = data_to_ctypes(data)
@@ -195,13 +207,18 @@ def write(self, data: BufferProtocol, offset: int = 0):
             raise ValueError("Attempting to write negative number bytes to buffer")
         gl.glBufferSubData(gl.GL_ARRAY_BUFFER, gl.GLintptr(offset), size, data)
 
-    def copy_from_buffer(self, source: "Buffer", size=-1, offset=0, source_offset=0):
-        """Copy data into this buffer from another buffer
-
-        :param source: The buffer to copy from
-        :param size: The amount of bytes to copy
-        :param offset: The byte offset to write the data in this buffer
-        :param source_offset: The byte offset to read from the source buffer
+    def copy_from_buffer(self, source: Buffer, size=-1, offset=0, source_offset=0):
+        """Copy data into this buffer from another buffer.
+
+        Args:
+            source:
+                The buffer to copy from
+            size:
+                The amount of bytes to copy
+            offset:
+                The byte offset to write the data in this buffer
+            source_offset:
+                The byte offset to read from the source buffer
         """
         # Read the entire source buffer into this buffer
         if size == -1:
@@ -232,13 +249,17 @@ def orphan(self, size: int = -1, double: bool = False):
         If the current buffer is busy in rendering operations
         it will be deallocated by OpenGL when completed.
 
-        :param size: New size of buffer. -1 will retain the current size.
-        :param double: Is passed in with `True` the buffer size will be doubled
+        Args:
+            size: (optional)
+                New size of buffer. -1 will retain the current size.
+                Takes precedence over ``double`` parameter if specified.
+            double (optional):
+                Is passed in with `True` the buffer size will be doubled
+                from its current size.
         """
-        if size > -1:
+        if size > 0:
             self._size = size
-
-        if double:
+        elif double is True:
             self._size *= 2
 
         gl.glBindBuffer(gl.GL_ARRAY_BUFFER, self._glo)
@@ -248,9 +269,13 @@ def bind_to_uniform_block(self, binding: int = 0, offset: int = 0, size: int = -
         """Bind this buffer to a uniform block location.
         In most cases it will be sufficient to only provide a binding location.
 
-        :param binding: The binding location
-        :param offset: byte offset
-        :param size: size of the buffer to bind.
+        Args:
+            binding:
+                The binding location
+            offset:
+                Byte offset
+            size:
+                Size of the buffer to bind.
         """
         if size < 0:
             size = self.size
@@ -261,9 +286,13 @@ def bind_to_storage_buffer(self, *, binding=0, offset=0, size=-1):
         """
         Bind this buffer as a shader storage buffer.
 
-        :param binding: The binding location
-        :param offset: Byte offset in the buffer
-        :param size: The size in bytes. The entire buffer will be mapped by default.
+        Args:
+            binding:
+                The binding location
+            offset:
+                Byte offset in the buffer
+            size:
+                The size in bytes. The entire buffer will be mapped by default.
         """
         if size < 0:
             size = self.size

arcade/gl/compute_shader.py

@@ -25,9 +25,15 @@
 class ComputeShader:
     """
     A higher level wrapper for an OpenGL compute shader.
+
+    Args:
+        ctx:
+            The context this shader belongs to.
+        glsl_source:
+            The GLSL source code for the compute shader.
     """
 
-    def __init__(self, ctx: "Context", glsl_source: str) -> None:
+    def __init__(self, ctx: Context, glsl_source: str) -> None:
         self._ctx = ctx
         self._source = glsl_source
         self._uniforms: dict[str, UniformBlock | Uniform] = dict()
@@ -95,7 +101,7 @@ def glo(self) -> int:
         """The name/id of the OpenGL resource"""
         return self._glo
 
-    def use(self):
+    def _use(self) -> None:
         """
         Use/activate the compute shader.
 
@@ -105,7 +111,7 @@ def use(self):
             since ``run()`` already does this for you.
         """
         gl.glUseProgram(self._glo)
-        # self._ctx.active_program = self
+        self._ctx.active_program = self
 
     def run(self, group_x=1, group_y=1, group_z=1) -> None:
         """
@@ -128,11 +134,12 @@ def run(self, group_x=1, group_y=1, group_z=1) -> None:
         a size for a dimension or uses ``1`` as size you don't have to supply
         this parameter.
 
-        :param group_x: The number of work groups to be launched in the X dimension.
-        :param group_y: The number of work groups to be launched in the y dimension.
-        :param group_z: The number of work groups to be launched in the z dimension.
+        Args:
+            group_x: The number of work groups to be launched in the X dimension.
+            group_y: The number of work groups to be launched in the y dimension.
+            group_z: The number of work groups to be launched in the z dimension.
         """
-        self.use()
+        self._use()
         gl.glDispatchCompute(group_x, group_y, group_z)
 
     def __getitem__(self, item) -> Uniform | UniformBlock:
@@ -164,18 +171,25 @@ def __del__(self):
         if self._ctx.gc_mode == "context_gc" and self._glo > 0:
             self._ctx.objects.append(self)
 
-    def delete(self):
+    def delete(self) -> None:
         """
         Destroy the internal compute shader object.
+
         This is normally not necessary, but depends on the
-        garbage collection more configured in the context.
+        garbage collection configured in the context.
         """
         ComputeShader.delete_glo(self._ctx, self._glo)
         self._glo = 0
 
     @staticmethod
     def delete_glo(ctx, prog_id):
-        """Low level method for destroying a compute shader by id"""
+        """
+        Low level method for destroying a compute shader by id.
+
+        Args:
+            ctx: The context this program belongs to.
+            prog_id: The OpenGL id of the program.
+        """
         # Check to see if the context was already cleaned up from program
         # shut down. If so, we don't need to delete the shaders.
         if gl.current_context is None: