pyglet 2.1.8__tar.gz → 2.1.10__tar.gz

{pyglet-2.1.8 → pyglet-2.1.10}/.github/workflows/unittests.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ '3.8', '3.9', '3.10', '3.11', '3.12', 'pypy-3.10' ]
+        python-version: [ '3.9', '3.10', '3.11', '3.12', '3.13', '3.14', 'pypy-3.10' ]
     name: Python ${{ matrix.python-version }} ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -28,7 +28,7 @@ jobs:
     runs-on: macos-latest
     strategy:
       matrix:
-        python-version: [ '3.10', '3.11', '3.12' ]
+        python-version: [ '3.10', '3.11', '3.12', '3.13', '3.14']
     name: Python ${{ matrix.python-version }} OSX
     steps:
       - uses: actions/checkout@v4
@@ -47,7 +47,7 @@ jobs:
     runs-on: windows-latest
     strategy:
       matrix:
-        python-version: [ '3.8', '3.9', '3.10', '3.11', '3.12' ]
+        python-version: [ '3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
     name: Python ${{ matrix.python-version }} Windows
     steps:
       - uses: actions/checkout@v4

{pyglet-2.1.8 → pyglet-2.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyglet
-Version: 2.1.8
+Version: 2.1.10
 Summary: pyglet is a cross-platform games and multimedia package.
 Author-email: Alex Holkner & contributors <Alex.Holkner@gmail.com>
 Requires-Python: >=3.8

{pyglet-2.1.8 → pyglet-2.1.10}/RELEASE_NOTES

@@ -1,3 +1,35 @@
+pyglet 2.1.10
+
+Changes
+-------
+media: Add support for FFmpeg 8.0 (#1365)
+window: Update default dpi_scaling option to "platform". (#1383)
+window: Convert the Window event queue to a deque. (#1362)
+input.evdev: Do not attempt to reuse Controller instances on re-connect, as naming conflicts can occur.
+
+Bugfixes
+--------
+text: fix typing of Label.__init__'s align argument. (#1361)
+text: Update the passed args for attributed text. (#1379)
+shader: Fixed number of elements for GL_FLOAT_MAT3 (9, not 6) in pyglet.graphics.shader._uniform_setters. (#1364)
+
+
+pyglet 2.1.9
+
+Changes
+-------
+docs: Improve missing or underdeveloped math doc (#1295)
+input: Add new Controller properties for polling - Controller.dpad, Controller.leftanalog, Controller.rightanalog Vec2s.
+
+
+Bugfixes
+-------
+input.linux.evdev: Add support for the SYN_DROPPED event, to prevent "stuck" controls when events are lost.
+input.linux.evdev: Implement missing EvdevDevice.poll method.
+graphics.shaders: Fix attribute pointer issue for integers. (#1351)
+window.headless: Add missing abstract methods to HeadlessScreen (#1350)
+
+
 pyglet 2.1.8
 
 Changes

{pyglet-2.1.8 → pyglet-2.1.10}/examples/dpi_scaled_window.py

@@ -1,7 +1,5 @@
 import pyglet
-
-pyglet.options["debug_gl"] = False
-pyglet.options.dpi_scaling = "scaled"
+pyglet.options.debug_gl = False
 
 window = pyglet.window.Window(800, 600, caption="DPI Test", resizable=True)
 batch = pyglet.graphics.Batch()
@@ -31,8 +29,7 @@ labels = [hello_label, mouse_enter_label, mouse_leave_label, mouse_motion_label,
 dinosaur = pyglet.resource.animation("programming_guide/dinosaur.gif")
 
 sprite = pyglet.sprite.Sprite(dinosaur, x=100, y=140, batch=batch)
-if pyglet.options.dpi_scaling != "real":
-    sprite.scale = window.scale
+sprite.scale = window.scale
 
 
 @window.event
@@ -99,10 +96,9 @@ def on_scale(scale, dpi):
     print("Window Size:", window.get_size())
     print("Window Scale Ratio:", window.scale)
     print("Window Frame Buffer Size:", window.get_framebuffer_size())
-    if pyglet.options.dpi_scaling != "real":
-        for label in labels:
-            label.dpi = dpi
-        sprite.scale = window.scale
+    for label in labels:
+        label.dpi = dpi
+    sprite.scale = window.scale
 
 
 pyglet.app.run()

{pyglet-2.1.8 → pyglet-2.1.10}/pyglet/__init__.py

@@ -15,7 +15,7 @@ if TYPE_CHECKING:
     from typing import Any, Callable, ItemsView, Sized
 
 #: The release version
-version = '2.1.8'
+version = '2.1.10'
 __version__ = version
 
 MIN_PYTHON_VERSION = 3, 8
@@ -255,8 +255,8 @@ class Options:
 
     .. versionadded:: 2.0.5"""
 
-    dpi_scaling: Literal["real", "scaled", "stretch", "platform"] = "real"
-    """For 'HiDPI' displays, Window behavior can differ between operating systems. Defaults to `'real'`.
+    dpi_scaling: Literal["real", "scaled", "stretch", "platform"] = "platform"
+    """For 'HiDPI' displays, Window behavior can differ between operating systems. Defaults to `'platform'`.
 
     The current options are an attempt to create consistent behavior across all of the operating systems.
 

{pyglet-2.1.8 → pyglet-2.1.10}/pyglet/app/cocoa.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import signal
 import time
 

{pyglet-2.1.8 → pyglet-2.1.10}/pyglet/display/headless.py

@@ -1,3 +1,7 @@
+from __future__ import annotations
+
+from typing import Literal
+
 import pyglet
 import warnings
 
@@ -69,3 +73,10 @@ class HeadlessScreen(Screen):
 
     def restore_mode(self):
         pass
+
+    def get_display_id(self) -> str | int:
+        # No real unique ID is available, just hash together the properties.
+        return hash((self.x, self.y, self.width, self.height))
+
+    def get_monitor_name(self) -> str | Literal["Unknown"]:
+        return "Headless"

{pyglet-2.1.8 → pyglet-2.1.10}/pyglet/graphics/shader.py

@@ -58,6 +58,7 @@ from pyglet.gl.gl import (
     glUnmapBuffer,
     glUseProgram,
     glVertexAttribDivisor,
+    glVertexAttribIPointer,
     glVertexAttribPointer,
 )
 from pyglet.graphics.vertexbuffer import AttributeBufferObject, BufferObject
@@ -158,7 +159,7 @@ _uniform_setters: dict[int, tuple[GLDataType, GLFunc, GLFunc, int]] = {
     gl.GL_UNSIGNED_INT_SAMPLER_3D: (gl.GLint, gl.glUniform1iv, gl.glProgramUniform1iv, 1),
 
     gl.GL_FLOAT_MAT2: (gl.GLfloat, gl.glUniformMatrix2fv, gl.glProgramUniformMatrix2fv, 4),
-    gl.GL_FLOAT_MAT3: (gl.GLfloat, gl.glUniformMatrix3fv, gl.glProgramUniformMatrix3fv, 6),
+    gl.GL_FLOAT_MAT3: (gl.GLfloat, gl.glUniformMatrix3fv, gl.glProgramUniformMatrix3fv, 9),
     gl.GL_FLOAT_MAT4: (gl.GLfloat, gl.glUniformMatrix4fv, gl.glProgramUniformMatrix4fv, 16),
 
     # TODO: test/implement these:
@@ -257,6 +258,9 @@ class Attribute:
         self.element_size = sizeof(self.c_type)
         self.stride = count * self.element_size
 
+        self._is_int = gl_type in (gl.GL_INT, gl.GL_SHORT, gl.GL_BYTE, gl.GL_UNSIGNED_INT,
+                                   gl.GL_UNSIGNED_SHORT, gl.GL_UNSIGNED_BYTE) and self.normalize is False
+
     def enable(self) -> None:
         """Enable the attribute."""
         glEnableVertexAttribArray(self.location)
@@ -271,7 +275,10 @@ class Attribute:
                 Pointer offset to the currently bound buffer for this attribute.
 
         """
-        glVertexAttribPointer(self.location, self.count, self.gl_type, self.normalize, self.stride, ptr)
+        if self._is_int:
+            glVertexAttribIPointer(self.location, self.count, self.gl_type, self.stride, ptr)
+        else:
+            glVertexAttribPointer(self.location, self.count, self.gl_type, self.normalize, self.stride, ptr)
 
     def set_divisor(self) -> None:
         glVertexAttribDivisor(self.location, 1)

{pyglet-2.1.8 → pyglet-2.1.10}/pyglet/input/base.py

@@ -520,6 +520,7 @@ class Controller(EventDispatcher):
         #: The unique guid for this Device
         self.guid: str = mapping.get('guid')
 
+        # Pollable
         self.a: bool = False
         self.b: bool = False
         self.x: bool = False
@@ -534,6 +535,10 @@ class Controller(EventDispatcher):
 
         self.lefttrigger: float = 0.0
         self.righttrigger: float = 0.0
+        self.dpad: Vec2 = Vec2()
+        self.leftanalog: Vec2 = Vec2()
+        self.rightanalog: Vec2 = Vec2()
+
         self.leftx: float = 0.0
         self.lefty: float = 0.0
         self.rightx: float = 0.0
@@ -617,12 +622,14 @@ class Controller(EventDispatcher):
             @control.event
             def on_change(value):
                 self.dpady = round(value * scale + bias) * sign    # normalized
+                self.dpad = Vec2(self.dpadx, self.dpady)
                 self.dispatch_event('on_dpad_motion', self, Vec2(self.dpadx, self.dpady))
 
         elif axis_name in ("dpleft", "dpright"):
             @control.event
             def on_change(value):
                 self.dpadx = round(value * scale + bias) * sign     # normalized
+                self.dpad = Vec2(self.dpadx, self.dpady)
                 self.dispatch_event('on_dpad_motion', self, Vec2(self.dpadx, self.dpady))
 
         elif axis_name in ("lefttrigger", "righttrigger"):
@@ -637,14 +644,16 @@ class Controller(EventDispatcher):
             def on_change(value):
                 normalized_value = value * scale + bias
                 setattr(self, axis_name, normalized_value)
-                self.dispatch_event('on_stick_motion', self, "leftstick", Vec2(self.leftx, -self.lefty))
+                self.left_analog = Vec2(self.leftx, -self.lefty)
+                self.dispatch_event('on_stick_motion', self, "leftstick", self.left_analog)
 
         elif axis_name in ("rightx", "righty"):
             @control.event
             def on_change(value):
                 normalized_value = value * scale + bias
                 setattr(self, axis_name, normalized_value)
-                self.dispatch_event('on_stick_motion', self, "rightstick", Vec2(self.rightx, -self.righty))
+                self.right_analog = Vec2(self.rightx, -self.righty)
+                self.dispatch_event('on_stick_motion', self, "rightstick", self.right_analog)
 
     def _bind_button_control(self, relation: Relation, control: Button, button_name: str) -> None:
         if button_name in ("dpleft", "dpright", "dpup", "dpdown"):
@@ -655,7 +664,8 @@ class Controller(EventDispatcher):
             def on_change(value):
                 target, bias = defaults[button_name]
                 setattr(self, target, bias * value)
-                self.dispatch_event('on_dpad_motion', self, Vec2(self.dpadx, self.dpady))
+                self.dpad = Vec2(self.dpadx, self.dpady)
+                self.dispatch_event('on_dpad_motion', self, self.dpad)
         else:
             @control.event
             def on_change(value):
@@ -681,7 +691,7 @@ class Controller(EventDispatcher):
         @control.event
         def on_change(value):
             vector = _input_map.get(value // _scale, Vec2(0.0, 0.0))
-            self.dpadx, self.dpady = vector
+            self.dpad = vector
             self.dispatch_event('on_dpad_motion', self, vector)
 
     def _initialize_controls(self) -> None:

{pyglet-2.1.8 → pyglet-2.1.10}/pyglet/input/linux/evdev.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import os
 import time
 import ctypes
+import select
 import warnings
 import threading
 
@@ -11,6 +12,7 @@ from ctypes import c_int16 as _s16
 from ctypes import c_uint32 as _u32
 from ctypes import c_int32 as _s32
 from ctypes import c_int64 as _s64
+from ctypes import c_byte as _c_byte
 
 import pyglet
 
@@ -31,6 +33,26 @@ except ImportError:
         return c.read(fd, buffers, 3072)
 
 
+KeyMaxArray = _c_byte * (KEY_MAX // 8 + 1)
+
+
+class _EvdevInfo:
+    event_type: int
+    event_code: int
+
+
+class EvdevButton(Button, _EvdevInfo):
+    pass
+
+
+class EvdevAbsoluteAxis(AbsoluteAxis, _EvdevInfo):
+    pass
+
+
+class EvdevRelativeAxis(RelativeAxis, _EvdevInfo):
+    pass
+
+
 # Structures from /linux/blob/master/include/uapi/linux/input.h
 
 class Timeval(ctypes.Structure):
@@ -158,11 +180,13 @@ class FFEvent(ctypes.Structure):
     )
 
 
+# Helper "macros" for file io:
 EVIOCGVERSION = _IOR('E', 0x01, ctypes.c_int)
 EVIOCGID = _IOR('E', 0x02, InputID)
 EVIOCGNAME = _IOR_str('E', 0x06)
 EVIOCGPHYS = _IOR_str('E', 0x07)
 EVIOCGUNIQ = _IOR_str('E', 0x08)
+EVIOCGKEY = _IOR_len('E', 0x18)
 EVIOCSFF = _IOW('E', 0x80, FFEvent)
 
 
@@ -170,9 +194,13 @@ def EVIOCGBIT(fileno, ev, buffer):
     return _IOR_len('E', 0x20 + ev)(fileno, buffer)
 
 
-def EVIOCGABS(fileno, abs):
-    buffer = InputABSInfo()
-    return _IOR_len('E', 0x40 + abs)(fileno, buffer)
+def EVIOCGABS(fileno, ev, buffer=InputABSInfo()):
+    return _IOR_len('E', 0x40 + ev)(fileno, buffer)
+
+
+def get_key_state(fileno, event_code, buffer=KeyMaxArray()):
+    buffer = EVIOCGKEY(fileno, buffer)
+    return bool(buffer[event_code // 8] & (1 << (event_code % 8)))
 
 
 def get_set_bits(bytestring):
@@ -217,18 +245,16 @@ def _create_control(fileno, event_type, event_code):
         value = absinfo.value
         minimum = absinfo.minimum
         maximum = absinfo.maximum
-        control = AbsoluteAxis(name, minimum, maximum, raw_name)
+        control = EvdevAbsoluteAxis(name, minimum, maximum, raw_name, inverted=name == 'hat_y')
         control.value = value
-        if name == 'hat_y':
-            control.inverted = True
     elif event_type == EV_REL:
         raw_name = rel_raw_names.get(event_code, f'EV_REL({event_code:x})')
         name = _rel_names.get(event_code)
-        control = RelativeAxis(name, raw_name)
+        control = EvdevRelativeAxis(name, raw_name)
     elif event_type == EV_KEY:
         raw_name = key_raw_names.get(event_code, f'EV_KEY({event_code:x})')
         name = None
-        control = Button(name, raw_name)
+        control = EvdevButton(name, raw_name)
     else:
         return None
     control.event_type = event_type
@@ -248,7 +274,8 @@ event_types = {
 
 
 class EvdevDevice(XlibSelectDevice, Device):
-    _fileno = None
+    _fileno: int | None
+    _poll: "select.poll | None"
 
     def __init__(self, display, filename):
         self._filename = filename
@@ -301,11 +328,14 @@ class EvdevDevice(XlibSelectDevice, Device):
                         self.control_map[(event_type, event_code)] = control
                         self.controls.append(control)
 
-        self.controls.sort(key=lambda c: c.event_code)
+        self.controls.sort(key=lambda ctrl: ctrl.event_code)
         os.close(fileno)
 
+        self._poll = select.poll()
         self._event_size = ctypes.sizeof(InputEvent)
         self._event_buffer = (InputEvent * 64)()
+        self._syn_dropped = False
+        self._event_queue = []
 
         super().__init__(display, name)
 
@@ -321,6 +351,7 @@ class EvdevDevice(XlibSelectDevice, Device):
     def open(self, window=None, exclusive=False):
         try:
             self._fileno = os.open(self._filename, os.O_RDWR | os.O_NONBLOCK)
+            self._poll.register(self._fileno, select.POLLIN | select.POLLPRI)
         except OSError as e:
             raise DeviceOpenException(e)
 
@@ -333,6 +364,9 @@ class EvdevDevice(XlibSelectDevice, Device):
         if not self._fileno:
             return
 
+        if self._poll:
+            self._poll.unregister(self._fileno)
+
         pyglet.app.platform_event_loop.select_devices.remove(self)
         os.close(self._fileno)
         self._fileno = None
@@ -340,6 +374,20 @@ class EvdevDevice(XlibSelectDevice, Device):
     def get_controls(self):
         return self.controls
 
+    def _resync_control_state(self):
+        """Manually resync all Control state.
+
+        This method queries and resets the state of each Control using the appropriate
+        ioctl calls. If this causes the Control value to change, the associated events
+        will be dispatched. This is a somewhat expensive operation, but it is necessary
+        to perform in some cases (such as when a SYN_DROPPED event is received).
+        """
+        for control in self.control_map.values():
+            if isinstance(control, EvdevButton):
+                control.value = get_key_state(self._fileno, control.event_code)
+            if isinstance(control, EvdevAbsoluteAxis):
+                control.value = EVIOCGABS(self._fileno, control.event_code).value
+
     # Force Feedback methods
 
     def ff_upload_effect(self, structure):
@@ -351,25 +399,51 @@ class EvdevDevice(XlibSelectDevice, Device):
         return self._fileno
 
     def poll(self):
-        return False
+        return True if self._poll.poll(0) else False
 
     def select(self):
-        if not self._fileno:
-            return
-
+        """When the file descriptor is ready, read and process InputEvents.
+
+        This method has the following behavior:
+        - Read and queue all incoming input events.
+        - When a SYN_REPORT event is received, dispatch all queued events.
+        - If a SYN_DROPPED event is received, set a flag. When the next
+          SYN_REPORT event appears, drop all queued events & manually resync
+          all Control state.
+        """
         try:
             bytes_read = _readv(self._fileno, self._event_buffer)
+            n_events = bytes_read // self._event_size
         except OSError:
             self.close()
             return
 
-        n_events = bytes_read // self._event_size
-
         for event in self._event_buffer[:n_events]:
-            try:
-                self.control_map[(event.type, event.code)].value = event.value
-            except KeyError:
-                pass
+
+            # Mark the current chain of events as invalid and continue:
+            if (event.type, event.code) == (EV_SYN, SYN_DROPPED):
+                self._syn_dropped = True
+                continue
+
+            # Dispatch queued events when SYN_REPORT comes in:
+            if (event.type, event.code) == (EV_SYN, SYN_REPORT):
+
+                # Unless a SYN_DROPPED event has been received,
+                # in which case discard all queued events and resync:
+                if self._syn_dropped:
+                    self._event_queue.clear()
+                    self._syn_dropped = False
+                    self._resync_control_state()
+
+                # Dispatch all queued events, then clear the queue:
+                for queued_event in self._event_queue:
+                    if control := self.control_map.get((queued_event.type, queued_event.code)):
+                        control.value = queued_event.value
+                self._event_queue.clear()
+
+            # This is not a SYN_REPORT or SYN_DROPPED event, so it is probably
+            # an input event. Queue it until the next SYN_REPORT event comes in:
+            self._event_queue.append(event)
 
 
 class FFController(Controller):
@@ -467,10 +541,9 @@ class EvdevControllerManager(ControllerManager, XlibSelectDevice):
         else:
             return  # No device could be created
 
-        # Reuse existing controller instance if it exists, or create a new one:
-        if controller := self._controllers.get(name, _create_controller(device)):
+        if controller := _create_controller(device):
             self._controllers[name] = controller
-            # Dispatch event in main thread:
+            # Post the event in the main thread:
             self.post_event('on_connect', controller)
 
     def select(self):
@@ -486,6 +559,7 @@ class EvdevControllerManager(ControllerManager, XlibSelectDevice):
 
         for name in disappeared:
             if controller := self._controllers.get(name):
+                del self._controllers[name]
                 self.dispatch_event('on_disconnect', controller)
 
     def get_controllers(self) -> list[Controller]:
@@ -551,8 +625,8 @@ def _detect_controller_mapping(device):
                 ABS_Z: 'lefttrigger', ABS_RZ: 'righttrigger',
                 ABS_X: 'leftx', ABS_Y: 'lefty', ABS_RX: 'rightx', ABS_RY: 'righty'}
 
-    button_controls = [control for control in device.controls if isinstance(control, Button)]
-    axis_controls = [control for control in device.controls if isinstance(control, AbsoluteAxis)]
+    button_controls = [control for control in device.controls if isinstance(control, EvdevButton)]
+    axis_controls = [control for control in device.controls if isinstance(control, EvdevAbsoluteAxis)]
     hat_controls = [control for control in device.controls if control.name in ('hat_x', 'hat_y')]
 
     for i, control in enumerate(button_controls):

{pyglet-2.1.8 → pyglet-2.1.10}/pyglet/input/linux/evdev_constants.py

@@ -1,4 +1,4 @@
-"""Event constants from /usr/include/linux/input.h """
+"""Event constants from /usr/include/linux/input-event-codes.h"""
 
 EV_SYN = 0x00
 EV_KEY = 0x01
@@ -17,6 +17,7 @@ EV_MAX = 0x1f
 
 SYN_REPORT = 0
 SYN_CONFIG = 1
+SYN_DROPPED = 3
 
 # Keys and buttons
 

{pyglet-2.1.8 → pyglet-2.1.10}/pyglet/input/win32/xinput.py

@@ -575,14 +575,16 @@ class XInputController(Controller):
             def on_change(value):
                 normalized_value = value * scale + bias
                 setattr(self, name, normalized_value)
-                self.dispatch_event('on_stick_motion', self, "leftstick", Vec2(self.leftx, self.lefty))
+                self.leftanalog = Vec2(self.leftx, self.lefty)
+                self.dispatch_event('on_stick_motion', self, "leftstick", self.leftanalog)
 
         elif name in ("rightx", "righty"):
             @control.event
             def on_change(value):
                 normalized_value = value * scale + bias
                 setattr(self, name, normalized_value)
-                self.dispatch_event('on_stick_motion', self, "rightstick", Vec2(self.rightx, self.righty))
+                self.rightanalog = Vec2(self.rightx, self.righty)
+                self.dispatch_event('on_stick_motion', self, "rightstick", self.rightanalog)
 
     def _add_button(self, control, name):
 
@@ -592,7 +594,8 @@ class XInputController(Controller):
                 target, bias = {'dpleft': ('dpadx', -1.0), 'dpright': ('dpadx', 1.0),
                                 'dpdown': ('dpady', -1.0), 'dpup': ('dpady', 1.0)}[name]
                 setattr(self, target, bias * value)
-                self.dispatch_event('on_dpad_motion', self, Vec2(self.dpadx, self.dpady))
+                self.dpad = Vec2(self.dpadx, self.dpady)
+                self.dispatch_event('on_dpad_motion', self, self.dpad)
         else:
             @control.event
             def on_change(value):

{pyglet-2.1.8 → pyglet-2.1.10}/pyglet/libs/ioctl.py

@@ -41,7 +41,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from ctypes import Structure, c_int, c_uint
     from typing import Callable, Union
-    c_data = Union[type[Structure], c_int, c_uint]
+    c_data = type[Structure] | type[c_int] | type[c_uint]
 
 
 _IOC_NRBITS = 8
@@ -64,7 +64,7 @@ _IOC_READ = 2
 # 'code' instead of 'type' to indicate the ioctl "magic number" ('H', 'E', etc.).
 
 
-def _IOC(io_dir: _IOC_NONE | _IOC_READ | _IOC_WRITE, code: int, nr: int, size: int) -> int:
+def _IOC(io_dir: Union[_IOC_NONE, _IOC_READ, _IOC_WRITE], code: int, nr: int, size: int) -> int:
     return (io_dir << _IOC_DIRSHIFT) | (code << _IOC_TYPESHIFT) | (nr << _IOC_NRSHIFT) | (size << _IOC_SIZESHIFT)
 
 

{pyglet-2.1.8 → pyglet-2.1.10}/pyglet/math.py

@@ -1387,7 +1387,10 @@ class Mat4(_typing.NamedTuple):
 
 
 class Quaternion(_typing.NamedTuple):
-    """Quaternion."""
+    """Quaternion.
+
+    Quaternions are 4-dimensional complex numbers, useful for describing 3D rotations.
+    """
 
     w: float = 1.0
     x: float = 0.0
@@ -1403,6 +1406,8 @@ class Quaternion(_typing.NamedTuple):
         raise NotImplementedError
 
     def to_mat4(self) -> Mat4:
+        """Calculate a 4x4 transform matrix which applies a rotation."""
+
         w = self.w
         x = self.x
         y = self.y
@@ -1428,6 +1433,8 @@ class Quaternion(_typing.NamedTuple):
         return Mat4(a, b, c, 0.0, e, f, g, 0.0, i, j, k, 0.0, 0.0, 0.0, 0.0, 1.0)
 
     def to_mat3(self) -> Mat3:
+        """Create a 3x3 rotation matrix."""
+
         w = self.w
         x = self.x
         y = self.y
@@ -1453,21 +1460,34 @@ class Quaternion(_typing.NamedTuple):
         return Mat3(*(a, b, c, e, f, g, i, j, k))
 
     def length(self) -> float:
-        """Calculate the length of the Quaternion.
-
-        The distance between the coordinates and the origin.
-        """
+        """Calculate the length of the quaternion from the origin."""
         return _math.sqrt(self.w**2 + self.x**2 + self.y**2 + self.z**2)
 
     def conjugate(self) -> Quaternion:
+        """Calculate the conjugate of this quaternion.
+
+        This operation:
+        #. leaves the :py:attr:`.w` component alone
+        #. inverts the sign of the :py:attr:`.x`, :py:attr:`.y`, and :py:attr:`.z` components
+
+        """
         return Quaternion(self.w, -self.x, -self.y, -self.z)
 
     def dot(self, other: Quaternion) -> float:
+        """Calculate the dot product with another quaternion."""
         a, b, c, d = self
         e, f, g, h = other
         return a * e + b * f + c * g + d * h
 
     def normalize(self) -> Quaternion:
+        """Calculate a unit quaternion from the instance.
+
+        The returned quaternion will be a scaled-down version
+        of the instance which has:
+
+        * a length of ``1``
+        * the same relative of its components
+        """
         m = self.length()
         if m == 0:
             return self