pyglet 3.0.dev4__py3-none-any.whl → 3.0.dev5__py3-none-any.whl

pyglet/__init__.py

@@ -18,7 +18,7 @@ if TYPE_CHECKING:
     from typing import Any, Callable, ItemsView, Sized
 
 #: The release version
-version = '3.0.dev4'
+version = '3.0.dev5'
 __version__ = version
 
 MIN_PYTHON_VERSION = 3, 8

pyglet/customtypes.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import ctypes
 import sys
 
-from typing import Union, Literal, Type, Protocol, Tuple
+from typing import Union, Literal, Type, Protocol, Tuple, runtime_checkable
 
 from ctypes import _SimpleCData, _Pointer  # type: ignore  # noqa: PGH003
 
@@ -44,11 +44,16 @@ CTypesPointer = _Pointer
 
 
 
+@runtime_checkable
 class ScissorProtocol(Protocol):
-    x: int
-    y: int
-    width: int
-    height: int
+    """Protocol for an object that holds information for scissor states."""
+
+    @property
+    def area(self) -> tuple[int, int, int, int]:
+        """Return the region of the scissor area.
+
+        Requires the x, y, width, and height in screen space coordinates.
+        """
 
 
 
@@ -64,4 +69,5 @@ __all__ = [
     "MediaTypes",
     "RGBAColor",
     "RGBColor",
+    "ScissorProtocol",
 ]

pyglet/experimental/geoshader_sprite.py

@@ -768,9 +768,16 @@ class Sprite(event.EventDispatcher):
         efficiently.
         """
         ctx = pyglet.graphics.api.core.current_context
-        self._group.set_state_recursive(ctx)
+        draw_ctx = pyglet.graphics.draw.DrawContext(
+            surface_ctx=ctx,
+            backend_ctx=None,
+            draw_pass=pyglet.graphics.draw.BatchDrawOptions().resolve(ctx),
+            renderer=ctx.renderer,
+        )
+        draw_ctx.begin()
+        self._group.set_state_recursive(draw_ctx)
         self._vertex_list.draw(GeometryMode.POINTS)
-        self._group.unset_state_recursive(ctx)
+        self._group.unset_state_recursive(draw_ctx)
 
     def __del__(self):
         try:

pyglet/graphics/__init__.py

@@ -12,6 +12,14 @@ from typing import TYPE_CHECKING
 
 import pyglet
 
+class GraphicsBackendError(Exception):
+    """The base exception class for all graphics backends."""
+
+class GraphicsAPIError(GraphicsBackendError):
+    """An exception that occurs from the graphics API directly."""
+
+class GraphicsIntegrationError(GraphicsBackendError):
+    """An exception that occurs from pyglets internal graphics integration of the APIs."""
 
 class UnsupportedBackendError(Exception):
     """Raised when a graphics feature is unavailable on the active backend."""

pyglet/graphics/api/base.py

@@ -4,14 +4,19 @@ import atexit
 import os
 import weakref
 from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Protocol, get_type_hints, Sequence, Callable, NoReturn
 
+from pyglet.graphics import GraphicsIntegrationError, GraphicsBackendError
+from pyglet.util import debug_print
+
 if TYPE_CHECKING:
     from pyglet.config import SurfaceConfig
-    from pyglet.math import Mat4
     from pyglet.graphics.api.gl import ObjectSpace
+    from pyglet.graphics.buffer import BufferRange
     from pyglet.window import Window
 
+_debug_print = debug_print("debug_api")
 
 class BackendGlobalObject(ABC):  # Temp name for now.
     """A container for backend resources and information that are required throughout the code.
@@ -35,7 +40,11 @@ class BackendGlobalObject(ABC):  # Temp name for now.
         ...
 
     @abstractmethod
-    def get_surface_context(self, window: Window, config: SurfaceConfig, shared: SurfaceContext | None) -> SurfaceContext:
+    def get_surface_context(
+            self,
+            window: Window,
+            config: SurfaceConfig,
+            shared: SurfaceContext | None) -> SurfaceContext:
         """After a window is created, this will be called.
 
         This must return a BackendWindowObject object.
@@ -45,14 +54,29 @@ class BackendGlobalObject(ABC):  # Temp name for now.
     def get_default_configs(self) -> Sequence:
         """Configs to use if none specified."""
 
-    @abstractmethod
-    def initialize_matrices(self, window: Window) -> WindowTransformations:
-        """Initialize the global matrices."""
-
     @abstractmethod
     def set_viewport(self, window, x: int, y: int, width: int, height: int) -> None:
         """Set the global viewport."""
 
+
+class BackendRenderer(ABC):
+    """Backend-specific rendering helpers used by draw-context state transitions."""
+
+    def __init__(self, surface_ctx: SurfaceContext) -> None:
+        self.surface_ctx = surface_ctx
+
+    @abstractmethod
+    def set_viewport(self, x: int, y: int, width: int, height: int) -> None:
+        """Set the active viewport."""
+
+    @abstractmethod
+    def set_scissor(self, scissor: Any | None) -> None:
+        """Set or clear the active scissor rectangle."""
+
+    @abstractmethod
+    def set_clear_color(self, r: float, g: float, b: float, a: float) -> None:
+        """Set the active clear color."""
+
     @staticmethod
     def load_package_shader(package, resource_name):
         """Reads a binary resource from the given package or subpackage without external dependencies.
@@ -72,11 +96,19 @@ class BackendGlobalObject(ABC):  # Temp name for now.
         with open(resource_path, 'rb') as file:
             return file.read()
 
+
+class UnavailableBackendError(GraphicsBackendError):
+    """An exception that occurs when a backend is not yet available."""
+    def __init__(self) -> None:  # noqa: D107
+        super().__init__(
+            "A backend is not currently available. Ensure the backend choice is correct."
+            "If your environment variable is set to no backend, then backend-required resources may have been imported."
+        )
+
+
 class NullBackend(BackendGlobalObject):  # noqa: D101
     def _raise_no_backend(self) -> NoReturn:
-        msg = ("A backend is not currently available. Ensure the backend choice is correct. "
-               "If your environment variable is set to no backend, then backend-required resources may have been imported.")
-        raise RuntimeError(msg)
+        raise UnavailableBackendError
 
     @property
     def object_space(self) -> ObjectSpace:
@@ -89,9 +121,6 @@ class NullBackend(BackendGlobalObject):  # noqa: D101
     def get_default_configs(self) -> Sequence:
         self._raise_no_backend()
 
-    def initialize_matrices(self, window: Window) -> None:
-        self._raise_no_backend()
-
     def set_viewport(self, window, x: int, y: int, width: int, height: int) -> None:
         self._raise_no_backend()
 
@@ -120,6 +149,7 @@ class SurfaceInfo(ABC):
     MAX_TEXTURE_IMAGE_UNITS: int
     MAX_COMBINED_TEXTURE_IMAGE_UNITS: int
     MAX_UNIFORM_BUFFER_BINDINGS: int
+    MAX_UNIFORM_BUFFER_OFFSET_ALIGNMENT: int
     MAX_UNIFORM_BLOCK_SIZE: int
     MAX_VERTEX_ATTRIBS: int
 
@@ -142,6 +172,7 @@ class SurfaceInfo(ABC):
         self.MAX_TEXTURE_IMAGE_UNITS = 0
         self.MAX_COMBINED_TEXTURE_IMAGE_UNITS = 0
         self.MAX_UNIFORM_BUFFER_BINDINGS = 0
+        self.MAX_UNIFORM_BUFFER_OFFSET_ALIGNMENT = 0
         self.MAX_UNIFORM_BLOCK_SIZE = 0
         self.MAX_VERTEX_ATTRIBS = 0
 
@@ -196,17 +227,89 @@ class SurfaceInfo(ABC):
         return self.api
 
 
+@dataclass
+class FrameSlotData:
+    """Resources and fence state for one frame-in-flight slot."""
+
+    fence: Any | None = None
+    ubo_ranges: list[BufferRange] = field(default_factory=list)
+
+
+class FrameResourceManager:
+    """Tracks in-flight GPU-visible resource ranges by frame."""
+
+    def __init__(self, surface_ctx: SurfaceContext, slots: int = 3) -> None:
+        self.surface_ctx = surface_ctx
+        self.slots = [FrameSlotData() for _ in range(max(1, int(slots)))]
+        self._active_slot = self.slots[0]
+
+    @property
+    def active_slot(self) -> FrameSlotData:
+        return self._active_slot
+
+    def _release_slot(self, slot: FrameSlotData) -> None:
+        if slot.fence is not None:
+            self.surface_ctx.delete_frame_fence(slot.fence)
+            slot.fence = None
+        for ubo_range in slot.ubo_ranges:
+            ubo_range.frame_use_count = max(0, ubo_range.frame_use_count - 1)
+            ubo_range.in_use = ubo_range.frame_use_count > 0
+        slot.ubo_ranges.clear()
+
+    def frame_begin(self, frame_index: int) -> None:
+        slot_index = frame_index % len(self.slots)
+        slot = self.slots[slot_index]
+
+        if slot.fence is not None:
+            if not self.surface_ctx.poll_frame_fence(slot.fence):
+                # The frame resources are still in use by the GPU after we've wrapped around.
+                # At this point the CPU has caught up to the GPU. Wait for frame to become available.
+                assert _debug_print(f"CPU caught up to GPU on frame slot: {slot_index}, frame index: {frame_index}.")
+                self.surface_ctx.wait_frame_fence(slot.fence)
+            self._release_slot(slot)
+
+        self._active_slot = slot
+
+    def allocate_ubo(self, ubo_range: BufferRange) -> None:
+        if ubo_range.in_use:
+            msg = "Trying to allocate a UBO range that is already in use by a submitted frame."
+            raise GraphicsIntegrationError(msg)
+
+        self.use_ubo(ubo_range)
+
+    def use_ubo(self, ubo_range: BufferRange) -> None:
+        if any(active_range is ubo_range for active_range in self._active_slot.ubo_ranges):
+            return
+
+        ubo_range.frame_use_count += 1
+        ubo_range.in_use = True
+        self._active_slot.ubo_ranges.append(ubo_range)
+
+    def frame_submit(self) -> None:
+        if not self._active_slot.ubo_ranges:
+            return
+        self._active_slot.fence = self.surface_ctx.create_frame_fence()
+
+    def delete(self) -> None:
+        for slot in self.slots:
+            self._release_slot(slot)
+
+
 class SurfaceContext(ABC):  # Temp name for now.
     """A container for backend resources and information that are tied to a specific Window.
 
     In OpenGL this would be something like an OpenGL Context, or in Vulkan, a Surface.
     """
-    clear_color = (0.2, 0.2, 0.2, 1.0)
+    clear_color = (0.0, 0.0, 0.0, 1.0)
+    renderer: BackendRenderer
 
     def __init__(self, global_ctx: BackendGlobalObject, window: Window, config: Any) -> None:
         self.core = global_ctx
         self.window = window
         self.config = config
+        self.frame_index = 0
+        self._frame_active = False
+        self.frame_resources = FrameResourceManager(self)
 
     @property
     @abstractmethod
@@ -237,19 +340,69 @@ class SurfaceContext(ABC):  # Temp name for now.
         This function is called automatically when the operating system Window has been created.
         """
 
+    @property
+    def frame_active(self) -> bool:
+        return self._frame_active
+
     @abstractmethod
     def destroy(self) -> None:
         """Destroys the graphical context."""
 
+    def frame_begin(self) -> None:
+        """Begin a frame draw/update scope for this context."""
+        self.frame_resources.frame_begin(self.frame_index)
+        self._frame_active = True
+
+    def frame_submit(self) -> None:
+        """Submit queued GPU work for the current frame."""
+        self.frame_resources.frame_submit()
+
+    def create_frame_fence(self) -> Any | None:
+        """Create a backend fence for submitted frame resources."""
+        return None
+
+    def poll_frame_fence(self, fence: Any) -> bool:
+        """Return whether a submitted frame fence has completed."""
+        return True
+
+    def wait_frame_fence(self, fence: Any) -> None:
+        """Waits until a submitted frame fence has completed.
+
+        This is a blocking operation.
+        """
+
+    def delete_frame_fence(self, fence: Any) -> None:
+        """Delete a submitted frame fence."""
+
+    def frame_end(self) -> None:
+        """Finalize the current frame, present, and advance frame index."""
+        if not self._frame_active:
+            return
+        try:
+            self.frame_submit()
+            self.present()
+            self.frame_index += 1
+        finally:
+            self._frame_active = False
+
     @abstractmethod
-    def flip(self) -> None:
-        """Flips the buffers in the graphical context."""
+    def present(self) -> None:
+        """Present rendered frame output."""
 
     @abstractmethod
     def clear(self) -> None:
         """Clears the framebuffer."""
 
 
+class UnavailableContextError(GraphicsBackendError):
+    """An exception that occurs when a backend context is not yet available."""
+    def __init__(self) -> None:  # noqa: D107
+        super().__init__(
+            "A Rendering Context has not yet been created, or has already been deleted. Please ensure "
+            "a context exists (create a Window) before attempting to create objects with GPU resources.",
+        )
+
+
 class NullContext:
     """Used to represent a Null state before a Context is created.
 
@@ -264,9 +417,7 @@ class NullContext:
 
     @staticmethod
     def _raise_no_context() -> NoReturn:
-        msg = ("A rendering Context has not yet been created, or has already been deleted. Please ensure "
-               "a context exists (create a Window) before attempting to perform any GPU related activities.")
-        raise RuntimeError(msg)
+        raise UnavailableContextError
 
     def __getattribute__(self, item):
         object.__getattribute__(self, "_raise_no_context")()
@@ -391,42 +542,6 @@ class GraphicsConfig:
         return self._user_set_attributes
 
 
-class WindowTransformations:
-    def __init__(self, window, projection, view, model):
-        self._window = window
-        self._projection = projection
-        self._view = view
-        self._model = model
-
-    @property
-    def projection(self) -> Mat4:
-        return self._projection
-
-    @projection.setter
-    def projection(self, projection: Mat4) -> None:
-        self._projection = projection
-
-    @property
-    def view(self) -> Mat4:
-        return self._view
-
-    @view.setter
-    def view(self, view: Mat4) -> None:
-        self._view = view
-
-    @property
-    def model(self) -> Mat4:
-        return self._model
-
-    @model.setter
-    def model(self, model: Mat4) -> None:
-        self._model = model
-
-
-class UBOMatrixTransformations(WindowTransformations):  # noqa: D101
-    ...
-
-
 class GraphicsResource(Protocol):  # noqa: D101
     def delete(self) -> None:
         ...

pyglet/graphics/api/gl/buffer.py

@@ -13,12 +13,12 @@ from pyglet.graphics.api.gl import (
     GL_DRAW_INDIRECT_BUFFER,
     GL_DYNAMIC_DRAW,
     GL_ELEMENT_ARRAY_BUFFER,
+    GL_MAP_READ_BIT,
+    GL_MAP_WRITE_BIT,
     GL_READ_ONLY,
     GL_READ_WRITE,
     GL_MAP_COHERENT_BIT,
     GL_MAP_PERSISTENT_BIT,
-    GL_MAP_READ_BIT,
-    GL_MAP_WRITE_BIT,
     GL_PIXEL_PACK_BUFFER,
     GL_PIXEL_UNPACK_BUFFER,
     GL_TEXTURE_BUFFER,
@@ -491,11 +491,40 @@ class GLUniformBufferObject(UniformBufferObject):
     """OpenGL Uniform Buffer Object wrapper."""
 
     buffer: GLBufferObject
-    __slots__ = ()
+    minimum_alignment: int
+    __slots__ = ("minimum_alignment",)
+
+    def __init__(
+        self,
+        context: OpenGLSurfaceContext,
+        view_class: type[ctypes.Structure],
+        buffer_size: int,
+        binding: int,
+        *,
+        alignment: int | None = None,
+        copies_per_resource: int = 3,
+        strict: bool = False,
+    ) -> None:
+        self._context = context
+        self.minimum_alignment = max(1, context.info.MAX_UNIFORM_BUFFER_OFFSET_ALIGNMENT)
+        requested_alignment = (
+            self.minimum_alignment if alignment is None else max(int(alignment), self.minimum_alignment)
+        )
+        super().__init__(
+            context,
+            view_class,
+            buffer_size,
+            binding,
+            alignment=requested_alignment,
+            copies_per_resource=copies_per_resource,
+            strict=strict,
+        )
 
     def _create_buffer(self, context: OpenGLSurfaceContext, buffer_size: int) -> GLBufferObject:
         return GLBufferObject(context, buffer_size, target=GL_UNIFORM_BUFFER)
 
+    def _bind_range(self, binding: int, offset: int, size: int) -> None:
+        self._context.glBindBufferRange(GL_UNIFORM_BUFFER, binding, self.buffer.id, offset, size)
 
 class PersistentBufferObject(BaseMappedBufferObject):
     """A persistently mapped OpenGL buffer.
@@ -559,7 +588,10 @@ class PersistentBufferObject(BaseMappedBufferObject):
         self._context.glBufferStorage(self.target, storage_size, data, self.flags)
 
         ptr_type = ctypes.POINTER(ctypes.c_byte * storage_size)
-        mapped = ctypes.cast(self._context.glMapBufferRange(self.target, 0, storage_size, self.flags), ptr_type).contents
+        mapped = ctypes.cast(
+            self._context.glMapBufferRange(self.target, 0, storage_size, self.flags),
+            ptr_type,
+        ).contents
         mapped_ptr = ctypes.addressof(mapped)
         return new_id, mapped, mapped_ptr, storage_size
 

pyglet/graphics/api/gl/cocoa/context.py

@@ -72,5 +72,5 @@ class CocoaContext(OpenGLSurfaceContext):
         self._nscontext.getValues_forParameter_(byref(vals), cocoapy.NSOpenGLCPSwapInterval)
         return bool(vals.value)
 
-    def flip(self) -> None:
+    def present(self) -> None:
         self._nscontext.flushBuffer()

pyglet/graphics/api/gl/context.py

@@ -5,10 +5,23 @@ import weakref
 from typing import Callable, TYPE_CHECKING
 
 from pyglet.enums import GraphicsAPI
+from pyglet.graphics import GraphicsAPIError, GraphicsIntegrationError
 from pyglet.graphics.api.gl import gl, gl_info, ObjectSpace
 from pyglet.graphics.api.base import SurfaceContext, NullContext
-from pyglet.graphics.api.gl.gl import GLFunctions, GLuint, GL_COLOR_BUFFER_BIT, GL_DEPTH_BUFFER_BIT
-
+from pyglet.graphics.api.gl.gl import (
+    GL_ALREADY_SIGNALED,
+    GL_COLOR_BUFFER_BIT,
+    GL_CONDITION_SATISFIED,
+    GL_DEPTH_BUFFER_BIT,
+    GL_SYNC_GPU_COMMANDS_COMPLETE,
+    GL_TIMEOUT_EXPIRED,
+    GL_WAIT_FAILED,
+    GLFunctions,
+    GLuint,
+    GL_SYNC_FLUSH_COMMANDS_BIT,
+    GL_TIMEOUT_IGNORED,
+)
+from pyglet.graphics.api.gl.renderer import GLRenderer
 
 if TYPE_CHECKING:
     from pyglet.config import SurfaceConfig
@@ -50,10 +63,7 @@ class OpenGLSurfaceContext(SurfaceContext, GLFunctions):
                 A context to share objects with. Use ``None`` to disable sharing.
         """
         self._context = None
-        self.core = core
-        self.window = window
-        self.config = config
-        #super().__init__(core, window, config)
+        super().__init__(core, window, config)
         self.context_share = context_share or None  # Use a real NoneType instead of NullContext
         self.is_current = False
         self._info = gl_info.GLInfo(platform_info)
@@ -69,6 +79,7 @@ class OpenGLSurfaceContext(SurfaceContext, GLFunctions):
             self.object_space = ObjectSpace()
 
         self.cached_programs = weakref.WeakValueDictionary()
+        self.renderer = GLRenderer(self)
 
         # GLES needs an FBO to read pixel data.
         self.gles_pixel_fbo = None
@@ -108,8 +119,36 @@ class OpenGLSurfaceContext(SurfaceContext, GLFunctions):
         #     raise RuntimeError(msg)
         self.window = window
 
-    def before_draw(self) -> None:
+    def frame_begin(self) -> None:
         self.set_current()
+        super().frame_begin()
+
+    def create_frame_fence(self) -> object | None:
+        if not (self.info.have_version(3, 2) or self.info.have_extension("GL_ARB_sync")):
+            return None
+        return self.glFenceSync(GL_SYNC_GPU_COMMANDS_COMPLETE, 0)
+
+    def wait_frame_fence(self, fence) -> None:
+        self.glClientWaitSync(fence, GL_SYNC_FLUSH_COMMANDS_BIT, GL_TIMEOUT_IGNORED)
+
+    def poll_frame_fence(self, fence) -> bool:
+        if fence is None:
+            return True
+
+        result = self.glClientWaitSync(fence, 0, 0)
+        if result in (GL_ALREADY_SIGNALED, GL_CONDITION_SATISFIED):
+            return True
+        if result == GL_TIMEOUT_EXPIRED:
+            return False
+        if result == GL_WAIT_FAILED:
+            raise GraphicsAPIError("glClientWaitSync failed")
+
+        msg = f"Unexpected glClientWaitSync result: {result}"
+        raise GraphicsIntegrationError(msg)
+
+    def delete_frame_fence(self, fence) -> None:
+        if fence is not None:
+            self.glDeleteSync(fence)
 
     def set_current(self) -> None:
         """Make this the active Context.