gl46 0.1.0__py3-none-any.whl

gl46/__init__.py

@@ -0,0 +1,99 @@
+"""OpenGL 4.6 Direct State Access utility library (gl46)."""
+
+from gl46.barrier import Barrier, MemoryBarrier
+from gl46.base import GLObject
+from gl46.buffer import EBO, IBO, Buffer, IndirectDrawBuffer, ShaderStorage
+from gl46.camera import Camera
+from gl46.debug import DebugOutput
+from gl46.errors import (
+    GL46Error,
+    GLCompilationError,
+    GLFileNotFoundError,
+    GLLinkError,
+    GLObjectDeletedError,
+    GLVersionError,
+)
+from gl46.framebuffer import Framebuffer
+from gl46.gl import GL, PyOpenGLGL, configure, get_gl
+from gl46.material import Material
+from gl46.pipeline import ProgramPipeline
+from gl46.program import Program
+from gl46.query import Query
+from gl46.renderbuffer import Renderbuffer, RenderbufferMultisample
+from gl46.sampler import Sampler
+from gl46.shader import Shader, ShaderStage
+from gl46.texture import (
+    Texture2D,
+    Texture2DArray,
+    TextureBuffer,
+    TextureCubeMapArray,
+    TextureMultisample,
+)
+from gl46.transformfeedback import TransformFeedback
+from gl46.version import parse_version, require_core, require_dsa
+from gl46.vertexarray import VertexArray, VertexAttrib
+from gl46.window import Window
+
+GLenum = GLuint = GLint = int
+
+__all__ = [
+    "EBO",
+    "GL",
+    "IBO",
+    "Barrier",
+    "Buffer",
+    "Camera",
+    "DebugOutput",
+    "Framebuffer",
+    "GL46Error",
+    "GLCompilationError",
+    "GLFileNotFoundError",
+    "GLLinkError",
+    "GLObject",
+    "GLObjectDeletedError",
+    "GLVersionError",
+    "GLenum",
+    "GLint",
+    "GLuint",
+    "IndirectDrawBuffer",
+    "Material",
+    "MemoryBarrier",
+    "Program",
+    "ProgramPipeline",
+    "PyOpenGLGL",
+    "Query",
+    "Renderbuffer",
+    "RenderbufferMultisample",
+    "Sampler",
+    "Shader",
+    "ShaderStage",
+    "ShaderStorage",
+    "Texture2D",
+    "Texture2DArray",
+    "TextureBuffer",
+    "TextureCubeMapArray",
+    "TextureMultisample",
+    "TransformFeedback",
+    "VertexArray",
+    "VertexAttrib",
+    "Window",
+    "configure",
+    "get_gl",
+    "parse_version",
+    "require_core",
+    "require_dsa",
+]
+
+try:
+    from gl46.window_imgui import build_imgui_params, run_imgui_app
+except ImportError:  # imgui-bundle missing or partially broken
+    pass
+else:
+    __all__ += ["build_imgui_params", "run_imgui_app"]
+
+try:
+    from gl46.window_qt import GL46Widget, make_qt_format, run_qt_app
+except ImportError:  # PySide6 not installed
+    pass
+else:
+    __all__ += ["GL46Widget", "make_qt_format", "run_qt_app"]

gl46/barrier.py

@@ -0,0 +1,82 @@
+"""High-level GPU memory barrier helpers around :func:`glMemoryBarrier`.
+
+Compute shader writes to storage buffers, images and atomic counters are
+not ordered against later reads unless an explicit barrier is posted.
+"""
+
+from __future__ import annotations
+
+from gl46.constants import (
+    GL_ALL_BARRIER_BITS,
+    GL_ATOMIC_COUNTER_BARRIER_BIT,
+    GL_BUFFER_UPDATE_BARRIER_BIT,
+    GL_CLIENT_MAPPED_BUFFER_BARRIER_BIT,
+    GL_COMMAND_BARRIER_BIT,
+    GL_ELEMENT_ARRAY_BARRIER_BIT,
+    GL_FRAMEBUFFER_BARRIER_BIT,
+    GL_PIXEL_BUFFER_BARRIER_BIT,
+    GL_QUERY_BUFFER_BARRIER_BIT,
+    GL_SHADER_IMAGE_ACCESS_BARRIER_BIT,
+    GL_SHADER_STORAGE_BARRIER_BIT,
+    GL_TEXTURE_FETCH_BARRIER_BIT,
+    GL_TRANSFORM_FEEDBACK_BARRIER_BIT,
+    GL_UNIFORM_BARRIER_BIT,
+    GL_VERTEX_ATTRIB_ARRAY_BARRIER_BIT,
+)
+from gl46.gl import GL, get_gl
+
+
+class Barrier:
+    """Named memory-barrier bits plus helpers to post the common combos.
+
+    The class attributes are the individual ``GL_*_BARRIER_BIT`` masks; the
+    helpers post the barrier that pairs well with a freshly-written
+    resource.  Callers may also ``OR`` several attributes together and post
+    them with :meth:`post`.
+    """
+
+    SHADER_STORAGE = GL_SHADER_STORAGE_BARRIER_BIT
+    SHADER_IMAGE_ACCESS = GL_SHADER_IMAGE_ACCESS_BARRIER_BIT
+    TEXTURE_FETCH = GL_TEXTURE_FETCH_BARRIER_BIT
+    VERTEX_ATTRIB_ARRAY = GL_VERTEX_ATTRIB_ARRAY_BARRIER_BIT
+    ELEMENT_ARRAY = GL_ELEMENT_ARRAY_BARRIER_BIT
+    UNIFORM = GL_UNIFORM_BARRIER_BIT
+    COMMAND = GL_COMMAND_BARRIER_BIT
+    PIXEL_BUFFER = GL_PIXEL_BUFFER_BARRIER_BIT
+    BUFFER_UPDATE = GL_BUFFER_UPDATE_BARRIER_BIT
+    FRAMEBUFFER = GL_FRAMEBUFFER_BARRIER_BIT
+    TRANSFORM_FEEDBACK = GL_TRANSFORM_FEEDBACK_BARRIER_BIT
+    ATOMIC_COUNTER = GL_ATOMIC_COUNTER_BARRIER_BIT
+    QUERY_BUFFER = GL_QUERY_BUFFER_BARRIER_BIT
+    CLIENT_MAPPED = GL_CLIENT_MAPPED_BUFFER_BARRIER_BIT
+    ALL = GL_ALL_BARRIER_BITS
+
+    @staticmethod
+    def post(barriers: int, gl: GL | None = None) -> None:
+        """Post ``glMemoryBarrier`` with the given barrier bits."""
+        (gl if gl is not None else get_gl()).memory_barrier(barriers)
+
+    @classmethod
+    def shader_storage(cls, gl: GL | None = None) -> None:
+        """Post a shader-storage barrier before reading an SSBO written earlier."""
+        cls.post(cls.SHADER_STORAGE, gl)
+
+    @classmethod
+    def image_to_texture(cls, gl: GL | None = None) -> None:
+        """Post a barrier for compute writes to images read back as textures."""
+        cls.post(cls.SHADER_IMAGE_ACCESS | cls.TEXTURE_FETCH, gl)
+
+    @classmethod
+    def vertex_attributes(cls, gl: GL | None = None) -> None:
+        """Post a barrier after buffer writes read as vertex attributes."""
+        cls.post(cls.VERTEX_ATTRIB_ARRAY, gl)
+
+    @classmethod
+    def atomic_to_storage(cls, gl: GL | None = None) -> None:
+        """Post a barrier between atomic-counter and SSBO access."""
+        cls.post(cls.ATOMIC_COUNTER | cls.SHADER_STORAGE, gl)
+
+
+MemoryBarrier = Barrier
+
+__all__ = ["Barrier", "MemoryBarrier"]

gl46/base.py

@@ -0,0 +1,53 @@
+"""Base class shared by every GPU-backed object in :mod:`gl46`."""
+
+from __future__ import annotations
+
+from gl46.errors import GLObjectDeletedError
+from gl46.gl import GL, get_gl
+
+
+class GLObject:
+    """A GPU resource that owns a GL handle.
+
+    Subclasses allocate the handle in their ``__init__`` and implement
+    :meth:`_delete_impl` to release it. Calling :meth:`delete` twice, or
+    using a deleted object, is a no-op / guarded error respectively.
+    """
+
+    _gl: GL
+    _id: int
+    _deleted: bool
+
+    def __init__(self, gl: GL | None = None) -> None:
+        self._gl = gl if gl is not None else get_gl()
+        self._id = -1
+        self._deleted = False
+
+    @property
+    def id(self) -> int:
+        """The raw GL name (handle) of this object."""
+        self._require_alive()
+        return self._id
+
+    @property
+    def deleted(self) -> bool:
+        """True once the underlying GL object has been released."""
+        return self._deleted
+
+    def _require_alive(self) -> None:
+        if self._deleted:
+            raise GLObjectDeletedError(f"{type(self).__name__} has been deleted")
+
+    def delete(self) -> None:
+        """Release the GL resource. Safe to call multiple times."""
+        if self._deleted:
+            return
+        self._require_alive()
+        self._delete_impl()
+        self._deleted = True
+
+    def _delete_impl(self) -> None:
+        raise NotImplementedError
+
+
+__all__ = ["GLObject"]

gl46/buffer.py

@@ -0,0 +1,351 @@
+"""DSA vertex/index buffer wrapper around :func:`glCreateBuffers`."""
+
+from __future__ import annotations
+
+import ctypes
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from gl46.base import GLObject
+from gl46.constants import (
+    GL_ARRAY_BUFFER,
+    GL_DRAW_INDIRECT_BUFFER,
+    GL_DYNAMIC_STORAGE_BIT,
+    GL_ELEMENT_ARRAY_BUFFER,
+    GL_MAP_COHERENT_BIT,
+    GL_MAP_PERSISTENT_BIT,
+    GL_MAP_WRITE_BIT,
+    GL_SHADER_STORAGE_BUFFER,
+)
+from gl46.gl import GL, DataPayload
+
+
+def _payload_size(payload: DataPayload) -> int:
+    return len(payload) if isinstance(payload, bytes) else int(payload.nbytes)
+
+
+class Buffer(GLObject):
+    """An immutable-size GPU buffer (VBO/IBO/UBO/SSBO).
+
+    Storage is allocated once via ``glNamedBufferStorage``; its size and
+    usage flags are fixed for the lifetime of the buffer, which is exactly
+    the DSA idiom promoted by the OpenGL 4.6 style.
+    """
+
+    def __init__(
+        self,
+        size: int,
+        *,
+        dynamic: bool = False,
+        flags: int = 0,
+        gl: GL | None = None,
+        initial_data: DataPayload | None = None,
+    ) -> None:
+        super().__init__(gl)
+        if size < 0:
+            raise ValueError(f"buffer size must be >= 0, got {size}")
+        if initial_data is not None:
+            data_size = _payload_size(initial_data)
+            if data_size != size:
+                raise ValueError(
+                    f"initial_data is {data_size} bytes but buffer size is {size} "
+                    f"(glNamedBufferStorage copies exactly {size} bytes from the "
+                    f"payload, so the payload must match the storage size)"
+                )
+        self._size = size
+        if dynamic:
+            flags |= GL_DYNAMIC_STORAGE_BIT | GL_MAP_WRITE_BIT | GL_MAP_PERSISTENT_BIT
+        self._flags = flags
+        (self._id,) = self._gl.create_buffers(1)
+        self._gl.named_buffer_storage(self._id, size, initial_data, self._flags)
+
+    @classmethod
+    def from_data(
+        cls,
+        data: DataPayload,
+        *,
+        dynamic: bool = False,
+        flags: int = 0,
+        gl: GL | None = None,
+    ) -> Buffer:
+        """Allocate a buffer sized to ``data`` and upload it immediately.
+
+        The data is provided to ``glNamedBufferStorage`` directly, which is
+        the only way to populate immutable (non-``GL_DYNAMIC_STORAGE_BIT``)
+        storage; ``glNamedBufferSubData`` would raise ``GL_INVALID_OPERATION``.
+        """
+        return cls(_payload_size(data), dynamic=dynamic, flags=flags, gl=gl, initial_data=data)
+
+    @classmethod
+    def persistent(
+        cls,
+        size: int,
+        *,
+        initial_data: DataPayload | None = None,
+        gl: GL | None = None,
+    ) -> Buffer:
+        """Allocate ``size`` bytes persistently mapped and CPU/GPU coherent.
+
+        The storage gets ``GL_DYNAMIC_STORAGE_BIT | GL_MAP_WRITE_BIT |
+        GL_MAP_PERSISTENT_BIT | GL_MAP_COHERENT_BIT``, which allows the CPU
+        to write straight into the mapped region while the GPU reads it,
+        without any explicit flush or unmap.  ``initial_data`` may seed the
+        storage at allocation time.
+        """
+        flags = (
+            GL_DYNAMIC_STORAGE_BIT | GL_MAP_WRITE_BIT | GL_MAP_PERSISTENT_BIT | GL_MAP_COHERENT_BIT
+        )
+        return cls(size, flags=flags, gl=gl, initial_data=initial_data)
+
+    @property
+    def size_bytes(self) -> int:
+        return self._size
+
+    @property
+    def storage_flags(self) -> int:
+        return self._flags
+
+    def update(self, data: DataPayload, *, offset: int = 0) -> None:
+        """Upload ``data`` into the buffer at ``offset`` (``glNamedBufferSubData``)."""
+        self._require_alive()
+        size = _payload_size(data)
+        if offset + size > self._size:
+            raise ValueError(
+                f"upload of {size} bytes at offset {offset} "
+                f"exceeds buffer capacity of {self._size} bytes"
+            )
+        self._gl.named_buffer_sub_data(self._id, offset, size, data)
+
+    def bind(self, target: int = GL_ARRAY_BUFFER) -> None:
+        """Bind this buffer to ``target`` (usually only needed for legacy paths)."""
+        self._require_alive()
+        self._gl.bind_buffer(target, self._id)
+
+    def unbind(self, target: int = GL_ARRAY_BUFFER) -> None:
+        """Unbind any buffer from ``target`` (binds the null buffer)."""
+        self._gl.bind_buffer(target, 0)
+
+    def bind_range(
+        self,
+        target: int,
+        index: int,
+        *,
+        offset: int = 0,
+        size: int | None = None,
+    ) -> None:
+        """Bind a range of this buffer to a indexed target (``glBindBufferRange``).
+
+        ``size=None`` binds from ``offset`` to the end of the buffer; a
+        ``size`` of 0 binds an empty range.  Raises :class:`ValueError` if
+        the window is out of bounds.
+        """
+        self._require_alive()
+        effective = self._size - offset if size is None else size
+        if offset < 0 or effective < 0 or offset + effective > self._size:
+            raise ValueError(
+                f"bind_range({offset}, {effective}) exceeds buffer capacity of {self._size} bytes"
+            )
+        self._gl.bind_buffer_range(target, index, self._id, offset, effective)
+
+    def bind_base(self, target: int, index: int) -> None:
+        """Bind the whole buffer to an indexed target (``glBindBufferBase``)."""
+        self._require_alive()
+        self._gl.bind_buffer_base(target, index, self._id)
+
+    def map(self, access: int = GL_MAP_WRITE_BIT) -> MappedBuffer:
+        """Map the whole buffer for direct CPU access (``glMapNamedBuffer``).
+
+        Returns a :class:`MappedBuffer` context manager; the mapping stays
+        valid until it is used as a ``with`` block body ends (or
+        :meth:`Buffer.unmap` is called).  Only valid when the storage flags
+        include ``GL_MAP_*`` (and ``GL_MAP_PERSISTENT_BIT`` for a persistent
+        mapping).
+        """
+        self._require_alive()
+        address = self._gl.map_named_buffer(self._id, access)
+        return MappedBuffer(self, address, 0, self._size, access=access)
+
+    def map_range(self, offset: int, length: int, access: int = GL_MAP_WRITE_BIT) -> MappedBuffer:
+        """Map ``length`` bytes at ``offset`` (``glMapNamedBufferRange``).
+
+        Returns a :class:`MappedBuffer` context manager covering the mapped
+        window; GL writes start at ``offset`` but ``as_numpy`` offsets are
+        relative to the window start.  ``length`` must be at least 1 byte.
+        """
+        self._require_alive()
+        if length <= 0:
+            raise ValueError(f"map_range length must be > 0, got {length}")
+        if offset < 0 or offset + length > self._size:
+            raise ValueError(
+                f"map_range({offset}, {length}) exceeds buffer capacity of {self._size} bytes"
+            )
+        address = self._gl.map_named_buffer_range(self._id, offset, length, access)
+        return MappedBuffer(self, address, offset, length, access=access)
+
+    def unmap(self) -> None:
+        """Release the mapping created by :meth:`map` or :meth:`map_range`."""
+        self._require_alive()
+        self._gl.unmap_named_buffer(self._id)
+
+    def flush_mapped(self, offset: int = 0, length: int | None = None) -> None:
+        """Flush a mapped region so the GL sees the CPU writes
+        (``glFlushMappedNamedBufferRange``); defaults to the whole buffer."""
+        self._require_alive()
+        self._gl.flush_mapped_named_buffer_range(self._id, offset, length or self._size)
+
+    def _delete_impl(self) -> None:
+        self._gl.delete_buffers([self._id])
+
+
+class MappedBuffer:
+    """A context-managed CPU view over a mapped ``Buffer``.
+
+    Created by :meth:`Buffer.map` / :meth:`Buffer.map_range`.  The mapped
+    address is exposed as :attr:`address`; :meth:`as_numpy` returns a
+    numpy view over a slice.  Leaving the ``with`` block (or calling
+    :meth:`Buffer.unmap`) releases the mapping, after which the view must
+    no longer be used.  When the mapping was opened without
+    ``GL_MAP_WRITE_BIT``, :meth:`as_numpy` views are read-only.
+    """
+
+    def __init__(
+        self,
+        buffer: Buffer,
+        address: int,
+        offset: int,
+        length: int,
+        *,
+        access: int = GL_MAP_WRITE_BIT,
+    ) -> None:
+        self._buffer = buffer
+        self.address = address
+        self.offset = offset
+        self.length = length
+        self._access = access
+        self._closed = False
+
+    def as_numpy(self, dtype: Any, shape: tuple[int, ...], *, offset: int = 0) -> NDArray[Any]:
+        """Return a numpy array viewing ``shape`` elements.
+
+        ``offset`` is a byte offset within the mapped window.  The array
+        shares the mapped memory, so writes land straight in the GPU buffer
+        when the mapping is writable.
+        """
+        if self._closed:
+            raise ValueError("mapped buffer has been closed (unmapped)")
+        itemsize = np.dtype(dtype).itemsize
+        nbytes = int(np.prod(shape)) * itemsize
+        if offset < 0 or nbytes < 0 or offset + nbytes > self.length:
+            raise ValueError(
+                f"as_numpy view of {nbytes} bytes at offset {offset} "
+                f"exceeds mapped length of {self.length} bytes"
+            )
+        ctype = np.ctypeslib.as_ctypes_type(dtype)
+        array = np.ctypeslib.as_array(
+            ctypes.cast(self.address + offset, ctypes.POINTER(ctype)), shape=shape
+        )
+        if not self._access & GL_MAP_WRITE_BIT:
+            array.setflags(write=False)
+        return array
+
+    def __enter__(self) -> MappedBuffer:
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        if not self._closed:
+            self._closed = True
+            self._buffer.unmap()
+
+
+class ShaderStorage(Buffer):
+    """A shader storage buffer (SSBO) bound to a binding point once.
+
+    The buffer's storage is created from ``data`` and the whole buffer is
+    bound to ``binding`` on ``GL_SHADER_STORAGE_BUFFER`` at construction
+    time; updates via :meth:`update` must not change the byte size.
+    """
+
+    def __init__(
+        self,
+        binding: int,
+        data: DataPayload,
+        *,
+        flags: int = 0,
+        gl: GL | None = None,
+    ) -> None:
+        flags |= GL_DYNAMIC_STORAGE_BIT
+        super().__init__(_payload_size(data), flags=flags, gl=gl, initial_data=data)
+        self._binding = binding
+        self.bind_range(GL_SHADER_STORAGE_BUFFER, binding)
+
+    def update(self, data: DataPayload, *, offset: int = 0) -> None:
+        """Upload ``data`` into the buffer at ``offset``.
+
+        The size is immutable but partial updates are allowed as long as the
+        region fits inside the buffer.
+        """
+        self._require_alive()
+        size = _payload_size(data)
+        if offset + size > self._size:
+            raise ValueError(
+                f"ShaderStorage update of {size} bytes at offset {offset} "
+                f"exceeds capacity of {self._size} bytes"
+            )
+        self._gl.named_buffer_sub_data(self._id, offset, size, data)
+
+
+class EBO(Buffer):
+    """An element/index buffer (``GL_ELEMENT_ARRAY_BUFFER``)."""
+
+    def __init__(self, elements: np.ndarray, *, gl: GL | None = None) -> None:
+        if elements.dtype != np.uint32:
+            elements = elements.astype(np.uint32)
+        super().__init__(elements.nbytes, gl=gl, initial_data=elements)
+        self._elements = elements
+
+    def bind(self, target: int = GL_ELEMENT_ARRAY_BUFFER) -> None:
+        self._require_alive()
+        self._gl.bind_buffer(target, self._id)
+
+    def draw_count(self) -> int:
+        return int(self._elements.size)
+
+
+class IndirectDrawBuffer(Buffer):
+    """An indirect draw buffer holding ``DrawArraysIndirectCommand`` records.
+
+    The buffer stores one ``(count, instanceCount, first, baseInstance)``
+    uint32 quadruple per draw, ready for ``glDrawArraysIndirect``.
+    """
+
+    def __init__(
+        self,
+        count: np.ndarray,
+        instance_count: np.ndarray,
+        first: np.ndarray,
+        base_instance: np.ndarray,
+        *,
+        gl: GL | None = None,
+    ) -> None:
+        n = len(count)
+        commands = np.zeros((n, 4), dtype=np.uint32)
+        commands[:, 0] = count
+        commands[:, 1] = instance_count
+        commands[:, 2] = first
+        commands[:, 3] = base_instance
+        super().__init__(commands.nbytes, gl=gl, initial_data=commands)
+        self._commands = commands
+
+    def bind(self, target: int = GL_DRAW_INDIRECT_BUFFER) -> None:
+        self._require_alive()
+        self._gl.bind_buffer(target, self._id)
+
+    def draw_count(self) -> int:
+        return len(self._commands)
+
+
+IBO = IndirectDrawBuffer
+
+__all__ = ["EBO", "IBO", "Buffer", "IndirectDrawBuffer", "MappedBuffer", "ShaderStorage"]