pyglet 3.0.dev9__py3-none-any.whl → 3.0.dev11__py3-none-any.whl

pyglet/__init__.py

@@ -8,6 +8,8 @@ import os
 import sys
 import warnings
 
+IS_DOC_BUILD = os.environ.get("PYGLET_DOC_BUILD") == "1"
+
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Literal, Sequence
 
@@ -18,7 +20,7 @@ if TYPE_CHECKING:
     from typing import Any, Callable, ItemsView, Sized
 
 #: The release version
-version = '3.0.dev9'
+version = '3.0.dev11'
 __version__ = version
 
 MIN_PYTHON_VERSION = 3, 10
@@ -264,6 +266,15 @@ class Options:
 
     .. versionadded:: 2.0.5"""
 
+    osx_displaylink: bool = True
+    """If ``True`` (the default), macOS 14 and later uses ``CADisplayLink`` to schedule window draws.
+
+    Set this to ``False`` before calling :func:`pyglet.app.run` to retain the clock-driven redraw behavior used by
+    earlier pyglet versions. This is useful for applications that need a timer defined frame cadence, such as a
+    deterministic capture pipeline or an application that coordinates drawing with an external scheduler.
+
+    .. versionadded:: 3.0.0"""
+
     dpi_scaling: Literal["platform", "stretch"] = "platform"
     """For 'HiDPI' displays, Window behavior can differ between operating systems. Defaults to `'platform'`.
 
@@ -354,7 +365,7 @@ for _option_name, _type_str in options.__annotations__.items():
 
 
 if (__debug__ is False) or getattr(sys, "frozen", False):
-    options.debug_gl = False
+    options.debug_api = False
 
 
 # Call tracing

pyglet/__init__.pyi

@@ -24,6 +24,8 @@ from . import sprite as sprite
 from . import text as text
 from . import window as window
 
+IS_DOC_BUILD: bool
+
 version: str
 MIN_PYTHON_VERSION: tuple[int, int]
 MIN_PYTHON_VERSION_STR: str
@@ -68,6 +70,7 @@ class Options:
     win32_disable_xinput: bool
     com_mta: bool
     osx_alt_loop: bool
+    osx_displaylink: bool
     dpi_scaling: Literal["platform", "stretch"]
     shader_bind_management: bool
     wayland: bool

pyglet/app/__init__.py

@@ -31,17 +31,17 @@ default policy is to wait until all windows are closed)::
 
 from __future__ import annotations
 
-import platform
 import sys
+import signal
+import platform
 import weakref
 
 import pyglet
 from pyglet import compat_platform
 from pyglet.app.base import EventLoop
 
-_is_pyglet_doc_run = hasattr(sys, "is_pyglet_doc_run") and sys.is_pyglet_doc_run
 
-if _is_pyglet_doc_run:
+if pyglet.IS_DOC_BUILD:
     from pyglet.app.base import PlatformEventLoop
 else:
     if compat_platform == 'darwin':
@@ -51,6 +51,9 @@ else:
         # Use alternate loop only if forced, or using an M1 chip.
         if (platform.machine() == 'arm64' and "M1" in get_chip_model()) or pyglet.options.osx_alt_loop:
             from pyglet.app.cocoa import CocoaAlternateEventLoop as EventLoop
+    elif compat_platform == 'ios':
+        from pyglet.app.ios import IOSEventLoop as EventLoop
+        from pyglet.app.ios import IOSPlatformEventLoop as PlatformEventLoop
     elif compat_platform in ('win32', 'cygwin'):
         from pyglet.app.win32 import Win32EventLoop as PlatformEventLoop
     elif compat_platform == 'linux':
@@ -79,7 +82,11 @@ def run(interval: float | None = 1 / 60) -> None:
 
         pyglet.app.event_loop.run(interval)
 
+    ..note: This convenience function also adds a SIGINT signal handler
+            to automatically call ``pyglet.app.exit`` when this signal
+            is detected.
     """
+    signal.signal(signal.SIGINT, lambda _s, _f: event_loop.exit())
     event_loop.run(interval)
 
 

pyglet/app/base.py

@@ -7,13 +7,12 @@ from abc import ABC, abstractmethod
 from queue import Queue
 from typing import TYPE_CHECKING, Any, Callable
 
-from pyglet import app, clock, event
+from pyglet import app, clock, event, IS_DOC_BUILD
 
 if TYPE_CHECKING:
     from pyglet.event import EventDispatcher
     from pyglet.window import BaseWindow
 
-_is_pyglet_doc_run = hasattr(sys, "is_pyglet_doc_run") and sys.is_pyglet_doc_run
 
 
 class WindowDrawSource(ABC):
@@ -406,7 +405,7 @@ class EventLoop(event.EventDispatcher):
         if len(app.windows) == 0:
             self.exit()
 
-    if _is_pyglet_doc_run:
+    if IS_DOC_BUILD:
         # Events
 
         def on_window_close(self, window: BaseWindow) -> None:

pyglet/app/cocoa.py

@@ -2,13 +2,16 @@ from __future__ import annotations
 
 import signal
 import time
+from typing import TYPE_CHECKING
 
+import pyglet
 from pyglet import app
-from pyglet.app.base import EventLoop, PlatformEventLoop
-from pyglet.libs.darwin import cocoapy, AutoReleasePool, ObjCSubclass, PyObjectEncoding, ObjCInstance, send_super, \
-    ObjCClass, get_selector, set_realtime_thread_policy
+from pyglet.app.base import EventLoop, PlatformEventLoop, WindowDrawSource
+from pyglet.libs.darwin import cocoapy, AutoReleasePool, PyObjectEncoding, ObjCInstance, send_super, \
+    ObjCClass, get_selector, objc_method, set_realtime_thread_policy
 
 NSApplication = cocoapy.ObjCClass('NSApplication')
+NSObject = cocoapy.ObjCClass('NSObject')
 NSMenu = cocoapy.ObjCClass('NSMenu')
 NSMenuItem = cocoapy.ObjCClass('NSMenuItem')
 NSDate = cocoapy.ObjCClass('NSDate')
@@ -17,6 +20,9 @@ NSUserDefaults = cocoapy.ObjCClass('NSUserDefaults')
 NSTimer = cocoapy.ObjCClass('NSTimer')
 NSRunningApplication = cocoapy.ObjCClass('NSRunningApplication')
 
+if TYPE_CHECKING:
+    from pyglet.window.apple.cocoa import CocoaWindow
+
 def add_menu_item(menu, title, action, key):
     with AutoReleasePool():
         title = cocoapy.CFSTR(title)
@@ -54,25 +60,24 @@ def create_menu():
         appMenuItem.release()
 
 
-class _AppDelegate_Implementation:
-    _AppDelegate = ObjCSubclass('NSObject', '_AppDelegate')
+class _AppDelegate(NSObject):
 
-    @_AppDelegate.method(b'@' + PyObjectEncoding)
+    @objc_method(b'@' + PyObjectEncoding)
     def init(self, pyglet_loop):
         objc = ObjCInstance(send_super(self, 'init'))
         self._pyglet_loop = pyglet_loop
         return objc  # objc is self
 
-    @_AppDelegate.method('v')
+    @objc_method('v')
     def updatePyglet_(self):
         self._pyglet_loop.nsapp_step()
 
-    @_AppDelegate.method('v@')
+    @objc_method('v@')
     def applicationWillTerminate_(self, notification):
         self._pyglet_loop.is_running = False
         self._pyglet_loop.has_exit = True
 
-    @_AppDelegate.method('v@')
+    @objc_method('v@')
     def applicationDidFinishLaunching_(self, notification):
         self._pyglet_loop._finished_launching = True
 
@@ -96,38 +101,32 @@ class _AppDelegate_Implementation:
 
         NSApp.activateIgnoringOtherApps_(True)
 
-    @_AppDelegate.method('v@')
+    @objc_method('v@')
     def applicationWillFinishLaunching_(self, notification):
         pass
 
-    @_AppDelegate.method('B')
+    @objc_method('B')
     def applicationSupportsSecureRestorableState_(self):
         return True
 
-_AppDelegate = ObjCClass('_AppDelegate')  # the actual class
-
 class CocoaAlternateEventLoop(EventLoop):
     """This is an alternate loop developed mainly for ARM64 variants of macOS.
-    nextEventMatchingMask_untilDate_inMode_dequeue_ is very broken with ctypes calls. Events eventually stop
-    working properly after X returns. This event loop differs in that it uses the built-in NSApplication event
+
+    nextEventMatchingMask_untilDate_inMode_dequeue_ is very broken with ctypes calls on M1.
+
+    Events eventually stop working properly after X returns. This event loop
+    differs in that it uses the built-in NSApplication event
     loop. We tie our schedule into it via timer.
     """
     def __init__(self):
         super().__init__()
         self.platform_event_loop = None
 
-    def run(self, interval: float | None = 1/60):
-        if interval is None:
-            pass  # do not schedule redraws
-        elif not interval:
-            self.clock.schedule(self._redraw_windows)
-        else:
-            self.clock.schedule_interval(self._redraw_windows, interval)
-
+    def run(self, interval: float | None = 1/60) -> None:
         self.has_exit = False
 
-        from pyglet.window import Window
-        Window._enable_event_queue = False
+        from pyglet.window import Window  # noqa: PLC0415
+        Window._enable_event_queue = False  # noqa: SLF001
 
         # Dispatch pending events
         for window in app.windows:
@@ -135,13 +134,18 @@ class CocoaAlternateEventLoop(EventLoop):
             window.dispatch_pending_events()
 
         self.platform_event_loop = app.platform_event_loop
+        self._schedule_window_draw(interval)
 
         self.dispatch_event('on_enter')
         self.is_running = True
 
-        self.platform_event_loop.nsapp_start(interval or 0)
+        try:
+            self.platform_event_loop.nsapp_start(interval or 0)
+        finally:
+            self._unschedule_window_draw()
+        self._raise_window_draw_exception()
 
-    def exit(self):
+    def exit(self) -> None:
         """Safely exit the event loop at the end of the current iteration.
 
         This method is a thread-safe equivalent for setting
@@ -159,12 +163,52 @@ class CocoaAlternateEventLoop(EventLoop):
             self.platform_event_loop.nsapp_stop()
 
 
+class CocoaWindowDrawSource(WindowDrawSource):
+    """Display driven drawing backed by one CADisplayLink."""
+
+    def __init__(self) -> None:
+        self._active = False
+        self._interval = None
+
+    def start(self, interval: float) -> bool:
+        started_windows = []
+        for window in app.windows:
+            if not window._start_display_link(interval):  # noqa: SLF001
+                for started_window in started_windows:
+                    started_window._stop_display_link()  # noqa: SLF001
+                return False
+            started_windows.append(window)
+
+        self._interval = interval
+        self._active = True
+        return True
+
+    def stop(self) -> None:
+        if not self._active:
+            return
+
+        self._active = False
+        self._interval = None
+        for window in app.windows:
+            window._stop_display_link()  # noqa: SLF001
+
+    def add_window(self, window: CocoaWindow) -> bool:
+        return not self._active or window._start_display_link(self._interval)  # noqa: SLF001
+
+    def remove_window(self, window: CocoaWindow) -> None:
+        window._stop_display_link()  # noqa: SLF001
+
+
 class CocoaPlatformEventLoop(PlatformEventLoop):
 
     def __init__(self):
         super().__init__()
         set_realtime_thread_policy()
         self._timer = None
+        nsview = ObjCClass('NSView')
+        self._display_link_supported = bool(
+            nsview.instancesRespondToSelector_(get_selector('displayLinkWithTarget:selector:'))
+        )
 
         with AutoReleasePool():
             # Prepare the default application.
@@ -198,7 +242,7 @@ class CocoaPlatformEventLoop(PlatformEventLoop):
         signal.signal(signal.SIGINT, term_received)
         signal.signal(signal.SIGTERM, term_received)
 
-    def start(self):
+    def start(self) -> None:
         with AutoReleasePool():
             if not self.NSApp.isRunning() and not self._finished_launching:
                 # finishLaunching should be called only once. However isRunning will not
@@ -207,9 +251,14 @@ class CocoaPlatformEventLoop(PlatformEventLoop):
                 self.NSApp.activateIgnoringOtherApps_(True)
                 self._finished_launching = True
 
-    def nsapp_start(self, interval):
-        """Used only for CocoaAlternateEventLoop"""
-        from pyglet.app import event_loop
+    def create_window_draw_source(self, _event_loop: EventLoop) -> WindowDrawSource | None:
+        if pyglet.options.osx_displaylink and self._display_link_supported:
+            return CocoaWindowDrawSource()
+        return None
+
+    def nsapp_start(self, interval: float) -> None:
+        """Used only for CocoaAlternateEventLoop."""
+        from pyglet.app import event_loop  # noqa: PLC0415
         self._event_loop = event_loop
 
         assert self._timer is None
@@ -219,26 +268,26 @@ class CocoaPlatformEventLoop(PlatformEventLoop):
             self.appdelegate,
             get_selector('updatePyglet:'),
             False,
-            True
+            True,
         )
 
         self.NSApp.run()
 
-    def nsapp_step(self):
-        """Used only for CocoaAlternateEventLoop"""
+    def nsapp_step(self) -> None:
+        """Used only for CocoaAlternateEventLoop."""
         self._event_loop.idle()
         with AutoReleasePool():
             self.dispatch_posted_events()
 
-    def nsapp_stop(self):
-        """Used only for CocoaAlternateEventLoop"""
+    def nsapp_stop(self) -> None:
+        """Used only for CocoaAlternateEventLoop."""
         self.NSApp.stop_(None)
 
         if self._timer:
             self._timer.invalidate()
             self._timer = None
 
-    def step(self, timeout=None):
+    def step(self, timeout: float | None=None) -> bool:  # noqa: ANN201
         with AutoReleasePool():
             self.dispatch_posted_events()
 
@@ -274,10 +323,10 @@ class CocoaPlatformEventLoop(PlatformEventLoop):
 
             return did_time_out
 
-    def stop(self):
+    def stop(self) -> None:
         pass
 
-    def notify(self):
+    def notify(self) -> None:
         with AutoReleasePool():
             notifyEvent = NSEvent.otherEventWithType_location_modifierFlags_timestamp_windowNumber_context_subtype_data1_data2_(
                 cocoapy.NSApplicationDefined, # type

pyglet/app/ios.py

@@ -0,0 +1,168 @@
+"""UIKit app loop integration on iOS."""
+from __future__ import annotations
+
+import os
+
+from pyglet import app
+from pyglet.app.base import EventLoop, PlatformEventLoop, WindowDrawSource
+from pyglet.libs.darwin import get_display_link_dt
+from pyglet.libs.darwin.cocoapy import (
+    CAFrameRateRange,
+    NSRunLoopCommonModes,
+    ObjCClass,
+    ObjCInstance,
+    PyObjectEncoding,
+    get_selector,
+    objc_method,
+    send_super,
+)
+
+_XCTEST_ENVIRONMENT = (
+    "XCTestBundlePath",
+    "XCTestConfigurationFilePath",
+    "XCTestSessionIdentifier",
+)
+
+def _is_xctest() -> bool:
+    return any(name in os.environ for name in _XCTEST_ENVIRONMENT)
+
+NSObject = ObjCClass('NSObject')
+NSRunLoop = ObjCClass('NSRunLoop')
+CADisplayLink = ObjCClass('CADisplayLink')
+
+
+class _PygletIOSDisplayLinkTarget(NSObject):
+
+    @objc_method(b'@' + PyObjectEncoding)
+    def initWithDrawSource_(self, draw_source: IOSDisplayLinkDrawSource) -> ObjCInstance | None:
+        self = ObjCInstance(send_super(self, 'init'))
+        if not self:
+            return None
+        self._draw_source = draw_source
+        return self
+
+    @objc_method('v@')
+    def displayLinkFired_(self, display_link: ObjCInstance) -> None:
+        self._draw_source.tick(display_link)
+
+
+class IOSDisplayLinkDrawSource(WindowDrawSource):
+    """One UIKit display link that paces all pyglet window drawing."""
+
+    def __init__(self, event_loop: IOSEventLoop) -> None:
+        self._event_loop = event_loop
+        self._display_link = None
+        self._target = None
+        self._last_timestamp: float | None = None
+
+    def start(self, interval: float) -> bool:
+        if self._display_link is not None:
+            return True
+
+        self._target = _PygletIOSDisplayLinkTarget.alloc().initWithDrawSource_(self)
+        display_link = CADisplayLink.displayLinkWithTarget_selector_(
+            self._target,
+            get_selector('displayLinkFired:'),
+        )
+        if display_link is None:
+            self._target.release()
+            self._target = None
+            return False
+
+        if interval:
+            frame_rate = 1 / interval
+            if CADisplayLink.instancesRespondToSelector_(get_selector('setPreferredFrameRateRange:')):
+                display_link.setPreferredFrameRateRange_(
+                    CAFrameRateRange(frame_rate, frame_rate, frame_rate),
+                )
+            else:
+                display_link.setPreferredFramesPerSecond_(round(frame_rate))
+
+        self._display_link = display_link
+        self._last_timestamp = None
+        display_link.addToRunLoop_forMode_(NSRunLoop.mainRunLoop(), NSRunLoopCommonModes)
+        return True
+
+    def stop(self) -> None:
+        if self._display_link is not None:
+            self._display_link.invalidate()
+            self._display_link = None
+        if self._target is not None:
+            self._target.release()
+            self._target = None
+        self._last_timestamp = None
+
+    def tick(self, display_link: ObjCInstance) -> None:
+        if self._display_link is None or not self._event_loop.is_running:
+            return
+        self._last_timestamp, dt = get_display_link_dt(display_link, self._last_timestamp)
+        self._event_loop._tick_app(dt)  # noqa: SLF001
+
+class IOSPlatformEventLoop(PlatformEventLoop):
+    """Schedules pyglet work from UIKit's already-running main run loop."""
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    def notify(self) -> None:
+        return None
+
+    def start(self) -> None:
+        self._is_running.set()
+
+    def step(self, timeout: float | None = None) -> None:
+        self.dispatch_posted_events()
+
+    def stop(self) -> None:
+        self._is_running.clear()
+
+    def create_window_draw_source(self, event_loop: EventLoop) -> WindowDrawSource:
+        return IOSDisplayLinkDrawSource(event_loop)
+
+
+class IOSEventLoop(EventLoop):
+    """Event loop similar to what we did for alt macos loop.."""
+
+    def run(self, interval: float | None = 1 / 60) -> None:
+        # Check for XCode environment as it owns the app lifetime and finalizes its embedded
+        # interpreter after the test returns.  It must not receive native
+        # callbacks from a pyglet timer after that point.
+        if _is_xctest():
+            # Tick app once during test to ensure at least one draw.
+            self._tick_app()
+            self.has_exit = True
+            return
+
+        self.has_exit = False
+        from pyglet.window import Window  # noqa: PLC0415
+        Window._enable_event_queue = False # noqa: SLF001
+        for window in app.windows:
+            window.dispatch_pending_events()
+
+        self._interval = interval
+        self.dispatch_event('on_enter')
+        self.is_running = True
+        app.platform_event_loop.start()
+        self._schedule_display_link(interval)
+
+    def _schedule_display_link(self, interval: float | None) -> None:
+        self._window_draw_source = app.platform_event_loop.create_window_draw_source(self)
+        if not self._window_draw_source.start(1 / 60 if interval is None else interval):
+            raise RuntimeError("Unable to create the iOS CADisplayLink.")
+
+    def _tick_app(self, draw_dt: float | None = None) -> None:
+        app.platform_event_loop.dispatch_posted_events()
+        clock_dt = self.clock.update_time()
+        self.clock.call_scheduled_functions(clock_dt)
+        if self._interval is not None:
+            for window in app.windows:
+                self._dispatch_platform_draw(window, clock_dt if draw_dt is None else draw_dt)
+
+    def exit(self) -> None:
+        if not self.is_running:
+            return
+        self.has_exit = True
+        self.is_running = False
+        self._unschedule_window_draw()
+        app.platform_event_loop.stop()
+        self.dispatch_event('on_exit')

pyglet/config/__init__.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, NamedTuple
 
+import pyglet
+
 from pyglet.enums import GraphicsAPI
 
 from .base import SurfaceConfig, UserConfig  # noqa: TC001
@@ -23,7 +25,7 @@ class Config:
 
     __slots__ = 'gl2', 'gles2', 'gles3', 'opengl', 'vulkan', 'webgl'
 
-    def __init__(self):
+    def __init__(self) -> None:  # noqa: D107
         self.opengl: OpenGLUserConfig = OpenGLUserConfig(major_version=3, minor_version=3, api=GraphicsAPI.OPENGL)
         self.gl2: OpenGLUserConfig = OpenGLUserConfig(major_version=2, minor_version=0, api=GraphicsAPI.OPENGL_2)
         self.gles2: OpenGLUserConfig = OpenGLUserConfig(major_version=2, minor_version=0, api=GraphicsAPI.OPENGL_ES_2)
@@ -33,9 +35,15 @@ class Config:
 
 
 def match_surface_config(config: UserConfig, surface: Window) -> SurfaceConfig | None:
-    if isinstance(config, (OpenGLUserConfig, WebGLUserConfig)):
+    if isinstance(config, OpenGLUserConfig):
         from pyglet.config.gl import get_surface_config  # noqa: PLC0415
         return get_surface_config(config, surface)
 
+    if isinstance(config, WebGLUserConfig):
+        if pyglet.compat_platform == 'emscripten':
+            from pyglet.config.gl.webgl import match  # noqa: PLC0415
+            return match(config, surface)
+        return None
+
     msg = f"Matching for '{config.__class__}' is not yet implemented."
     raise NotImplementedError(msg)

pyglet/config/gl/__init__.py

@@ -1,12 +1,21 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
 
 import pyglet
 
 from pyglet.enums import GraphicsAPI
 from pyglet.config.base import UserConfig, SurfaceConfig
 
+if TYPE_CHECKING:
+    from pyglet.window.apple.cocoa import CocoaWindow
+    from pyglet.window.apple.ios import IOSWindow
+    from pyglet.window.headless import HeadlessWindow
+    from pyglet.window.wayland import WaylandWindow
+    from pyglet.window.win32 import Win32Window
+    from pyglet.window.xlib import XlibWindow
+
 
 class GLSurfaceConfig(SurfaceConfig):
     config: OpenGLUserConfig
@@ -98,31 +107,31 @@ class WebGLUserConfig(UserConfig):
         return False
 
 
-def get_surface_config(user_config: UserConfig, surface: pyglet.window.Window) -> SurfaceConfig | None:
+def get_surface_config(user_config: OpenGLUserConfig, surface: pyglet.window.Window) -> SurfaceConfig | None:
 
     if pyglet.options.headless or pyglet.options.wayland:
-        from pyglet.config.gl.egl import match
+        from pyglet.config.gl.egl import match as match_egl  # noqa: PLC0415
 
-        return match(user_config, surface)
+        return match_egl(user_config, cast("HeadlessWindow | WaylandWindow", surface))
 
     if pyglet.compat_platform == "win32":
-        from pyglet.config.gl.windows import match  # noqa: PLC0415
+        from pyglet.config.gl.windows import match as match_windows  # noqa: PLC0415
 
-        return match(user_config, surface)
+        return match_windows(user_config, cast("Win32Window", surface))
 
     if pyglet.compat_platform.startswith("linux"):
-        from pyglet.config.gl.x11 import match  # noqa: PLC0415
+        from pyglet.config.gl.x11 import match as match_x11  # noqa: PLC0415
 
-        return match(user_config, surface)
+        return match_x11(user_config, cast("XlibWindow", surface))
 
     if pyglet.compat_platform == "darwin":
-        from pyglet.config.gl.macos import match  # noqa: PLC0415
+        from pyglet.config.gl.macos import match as match_macos  # noqa: PLC0415
 
-        return match(user_config, surface)
+        return match_macos(user_config, cast("CocoaWindow", surface))
 
-    if pyglet.compat_platform == "emscripten":
-        from pyglet.config.gl.webgl import match  # noqa: PLC0415
+    if pyglet.compat_platform == "ios":
+        from pyglet.config.gl.ios import match as match_ios  # noqa: PLC0415
 
-        return match(user_config, surface)
+        return match_ios(user_config, cast("IOSWindow", surface))
 
     return None