pyglet 3.0.dev5__tar.gz → 3.0.dev6__tar.gz

{pyglet-3.0.dev5 → pyglet-3.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyglet
-Version: 3.0.dev5
+Version: 3.0.dev6
 Summary: pyglet is a cross-platform games and multimedia package.
 Author-email: Alex Holkner & contributors <Alex.Holkner@gmail.com>
 Requires-Python: >=3.10

{pyglet-3.0.dev5 → pyglet-3.0.dev6}/doc/index.rst

@@ -42,6 +42,7 @@ If you are migrating from an older version of pyglet, please read through
    programming_guide/installation
    programming_guide/quickstart
    programming_guide/windowing
+   programming_guide/camera
    programming_guide/keyboard
    programming_guide/mouse
    programming_guide/input

{pyglet-3.0.dev5 → pyglet-3.0.dev6}/doc/programming_guide/camera.rst

@@ -93,8 +93,9 @@ Attach camera scopes to groups with ``Group.set_camera``::
     pyglet.sprite.Sprite(world_image, batch=batch, group=world_group)
     pyglet.text.Label("HUD", batch=batch, group=ui_group)
 
-``Group.set_camera`` applies camera state at draw entry by calling ``begin()``.
-It does not call ``end()`` during group unsetting.
+
+.. note:: ``Group.set_camera`` applies camera state at draw entry by calling ``begin()``.
+          It does not call ``end()`` during group unsetting.
 
 Viewport
 --------

{pyglet-3.0.dev5 → pyglet-3.0.dev6}/doc/requirements.txt

@@ -1,5 +1,5 @@
-sphinx==9.1.0
+sphinx==9.0.4
 sphinx_rtd_theme==3.1.0
 readthedocs-sphinx-search==0.3.2
-sphinx-autodoc-typehints==3.10.2
+sphinx-autodoc-typehints==3.6.1
 pytest

pyglet-3.0.dev6/examples/graphics/uniform_buffer_object.py

@@ -0,0 +1,152 @@
+"""Uniform Buffer Object region example.
+
+This example uses one shader program with three material UBO regions. Each
+group binds a different region before its shape is drawn.
+"""
+
+from __future__ import annotations
+
+import math
+
+import pyglet
+from pyglet.enums import GeometryMode, GraphicsAPI
+
+
+if pyglet.options.backend != GraphicsAPI.OPENGL:
+    raise RuntimeError("This example uses OpenGL 3.3 shader syntax. Run it with the OpenGL backend.")
+
+
+window = pyglet.window.Window(width=720, height=480, caption="Uniform Buffer Object", resizable=True)
+batch = pyglet.graphics.Batch()
+
+
+vertex_source = """#version 330 core
+    in vec2 position;
+
+    uniform WindowBlock
+    {
+        mat4 projection;
+        mat4 view;
+    } window;
+
+    layout(std140) uniform MaterialBlock
+    {
+        vec4 color;
+        vec4 offset_scale;
+    } material;
+
+    out vec4 vertex_color;
+
+    void main()
+    {
+        vec2 scaled_position = position * material.offset_scale.zw;
+        vec2 world_position = scaled_position + material.offset_scale.xy;
+        gl_Position = window.projection * window.view * vec4(world_position, 0.0, 1.0);
+        vertex_color = material.color;
+    }
+"""
+
+fragment_source = """#version 330 core
+    in vec4 vertex_color;
+    out vec4 final_color;
+
+    void main()
+    {
+        final_color = vertex_color;
+    }
+"""
+
+program = pyglet.graphics.ShaderProgram(
+    pyglet.graphics.Shader(vertex_source, "vertex"),
+    pyglet.graphics.Shader(fragment_source, "fragment"),
+)
+
+material_block = program.uniform_blocks["MaterialBlock"]
+
+
+def create_material(color: tuple[float, float, float, float],
+                    offset_scale: tuple[float, float, float, float]):
+    region = material_block.create_ubo_region()
+    # When creating the material, ensure it has some initial data.
+    with region as material_region:
+        material_region.color[:] = color
+        material_region.offset_scale[:] = offset_scale
+    return region
+
+
+triangle_vertices = (
+    -0.6, -0.5,
+     0.6, -0.5,
+     0.0,  0.6,
+)
+
+quad_vertices = (
+    -0.5, -0.5,
+     0.5, -0.5,
+     0.5,  0.5,
+    -0.5,  0.5,
+)
+
+materials = [
+    create_material((0.95, 0.30, 0.22, 1.0), (160.0, 240.0, 100.0, 100.0)),
+    create_material((0.18, 0.64, 0.96, 1.0), (360.0, 240.0, 120.0, 120.0)),
+    create_material((0.90, 0.82, 0.28, 1.0), (560.0, 240.0, 90.0, 90.0)),
+]
+elapsed_time = 0.0
+
+groups = []
+# Give each separate material its own group, so the dirty regions can be committed during draw.
+for material in materials:
+    group = pyglet.graphics.ShaderGroup(program)
+    group.set_uniform_buffer(material)
+    groups.append(group)
+
+triangle_1 = program.vertex_list(
+    3,
+    GeometryMode.TRIANGLES,
+    batch=batch,
+    group=groups[0],
+    position=("f", triangle_vertices),
+)
+triangle_2 = program.vertex_list_indexed(
+    4,
+    GeometryMode.TRIANGLES,
+    indices=(0, 1, 2, 0, 2, 3),
+    batch=batch,
+    group=groups[1],
+    position=("f", quad_vertices),
+)
+triangle_3 = program.vertex_list(
+    3,
+    GeometryMode.TRIANGLES,
+    batch=batch,
+    group=groups[2],
+    position=("f", triangle_vertices),
+)
+
+
+def update_materials(dt: float) -> None:
+    global elapsed_time
+    elapsed_time += dt
+
+    for index, region in enumerate(materials):
+        angle = elapsed_time * 1.6 + index * 2.1
+        center_x = 360.0 + math.cos(angle) * (120.0 + index * 18.0)
+        center_y = 240.0 + math.sin(angle * 0.8) * (70.0 + index * 12.0)
+
+        with region as material_region:
+            material_region.offset_scale[0] = center_x
+            material_region.offset_scale[1] = center_y
+
+
+@window.event
+def on_draw() -> None:
+    window.clear()
+    batch.draw()
+
+
+pyglet.clock.schedule_interval(update_materials, 1 / 60)
+
+
+if __name__ == "__main__":
+    pyglet.app.run()

pyglet-3.0.dev6/examples/model/model.py

@@ -0,0 +1,44 @@
+import pyglet
+
+from pyglet.math import Mat4, Vec3, Quaternion
+
+window = pyglet.window.Window(resizable=True)
+batch = pyglet.graphics.Batch()
+camera = pyglet.window.camera.FPSCamera(window, position=Vec3(0.0, 0.0, 5.0), target=Vec3(0.0, 0.0, 0.0))
+
+
+@window.event
+def on_draw():
+    window.clear()
+    # Set the camera explicity while drawing the Batch:
+    with batch.draw_with_options() as options:
+        options.camera = camera
+
+
+def animate(dt):
+    animate.elapsed += dt
+
+    rot_x = Quaternion.from_rotation(animate.elapsed/1, Vec3(1, 0, 0))
+    rot_y = Quaternion.from_rotation(animate.elapsed/2, Vec3(0, 1, 0))
+    rot_z = Quaternion.from_rotation(animate.elapsed/3, Vec3(0, 0, 1))
+    model_logo_instance.rotation = rot_x @ rot_y @ rot_z
+
+    rot_x = Quaternion.from_rotation(animate.elapsed/1, Vec3(1, 0, 0))
+    rot_y = Quaternion.from_rotation(animate.elapsed/2, Vec3(0, 1, 0))
+    rot_z = Quaternion.from_rotation(animate.elapsed/3, Vec3(0, 0, 1))
+    model_box_instance.rotation = rot_x @ rot_y @ rot_z
+
+
+if __name__ == "__main__":
+    logo_scene = pyglet.resource.scene('logo3d.obj')
+    box_scene = pyglet.resource.scene('box.obj')
+
+    model_logo = logo_scene.create_models(batch=batch)[0]   # only one model in this scene
+    model_logo_instance = model_logo.create_instance(translation=Vec3(1.25, 0.0, 1.0))
+
+    model_box = box_scene.create_models(batch=batch)[0]     # only one model in this scene
+    model_box_instance = model_box.create_instance(translation=Vec3(-1.25, 0.0, 0.0))
+
+    animate.elapsed = 0.0
+    pyglet.clock.schedule_interval(animate, 1 / 60)
+    pyglet.app.run()

pyglet-3.0.dev6/examples/window/file_drag_drops.py

@@ -0,0 +1,114 @@
+"""Highlight a drop zone while dragging files over a Window.
+
+This example is intended for platforms that support file drag events.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pyglet
+from pyglet import shapes
+
+
+class FileDragDropApp:
+    zone_width = 460
+    zone_height = 220
+
+    zone_normal = (70, 70, 80, 255)
+    zone_hover = (80, 170, 110, 255)
+    zone_border_normal = (130, 130, 140, 255)
+    zone_border_hover = (210, 240, 210, 255)
+
+    def __init__(self) -> None:
+        self.window = pyglet.window.Window(900, 600, caption="File Drag Drop Zone", file_drops=True)
+        self.batch = pyglet.graphics.Batch()
+        self.drag_paths: list[str] = []
+        self.zone_hovered = False
+
+        self.zone_x = (self.window.width - self.zone_width) // 2
+        self.zone_y = (self.window.height - self.zone_height) // 2
+
+        self.drop_zone = shapes.Rectangle(self.zone_x, self.zone_y,
+                                          self.zone_width, self.zone_height,
+                                          color=self.zone_normal, batch=self.batch)
+
+        self.drop_zone_border = shapes.BorderedRectangle(self.zone_x, self.zone_y,
+                                                        self.zone_width, self.zone_height,
+                                                        border=4,
+                                                        color=self.zone_normal,
+                                                        border_color=self.zone_border_normal,
+                                                        batch=self.batch)
+
+        self.status_label = pyglet.text.Label("Drag one or more files into the window.",
+                                              x=self.window.width // 2, y=self.window.height - 40,
+                                              anchor_x='center', anchor_y='center',
+                                              font_size=14, batch=self.batch)
+
+        self.zone_label = pyglet.text.Label("Drop Inside This Area",
+                                            x=self.window.width // 2, y=self.window.height // 2,
+                                            anchor_x='center', anchor_y='center',
+                                            font_size=18, weight="bold", batch=self.batch)
+
+        self.result_label = pyglet.text.Label("",
+                                              x=self.window.width // 2, y=70,
+                                              width=self.window.width - 60,
+                                              multiline=True,
+                                              anchor_x='center', anchor_y='center',
+                                              align='center',
+                                              font_size=12, batch=self.batch)
+
+        self.window.push_handlers(self)
+
+    def _drop_hit_test(self, x: int, y: int) -> bool:
+        """Returns True if the mouse coordinates intersect the drop zone area."""
+        return (self.zone_x <= x <= self.zone_x + self.zone_width
+                and self.zone_y <= y <= self.zone_y + self.zone_height)
+
+    def _set_zone_hover(self, hovered: bool) -> None:
+        self.zone_hovered = hovered
+
+        if hovered:
+            self.drop_zone.color = self.zone_hover
+            self.drop_zone_border.border_color = self.zone_border_hover
+        else:
+            self.drop_zone.color = self.zone_normal
+            self.drop_zone_border.border_color = self.zone_border_normal
+
+    def on_draw(self) -> None:
+        self.window.clear()
+        self.batch.draw()
+
+    def on_file_drag_enter(self, x: int, y: int, paths: list[str]) -> None:
+        self.drag_paths = paths
+        self._set_zone_hover(self._drop_hit_test(x, y))
+        self.status_label.text = f"Dragging {len(paths)} file(s)..."
+
+    def on_file_drag(self, x: int, y: int, paths: list[str]) -> None:
+        self.drag_paths = paths
+        self._set_zone_hover(self._drop_hit_test(x, y))
+
+    def on_file_drag_exit(self) -> None:
+        """Drag was lost or exited the window."""
+        self.drag_paths = []
+        self._set_zone_hover(False)
+        self.status_label.text = "Drag one or more files into the window."
+
+    def on_file_drop(self, x: int, y: int, paths: list[str]) -> None:
+        self.drag_paths = []
+        self._set_zone_hover(False)
+
+        if self._drop_hit_test(x, y):
+            basenames = ", ".join(Path(path).name for path in paths[:3])
+            if len(paths) > 3:
+                basenames += ", ..."
+            self.status_label.text = "Drop accepted."
+            self.result_label.text = f"Dropped {len(paths)} file(s): {basenames}"
+        else:
+            self.status_label.text = "Drop missed zone."
+            self.result_label.text = "Drop happened outside the target area."
+
+
+if __name__ == '__main__':
+    file_drop = FileDragDropApp()
+    pyglet.app.run()

{pyglet-3.0.dev5 → pyglet-3.0.dev6}/pyglet/__init__.py

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

{pyglet-3.0.dev5 → pyglet-3.0.dev6}/pyglet/event.py

@@ -121,7 +121,6 @@ from __future__ import annotations
 import inspect
 import os.path
 
-from functools import partial
 from typing import TYPE_CHECKING, Literal, Union
 from weakref import WeakMethod
 
@@ -193,7 +192,7 @@ class EventDispatcher:
                     msg = f'Unknown event "{name}"'
                     raise EventException(msg)
                 if inspect.ismethod(obj):
-                    yield name, WeakMethod(obj, partial(self._remove_handler, name))
+                    yield name, WeakMethod(obj)
                 else:
                     yield name, obj
             else:
@@ -201,7 +200,7 @@ class EventDispatcher:
                 for name in dir(obj):
                     if name in self.event_types:
                         meth = getattr(obj, name)
-                        yield name, WeakMethod(meth, partial(self._remove_handler, name))
+                        yield name, WeakMethod(meth)
 
         for name, handler in kwargs.items():
             # Function for handling given event (no magic)
@@ -209,7 +208,7 @@ class EventDispatcher:
                 msg = f'Unknown event "{name}"'
                 raise EventException(msg)
             if inspect.ismethod(handler):
-                yield name, WeakMethod(handler, partial(self._remove_handler, name))
+                yield name, WeakMethod(handler)
             else:
                 yield name, handler
 
@@ -303,25 +302,6 @@ class EventDispatcher:
             except KeyError:
                 pass
 
-    def _remove_handler(self, name: str, handler: Callable) -> None:
-        """Used internally to remove all handler instances for the given event name.
-
-        This is normally called from a dead ``WeakMethod`` to remove itself from the
-        event stack.
-        """
-        # Iterate over a copy as we might mutate the list
-        for frame in list(self._event_stack):
-
-            if name in frame:
-                try:
-                    if frame[name] == handler:
-                        del frame[name]
-                        if not frame:
-                            self._event_stack.remove(frame)
-                except TypeError:
-                    # weakref is already dead
-                    pass
-
     def dispatch_event(self, event_type: str, *args: Any) -> bool | None:
         """Dispatch an event to the attached event handlers.
 

{pyglet-3.0.dev5 → pyglet-3.0.dev6}/pyglet/graphics/__init__.py

@@ -37,6 +37,7 @@ if TYPE_CHECKING:
     from pyglet.graphics.shader import Shader, ShaderProgram, ComputeShaderProgram, TransformFeedbackShaderProgram  # noqa: F401
     from pyglet.graphics.state import State  # noqa: F401
     from pyglet.graphics.shader import get_default_shader  # noqa: F401
+    from pyglet.graphics.buffer import UniformBufferRegion  # noqa: F401
     from pyglet.graphics.draw import get_default_batch  # noqa: F401
     from pyglet.graphics.texture import Texture, TextureGrid, Texture3D, TextureArray  # noqa: F401
     from pyglet.graphics.atlas import TextureBin, TextureArrayBin, TextureAtlas  # noqa: F401
@@ -53,6 +54,7 @@ else:
     )
     from pyglet.graphics.state import State  # noqa: F401
     from pyglet.graphics.api import core  # noqa: F401
+    from pyglet.graphics.buffer import UniformBufferRegion  # noqa: F401
     from pyglet.graphics.texture import Texture, TextureGrid, Texture3D, TextureArray  # noqa: F401
     from pyglet.graphics.atlas import TextureBin, TextureArrayBin, TextureAtlas  # noqa: F401
     from pyglet.graphics.framebuffer import Framebuffer, Renderbuffer  # noqa: F401

{pyglet-3.0.dev5 → pyglet-3.0.dev6}/pyglet/graphics/api/gl/state.py

@@ -16,6 +16,7 @@ if TYPE_CHECKING:
     from pyglet.customtypes import ScissorProtocol
     from pyglet.graphics.draw import DrawContext
     from pyglet.graphics.api.gl.shader import ShaderProgram
+    from pyglet.graphics.buffer import UniformBufferRegion
     from pyglet.graphics.texture import Texture
 
 
@@ -50,8 +51,9 @@ class TextureState(State):  # noqa: D101
 
 @dataclass(frozen=True)
 class MultiTextureSamplerState(State):
-    """Static per-program sampler bindings for multi-texture draws."""
+    """Texture bindings and sampler uniforms for multi-texture draws."""
     program: ShaderProgram
+    textures: tuple[tuple[tuple[int, int], int, int], ...]
     uniforms: tuple[tuple[str, int], ...]
 
     sets_state: bool = True
@@ -61,10 +63,20 @@ class MultiTextureSamplerState(State):
             cls,
             program: ShaderProgram,
             textures: dict[str, Texture],
-            first_texture_unit: int = 0) -> MultiTextureSamplerState:
-        return cls(program, tuple((name, idx) for idx, name in enumerate(textures, first_texture_unit)))
+            first_texture_unit: int = 0,
+            set_id: int = 0) -> MultiTextureSamplerState:
+        texture_states = tuple(
+            ((texture.target, texture.id), texture_unit, set_id)
+            for texture_unit, texture in enumerate(textures.values(), first_texture_unit)
+        )
+        uniforms = tuple((name, idx) for idx, name in enumerate(textures, first_texture_unit))
+        return cls(program, texture_states, uniforms)
 
     def set_state(self, ctx: DrawContext) -> None:
+        for texture, texture_unit, _set_id in self.textures:
+            ctx.surface_ctx.glActiveTexture(GL_TEXTURE0 + texture_unit)
+            ctx.surface_ctx.glBindTexture(*texture)
+
         for uniform_name, texture_unit in self.uniforms:
             self.program[uniform_name] = texture_unit
 
@@ -216,8 +228,13 @@ class ViewportState(_BaseViewportState):
 
 @dataclass(frozen=True)
 class UniformBufferState(State):
-    name: str
-    binding: int
+    region: UniformBufferRegion
+    binding_index: int | None = None
+
+    sets_state: bool = True
+
+    def set_state(self, ctx: DrawContext) -> None:
+        self.region.bind(binding_index=self.binding_index)
 
 
 @dataclass(frozen=True)

{pyglet-3.0.dev5 → pyglet-3.0.dev6}/pyglet/graphics/api/gl2/state.py

@@ -5,7 +5,7 @@ from dataclasses import dataclass
 from pyglet.graphics.state import State
 from typing import TYPE_CHECKING
 from pyglet.graphics.api.gl.state import (TextureState, MultiTextureSamplerState, BlendState, ShaderUniformState,   # noqa: F401
-                                          DepthBufferComparison, ScissorState, ViewportState)
+                                          DepthBufferComparison, ScissorState, UniformBufferState, ViewportState)
 
 
 if TYPE_CHECKING:
@@ -24,6 +24,6 @@ class ShaderProgramState(State):
         ctx.active_shader_program = self.program
 
         if ctx.active_camera and ctx.active_camera.view.storage:
-            ctx.active_camera.view.storage.bind(ctx)
+            ctx.active_camera.view.storage.bind_camera(ctx)
 
 

{pyglet-3.0.dev5 → pyglet-3.0.dev6}/pyglet/graphics/api/webgl/state.py

@@ -10,6 +10,7 @@ from pyglet.graphics.state import State, _BaseScissorState, _BaseViewportState
 
 if TYPE_CHECKING:
     from pyglet.customtypes import ScissorProtocol
+    from pyglet.graphics.buffer import UniformBufferRegion
     from pyglet.graphics.api.webgl.shader import ShaderProgram
     from pyglet.graphics.draw import DrawContext
     from pyglet.graphics.texture import Texture
@@ -53,9 +54,11 @@ class TextureState(State):  # noqa: D101
 
 @dataclass(frozen=True)
 class MultiTextureSamplerState(State):
-    """Static per-program sampler bindings for multi-texture draws."""
+    """Texture bindings and sampler uniforms for multi-texture draws."""
     program: ShaderProgram
+    textures: tuple[tuple[tuple[int, int], int, int], ...]
     uniforms: tuple[tuple[str, int], ...]
+    webgl_textures: tuple[Any, ...] = field(hash=False, compare=False)
 
     sets_state: bool = True
 
@@ -64,10 +67,21 @@ class MultiTextureSamplerState(State):
             cls,
             program: ShaderProgram,
             textures: dict[str, Texture],
-            first_texture_unit: int = 0) -> MultiTextureSamplerState:
-        return cls(program, tuple((name, idx) for idx, name in enumerate(textures, first_texture_unit)))
+            first_texture_unit: int = 0,
+            set_id: int = 0) -> MultiTextureSamplerState:
+        texture_states = tuple(
+            ((texture.target, id(texture.id)), texture_unit, set_id)
+            for texture_unit, texture in enumerate(textures.values(), first_texture_unit)
+        )
+        uniforms = tuple((name, idx) for idx, name in enumerate(textures, first_texture_unit))
+        webgl_textures = tuple(texture.id for texture in textures.values())
+        return cls(program, texture_states, uniforms, webgl_textures)
 
     def set_state(self, ctx: DrawContext) -> None:
+        for (texture, texture_unit, _set_id), webgl_texture in zip(self.textures, self.webgl_textures):
+            ctx.surface_ctx.gl.activeTexture(GL_TEXTURE0 + texture_unit)
+            ctx.surface_ctx.gl.bindTexture(texture[0], webgl_texture)
+
         for uniform_name, texture_unit in self.uniforms:
             self.program[uniform_name] = texture_unit
 
@@ -203,8 +217,13 @@ class ViewportState(_BaseViewportState):
 
 @dataclass(frozen=True)
 class UniformBufferState(State):
-    name: str
-    binding: int
+    region: UniformBufferRegion
+    binding_index: int | None = None
+
+    sets_state: bool = True
+
+    def set_state(self, ctx: DrawContext) -> None:
+        self.region.bind(binding_index=self.binding_index)
 
 
 @dataclass(frozen=True)

{pyglet-3.0.dev5 → pyglet-3.0.dev6}/pyglet/graphics/buffer.py

@@ -464,6 +464,89 @@ class UniformBufferObject(RingBuffer):
         )
 
 
+class UniformBufferRegion:
+    """UBO region that uploads through a ring-buffered ``UniformBufferObject``.
+
+    The region owns one CPU-side data structure and a set of GPU ranges.
+
+    General practice is to update the data structure, mark it dirty, and then commit when you are done updating
+    for that frame.
+
+    .. warning:: Do not make the CPU-side data dirty after binding/committing during the same frame (for example,
+                 during the ``on_draw`` call), or GPU stalls may occur.
+
+    .. versionadded:: 3.0
+    """
+
+    __slots__ = (
+        "_current_binding",
+        "_current_range",
+        "_dirty",
+        "_next_range_index",
+        "_ranges",
+        "_ubo",
+        "data",
+    )
+
+    def __init__(
+        self,
+        ubo: UniformBufferObject,
+        *,
+        copies_per_resource: int | None = None,
+    ) -> None:
+        self._ubo = ubo
+        self.data = ubo.get_data_structure()
+        self._current_binding: BufferBindingSlice | None = None
+        self._current_range: BufferRange | None = None
+        self._ranges = ubo.reserve_resource_range(copies_per_resource=copies_per_resource)
+        self._next_range_index = 0
+        self._dirty = True
+
+    @property
+    def ubo(self) -> UniformBufferObject:
+        """The underlying ``UniformBufferObject``."""
+        return self._ubo
+
+    @property
+    def dirty(self) -> bool:
+        """Whether the CPU-side data needs to be uploaded before drawing."""
+        return self._dirty
+
+    def __enter__(self) -> ctypes.Structure:
+        return self.data
+
+    def __exit__(self, _exc_type: Any, _exc_val: Any, _exc_tb: Any) -> None:
+        self.mark_dirty()
+
+    def mark_dirty(self) -> None:
+        """Mark the CPU-side data for upload on the next ``bind`` call."""
+        self._dirty = True
+
+    def commit(self) -> None:
+        """Upload dirty CPU-side data to the next writable GPU range."""
+        if not self._dirty:
+            return
+
+        self._current_binding, self._current_range, self._next_range_index = (
+            self._ubo.upload_to_available_binding_from_ranges(
+                self.data,
+                self._ranges,
+                self._next_range_index,
+            )
+        )
+        self._dirty = False
+
+    def bind(self, *, binding_index: int | None = None) -> None:
+        """Upload dirty data if needed, then bind the current GPU range."""
+        self.commit()
+
+        if self._current_binding is None or self._current_range is None:
+            return
+
+        self._ubo.use_range(self._current_range)
+        self._ubo.bind_slice(self._current_binding, binding_index=binding_index)
+
+
 class MappedBufferObject(AbstractBuffer):
     """A GPU buffer that supports map/unmap and range mapping."""