e2D 2.0.0__cp313-cp313-win_amd64.whl → 2.0.2__cp313-cp313-win_amd64.whl

e2D/types.pyi

@@ -0,0 +1,61 @@
+"""
+Type stubs for types module
+Common type definitions for e2D library
+"""
+
+from typing import Union, Sequence
+import numpy as np
+import numpy.typing as npt
+import moderngl
+from .cvectors import Vector2D
+from glfw import _GLFWwindow
+
+# Type alias for vector-like objects - use this for ALL 2D vectors, positions, and sizes
+# Accepts Vector2D instances, tuples (x, y), or lists [x, y]
+VectorType = Union[Vector2D, tuple[int | float, int | float], Sequence[int | float]]
+
+# Color type (RGBA values between 0.0 and 1.0)
+ColorType = tuple[float, float, float, float]
+
+# Numeric types
+Number = int | float
+IntVec2 = tuple[int, int]
+FloatVec2 = tuple[float, float]
+NumVec2 = tuple[Number, Number]
+
+# Array-like types for numpy and buffers
+pArray = list | tuple
+ArrayLike = npt.NDArray[np.float32] | npt.NDArray[np.float64] | npt.NDArray[np.int32]
+
+# Shader and GPU resource types
+ContextType = moderngl.Context
+ProgramType = moderngl.Program
+ComputeShaderType = moderngl.ComputeShader
+BufferType = moderngl.Buffer
+VAOType = moderngl.VertexArray
+TextureType = moderngl.Texture
+
+ProgramAttrType = moderngl.Uniform | moderngl.UniformBlock | moderngl.Attribute | moderngl.Varying
+UniformType = moderngl.Uniform
+UniformBlockType = moderngl.UniformBlock
+
+# Window type
+WindowType = _GLFWwindow
+
+
+__all__ = [
+    'VectorType',
+    'Vector2D',
+    'ColorType',
+    'Number',
+    'IntVec2',
+    'FloatVec2',
+    'NumVec2',
+    'ArrayLike',
+    'ContextType',
+    'ProgramType',
+    'BufferType',
+    'VAOType',
+    'TextureType',
+    'WindowType',
+]

e2D/vectors.py

@@ -3,73 +3,164 @@ High-level Python wrapper for Vector2D with additional utilities
 Provides compatibility layer and convenience functions
 """
 
-try:
-    from .cvectors import (
-        Vector2D,
-        batch_add_inplace,
-        batch_scale_inplace,
-        batch_normalize_inplace,
-        vectors_to_array,
-        array_to_vectors,
-    )
-    _COMPILED = True
-except ImportError:
-    print("WARNING: Compiled cvectors module not found. Please run: python setup.py build_ext --inplace")
-    print("Falling back to pure Python implementation (slower)")
-    _COMPILED = False
-    
-    # Fallback implementation
-    import numpy as np
-    
-    class Vector2D:
-        """Pure Python fallback (much slower than compiled version)"""
-        def __init__(self, x=0.0, y=0.0):
-            self.data = np.array([x, y], dtype=np.float64)
-        
-        @property
-        def x(self):
-            return self.data[0]
-        
-        @x.setter
-        def x(self, value):
-            self.data[0] = value
-        
-        @property
-        def y(self):
-            return self.data[1]
-        
-        @y.setter
-        def y(self, value):
-            self.data[1] = value
-        
-        @property
-        def length(self):
-            return np.linalg.norm(self.data)
+from typing import Any, List, Literal, Protocol, runtime_checkable, TYPE_CHECKING, Sequence, cast
+import numpy as np
+from numpy.typing import NDArray
+
+# Define a protocol that both implementations must follow
+@runtime_checkable
+class Vector2DProtocol(Protocol):
+    """Protocol defining the Vector2D interface for type checking"""
+    x: float
+    y: float
+    
+    def __init__(self, x: float = 0.0, y: float = 0.0) -> None: ...
+    def copy(self) -> "Vector2DProtocol": ...
+    def normalize(self) -> None: ...
+    def __add__(self, other: Any) -> "Vector2DProtocol": ...
+    def __sub__(self, other: Any) -> "Vector2DProtocol": ...
+    def __mul__(self, other: Any) -> "Vector2DProtocol": ...
+    def __getitem__(self, idx: int) -> float: ...
+    def __setitem__(self, idx: int, value: float) -> None: ...
+    def __len__(self) -> int: ...
+    @property
+    def length(self) -> float: ...
+    @property
+    def length_sqrd(self) -> float: ...
+
+# For type checking - define stubs
+if TYPE_CHECKING:
+    # Constructor function for type checking
+    def Vector2D(x: float = 0.0, y: float = 0.0) -> Vector2DProtocol: ...  # noqa: F811
+    
+    # Type stubs for batch operations
+    def batch_add_inplace(vectors: Sequence[Vector2DProtocol], displacement: Vector2DProtocol) -> None: ...
+    def batch_scale_inplace(vectors: Sequence[Vector2DProtocol], scalar: float) -> None: ...
+    def batch_normalize_inplace(vectors: Sequence[Vector2DProtocol]) -> None: ...
+    def vectors_to_array(vectors: Sequence[Vector2DProtocol]) -> NDArray[np.float64]: ...
+    def array_to_vectors(arr: NDArray[np.float64]) -> list[Vector2DProtocol]: ...
+
+# Try to import the optimized Cython version, fall back to pure Python
+_COMPILED = False
+if not TYPE_CHECKING:
+    try:
+        from .cvectors import (  # type: ignore[assignment]
+            Vector2D,
+            batch_add_inplace,
+            batch_scale_inplace,
+            batch_normalize_inplace,
+            vectors_to_array,
+            array_to_vectors,
+        )
+        _COMPILED = True
+    except ImportError:
+        print("WARNING: Compiled cvectors module not found. Please run: python setup.py build_ext --inplace")
+        print("Falling back to pure Python implementation (slower)")
+        _COMPILED = False
         
-        @property
-        def length_sqrd(self):
-            return np.dot(self.data, self.data)
+        # Fallback pure Python implementation
+        class Vector2D:  # type: ignore[no-redef]
+            """Pure Python fallback (much slower than compiled version)"""
+            def __init__(self, x: float = 0.0, y: float = 0.0) -> None:
+                self.data = np.array([x, y], dtype=np.float64)
+            
+            @property
+            def x(self) -> float:
+                return self.data[0]
+            
+            @x.setter
+            def x(self, value: float) -> None:
+                self.data[0] = value
+            
+            @property
+            def y(self) -> float:
+                return self.data[1]
+            
+            @y.setter
+            def y(self, value: float) -> None:
+                self.data[1] = value
+            
+            @property
+            def length(self) -> np.floating:
+                return np.linalg.norm(self.data)
+            
+            @property
+            def length_sqrd(self) -> float:
+                return np.dot(self.data, self.data)
+            
+            def copy(self) -> "Vector2D":
+                return Vector2D(self.x, self.y)
+            
+            def normalize(self) -> None:
+                """Normalize this vector in place"""
+                length = self.length
+                if length > 0:
+                    self.data /= length
+            
+            def __add__(self, other) -> "Vector2D":
+                if isinstance(other, Vector2D):
+                    return Vector2D(self.x + other.x, self.y + other.y)
+                return Vector2D(self.x + other, self.y + other)
+            
+            def __sub__(self, other) -> "Vector2D":
+                if isinstance(other, Vector2D):
+                    return Vector2D(self.x - other.x, self.y - other.y)
+                return Vector2D(self.x - other, self.y - other)
+            
+            def __mul__(self, other) -> "Vector2D":
+                if isinstance(other, Vector2D):
+                    return Vector2D(self.x * other.x, self.y * other.y)
+                return Vector2D(self.x * other, self.y * other)
+            
+            def __getitem__(self, idx) -> float:
+                """Support indexing like a tuple (v[0], v[1])"""
+                if idx == 0:
+                    return self.x
+                elif idx == 1:
+                    return self.y
+                raise IndexError("Vector2D index out of range")
+            
+            def __setitem__(self, idx, value) -> None:
+                """Support setting by index (v[0] = x)"""
+                if idx == 0:
+                    self.x = value
+                elif idx == 1:
+                    self.y = value
+                else:
+                    raise IndexError("Vector2D index out of range")
+            
+            def __len__(self) -> Literal[2]:
+                """Support len(v) -> 2"""
+                return 2
+            
+            def __repr__(self) -> str:
+                return f"Vector2D({self.x}, {self.y})"
         
-        def copy(self):
-            return Vector2D(self.x, self.y)
+        # Fallback batch operations
+        def batch_add_inplace(vectors: Sequence[Vector2D], displacement: Vector2D) -> None:  # type: ignore[misc]
+            """Pure Python fallback for batch add"""
+            for vec in vectors:
+                vec.data += displacement.data  # type: ignore[attr-defined]
         
-        def __add__(self, other):
-            if isinstance(other, Vector2D):
-                return Vector2D(self.x + other.x, self.y + other.y)
-            return Vector2D(self.x + other, self.y + other)
+        def batch_scale_inplace(vectors: Sequence[Vector2D], scalar: float) -> None:  # type: ignore[misc]
+            """Pure Python fallback for batch scale"""
+            for vec in vectors:
+                vec.data *= scalar  # type: ignore[attr-defined]
         
-        def __sub__(self, other):
-            if isinstance(other, Vector2D):
-                return Vector2D(self.x - other.x, self.y - other.y)
-            return Vector2D(self.x - other, self.y - other)
+        def batch_normalize_inplace(vectors: Sequence[Vector2D]) -> None:  # type: ignore[misc]
+            """Pure Python fallback for batch normalize"""
+            for vec in vectors:
+                length = vec.length
+                if length > 0:
+                    vec.data /= length  # type: ignore[attr-defined]
         
-        def __mul__(self, other):
-            if isinstance(other, Vector2D):
-                return Vector2D(self.x * other.x, self.y * other.y)
-            return Vector2D(self.x * other, self.y * other)
+        def vectors_to_array(vectors: Sequence[Vector2D]) -> NDArray[np.float64]:  # type: ignore[misc]
+            """Pure Python fallback for vectors to array"""
+            return np.array([v.data for v in vectors], dtype=np.float64)  # type: ignore[attr-defined]
         
-        def __repr__(self):
-            return f"Vector2D({self.x}, {self.y})"
+        def array_to_vectors(arr: NDArray[np.float64]) -> list[Vector2D]:  # type: ignore[misc]
+            """Pure Python fallback for array to vectors"""
+            return [Vector2D(row[0], row[1]) for row in arr]
 
 
 # Convenience aliases
@@ -129,6 +220,7 @@ __all__ = [
     'batch_normalize_inplace',
     'vectors_to_array',
     'array_to_vectors',
+    '_COMPILED',
 ]
 
 

e2D/vectors.pyi

@@ -0,0 +1,106 @@
+"""
+Type stubs for vectors module
+High-level Python wrapper for Vector2D with additional utilities
+"""
+
+from typing import List, Tuple, Callable
+from .cvectors import Vector2D, batch_add_inplace, batch_scale_inplace, batch_normalize_inplace, vectors_to_array, array_to_vectors
+
+_COMPILED : bool
+# Convenience aliases
+V2 = Vector2D
+Vec2 = Vector2D
+
+# Pre-defined common vectors
+class CommonVectors:
+    """Pre-allocated common vectors (do not modify these!)"""
+    ZERO: Vector2D
+    ONE: Vector2D
+    UP: Vector2D
+    DOWN: Vector2D
+    LEFT: Vector2D
+    RIGHT: Vector2D
+    
+    @staticmethod
+    def zero() -> Vector2D:
+        """Create new zero vector"""
+        ...
+    
+    @staticmethod
+    def one() -> Vector2D:
+        """Create new one vector"""
+        ...
+    
+    @staticmethod
+    def up() -> Vector2D:
+        """Create new up vector"""
+        ...
+    
+    @staticmethod
+    def down() -> Vector2D:
+        """Create new down vector"""
+        ...
+    
+    @staticmethod
+    def left() -> Vector2D:
+        """Create new left vector"""
+        ...
+    
+    @staticmethod
+    def right() -> Vector2D:
+        """Create new right vector"""
+        ...
+
+# Additional utility functions
+def lerp(start: float, end: float, t: float) -> float:
+    """Linear interpolation between two values"""
+    ...
+
+def create_grid(width: int, height: int, spacing: float = 1.0) -> List[Vector2D]:
+    """
+    Create a grid of vectors
+    
+    Args:
+        width: Number of columns
+        height: Number of rows
+        spacing: Distance between points
+    
+    Returns:
+        List of Vector2D objects
+    """
+    ...
+
+def create_circle(radius: float, num_points: int) -> List[Vector2D]:
+    """
+    Create vectors arranged in a circle
+    
+    Args:
+        radius: Circle radius
+        num_points: Number of points
+    
+    Returns:
+        List of Vector2D objects
+    """
+    ...
+
+def benchmark(num_iterations: int = 100000) -> None:
+    """
+    Run a simple benchmark to test vector performance
+    """
+    ...
+
+__all__ = [
+    'Vector2D',
+    'V2',
+    'Vec2',
+    'CommonVectors',
+    'batch_add_inplace',
+    'batch_scale_inplace',
+    'batch_normalize_inplace',
+    'vectors_to_array',
+    'array_to_vectors',
+    'lerp',
+    'create_grid',
+    'create_circle',
+    '_COMPILED',
+]

e2D/winrec.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+from typing import Any, Optional
+import numpy as np
+import cv2
+import threading
+import queue
+import time
+
+
+class WinRec:
+    """
+    Asynchronous screen recorder for ModernGL-based e2D applications.
+    
+    Usage:
+        rootEnv.init_rec(fps=30, draw_on_screen=True, path='output.mp4')
+        # Recording happens automatically in the render loop
+        # F9: Pause/Resume, F10: Restart, F12: Screenshot
+    """
+    
+    def __init__(
+        self,
+        rootEnv: Any,
+        fps: int = 30,
+        draw_on_screen: bool = True,
+        path: str = 'output.mp4'
+    ) -> None:
+        self.rootEnv = rootEnv
+        self.path = path
+        self.fps = fps
+        self.draw_on_screen = draw_on_screen
+        self.is_recording = True  # Recording state (pause/resume)
+        self.screenshot_counter = 0  # Counter for screenshot filenames
+        self.recording_frames = 0  # Frames actually recorded (excludes paused frames)
+        self.pause_start_time: Optional[float] = None  # Track when recording was paused
+        self.total_pause_duration = 0.0  # Cumulative pause time
+        
+        # Get window size
+        width, height = self.rootEnv.window_size
+        
+        # Setup video writer
+        self.video_writer = cv2.VideoWriter(
+            self.path,
+            cv2.VideoWriter_fourcc(*'mp4v'),  # type: ignore
+            self.fps,
+            (width, height)
+        )
+        
+        # Pre-allocate buffers for zero-copy operations
+        self.frame_buffer = np.empty(shape=(height, width, 3), dtype=np.uint8)
+        
+        # Setup async video writing
+        self.frame_queue: queue.Queue = queue.Queue(maxsize=120)  # Buffer up to 4 seconds at 30fps
+        self.running = True
+        
+        # Statistics tracking
+        self.frames_written = 0
+        self.frames_dropped = 0
+        self.write_start_time = time.time()
+        self.last_stat_update = time.time()
+        self.current_write_fps = 0.0
+        
+        self.write_thread = threading.Thread(target=self._write_worker, daemon=False)
+        self.write_thread.start()
+    
+    def _write_worker(self) -> None:
+        """Background thread that writes frames to video file."""
+        while self.running or not self.frame_queue.empty():
+            try:
+                frame = self.frame_queue.get(timeout=0.1)
+                self.video_writer.write(frame)
+                self.frames_written += 1
+                self.frame_queue.task_done()
+                
+                # Update write FPS every second
+                current_time = time.time()
+                if current_time - self.last_stat_update >= 1.0:
+                    elapsed = current_time - self.write_start_time
+                    self.current_write_fps = self.frames_written / elapsed if elapsed > 0 else 0
+                    self.last_stat_update = current_time
+            except queue.Empty:
+                continue
+    
+    def handle_input(self) -> None:
+        """Handle recording control keyboard inputs (F9-F12)."""
+        import glfw
+        from .devices import KeyState
+        
+        # F9: Toggle pause/resume recording
+        if self.rootEnv.keyboard.get_key(glfw.KEY_F9, KeyState.JUST_PRESSED):
+            self.toggle_recording()
+            status = "REC" if self.is_recording else "PAUSED"
+            print(f"[Recording] {status}")
+        
+        # F10: Restart recording (reset all and resume)
+        if self.rootEnv.keyboard.get_key(glfw.KEY_F10, KeyState.JUST_PRESSED):
+            self.restart()
+            print("[Recording] Restarted (buffer cleared, timers reset)")
+        
+        # F12: Take screenshot
+        if self.rootEnv.keyboard.get_key(glfw.KEY_F12, KeyState.JUST_PRESSED):
+            screenshot_path = self.take_screenshot()
+            print(f"[Screenshot] Saved: {screenshot_path}")
+    
+    def update(self) -> None:
+        """Capture frame from ModernGL framebuffer and queue for writing."""
+        # Handle keyboard input first
+        self.handle_input()
+        
+        # Skip frame capture if recording is paused
+        if not self.is_recording:
+            return
+        
+        # Increment recording frame counter
+        self.recording_frames += 1
+        
+        # Read framebuffer from ModernGL context
+        # Note: OpenGL reads bottom-to-top, so we need to flip
+        width, height = self.rootEnv.window_size
+        pixels = self.rootEnv.ctx.screen.read(components=3)
+        
+        # Convert bytes to numpy array and reshape
+        frame = np.frombuffer(pixels, dtype=np.uint8).reshape((height, width, 3))
+        
+        # Flip vertically (OpenGL coordinates are bottom-up)
+        frame = np.flipud(frame)
+        
+        # Convert RGB to BGR for OpenCV
+        cv2.cvtColor(frame, cv2.COLOR_RGB2BGR, dst=self.frame_buffer)
+        
+        # Queue frame copy for async writing (non-blocking)
+        try:
+            self.frame_queue.put_nowait(self.frame_buffer.copy())
+        except queue.Full:
+            self.frames_dropped += 1  # Track dropped frames
+    
+    def get_rec_seconds(self) -> float:
+        """Get recorded time in seconds (excludes paused time)."""
+        return self.recording_frames / self.fps if self.fps > 0 else 0.0
+    
+    def draw(self) -> None:
+        """Draw recording statistics overlay on screen."""
+        if not self.draw_on_screen:
+            return
+        
+        # Calculate statistics
+        buffer_size = self.frame_queue.qsize()
+        buffer_percent = (buffer_size / self.frame_queue.maxsize) * 100
+        buffer_seconds = buffer_size / self.fps if self.fps > 0 else 0
+        
+        # Estimate optimal buffer size based on write performance
+        if self.current_write_fps > 0 and self.fps > 0:
+            write_lag = self.fps / self.current_write_fps
+            estimated_buffer = int(self.fps * 2 * write_lag)  # 2 seconds of lag compensation
+        else:
+            estimated_buffer = self.frame_queue.maxsize
+        
+        # Recording state indicator
+        rec_status = "REC" if self.is_recording else "PAUSED"
+        
+        # Format with fixed width for stable display
+        from .text_renderer import TextStyle, Pivots
+        from .color_defs import WHITE, BLACK
+        
+        row1 = (f"[{rec_status}] RecFrames:{self.recording_frames:>6} | "
+                f"RecTime:{self.get_rec_seconds():>6.2f}s | "
+                f"AppTime:{self.rootEnv.runtime:>6.2f}s")
+        row2 = (f"Buffer:{buffer_size:>3}/{self.frame_queue.maxsize:<3} "
+                f"({buffer_percent:>5.1f}%, {buffer_seconds:>4.1f}s) | "
+                f"WriteFPS:{self.current_write_fps:>5.1f}")
+        row3 = (f"Written:{self.frames_written:>6} | "
+                f"Dropped:{self.frames_dropped:>4} | "
+                f"OptBuf:{estimated_buffer:>3}")
+        row4 = "[F9]Pause/Resume [F10]Restart [F12]Screenshot"
+        
+        # Position in bottom-right corner with spacing
+        win_width, win_height = self.rootEnv.window_size_f
+        x_pos = win_width - 16
+        y_base = win_height - 16
+        line_height = 30  # Approximate line height
+        
+        style = TextStyle(color=WHITE, bg_color=(0.0, 0.0, 0.0, 0.9))
+        
+        # Draw from bottom to top
+        self.rootEnv.print(row4, (x_pos, y_base), style=style, pivot=Pivots.BOTTOM_RIGHT)
+        self.rootEnv.print(row3, (x_pos, y_base - line_height), style=style, pivot=Pivots.BOTTOM_RIGHT)
+        self.rootEnv.print(row2, (x_pos, y_base - line_height * 2), style=style, pivot=Pivots.BOTTOM_RIGHT)
+        self.rootEnv.print(row1, (x_pos, y_base - line_height * 3), style=style, pivot=Pivots.BOTTOM_RIGHT)
+    
+    def pause(self) -> None:
+        """Pause recording (stop capturing frames)."""
+        if self.is_recording:
+            self.is_recording = False
+            self.pause_start_time = time.time()
+    
+    def resume(self) -> None:
+        """Resume recording (continue capturing frames)."""
+        if not self.is_recording and self.pause_start_time is not None:
+            self.total_pause_duration += time.time() - self.pause_start_time
+            self.pause_start_time = None
+        self.is_recording = True
+    
+    def toggle_recording(self) -> None:
+        """Toggle between pause and resume."""
+        if self.is_recording:
+            self.pause()
+        else:
+            self.resume()
+    
+    def restart(self) -> None:
+        """Restart recording: clear buffer, reset all counters and timers, resume recording."""
+        self.clear_buffer()
+        self.recording_frames = 0
+        self.total_pause_duration = 0.0
+        self.pause_start_time = None
+        self.is_recording = True
+    
+    def clear_buffer(self) -> None:
+        """Clear the frame queue and reset write statistics."""
+        # Clear the queue
+        while not self.frame_queue.empty():
+            try:
+                self.frame_queue.get_nowait()
+                self.frame_queue.task_done()
+            except queue.Empty:
+                break
+        
+        # Reset write counters (but keep recording frames)
+        self.frames_written = 0
+        self.frames_dropped = 0
+        self.write_start_time = time.time()
+        self.last_stat_update = time.time()
+        self.current_write_fps = 0.0
+    
+    def take_screenshot(self, filename: Optional[str] = None) -> str:
+        """
+        Save current screen as PNG screenshot.
+        
+        Args:
+            filename: Optional custom filename. If None, auto-generates with counter.
+        
+        Returns:
+            str: Path to saved screenshot
+        """
+        if filename is None:
+            # Auto-generate filename with counter
+            base_path = self.path.rsplit('.', 1)[0]  # Remove .mp4 extension
+            filename = f"{base_path}_screenshot_{self.screenshot_counter:04d}.png"
+            self.screenshot_counter += 1
+        
+        # Capture current screen from ModernGL
+        width, height = self.rootEnv.window_size
+        pixels = self.rootEnv.ctx.screen.read(components=3)
+        
+        # Convert bytes to numpy array and reshape
+        frame = np.frombuffer(pixels, dtype=np.uint8).reshape((height, width, 3))
+        
+        # Flip vertically (OpenGL coordinates are bottom-up)
+        frame = np.flipud(frame)
+        
+        # Convert RGB to BGR for OpenCV
+        screenshot_buffer = np.empty(shape=(height, width, 3), dtype=np.uint8)
+        cv2.cvtColor(frame, cv2.COLOR_RGB2BGR, dst=screenshot_buffer)
+        
+        # Save as PNG
+        cv2.imwrite(filename, screenshot_buffer)
+        return filename
+    
+    def quit(self) -> None:
+        """Stop recording and release resources."""
+        # Stop accepting new frames and wait for queue to flush
+        self.running = False
+        self.frame_queue.join()  # Wait for all queued frames to be written
+        self.write_thread.join(timeout=5.0)  # Wait for thread to finish
+        self.video_writer.release()
+        print(f"[Recording] Saved {self.frames_written} frames to {self.path}")