sonolus.py 0.3.1__py3-none-any.whl → 0.3.3__py3-none-any.whl

sonolus/script/stream.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
+from math import inf
 from typing import cast, dataclass_transform
 
-from sonolus.backend.ir import IRExpr, IRInstr, IRPureInstr, IRConst
+from sonolus.backend.ir import IRConst, IRExpr, IRInstr, IRPureInstr
 from sonolus.backend.mode import Mode
 from sonolus.backend.ops import Op
 from sonolus.script.internal.context import ctx
@@ -14,6 +15,7 @@ from sonolus.script.internal.value import BackingValue, Value
 from sonolus.script.iterator import SonolusIterator
 from sonolus.script.num import Num
 from sonolus.script.record import Record
+from sonolus.script.runtime import prev_time, time
 from sonolus.script.values import sizeof
 
 
@@ -174,10 +176,11 @@ class _SparseStreamBacking(BackingValue):
         )
 
 
-class Stream[T](Record, BackingValue):
+class Stream[T](Record):
     """Represents a stream.
 
-    Most users should use `@stream` to declare streams and stream groups rather than using this class directly.
+    Most users should use [`@streams`][sonolus.script.stream.streams] to declare streams and stream groups rather than
+    using this class directly.
 
     If used directly, it is important that streams do not overlap. No other streams should have an offset in
     `range(self.offset, self.offset + max(1, sizeof(self.element_type())))`, or they will overlap and interfere
@@ -248,6 +251,12 @@ class Stream[T](Record, BackingValue):
         _check_can_read_stream()
         return _stream_get_next_key(self.offset, key)
 
+    def next_key_or_default(self, key: int | float, default: int | float) -> int:
+        """Get the next key, or the default value if there is no next key."""
+        _check_can_read_stream()
+        next_key = self.next_key(key)
+        return next_key if next_key > key else default
+
     def previous_key(self, key: int | float) -> int:
         """Get the previous key, or the key unchanged if it is the first key or the stream is empty.
 
@@ -256,6 +265,12 @@ class Stream[T](Record, BackingValue):
         _check_can_read_stream()
         return _stream_get_previous_key(self.offset, key)
 
+    def previous_key_or_default(self, key: int | float, default: int | float) -> int:
+        """Get the previous key, or the default value if there is no previous key."""
+        _check_can_read_stream()
+        previous_key = self.previous_key(key)
+        return previous_key if previous_key < key else default
+
     def has_next_key(self, key: int | float) -> bool:
         """Check if there is a next key after the given key in the stream."""
         _check_can_read_stream()
@@ -302,6 +317,14 @@ class Stream[T](Record, BackingValue):
         _check_can_read_stream()
         return self[self.next_key_inclusive(key)]
 
+    def get_previous_inclusive(self, key: int | float) -> T:
+        """Get the value corresponding to the previous key, or the value at the given key if it is in the stream.
+
+        Equivalent to `self[self.previous_key_inclusive(key)]`.
+        """
+        _check_can_read_stream()
+        return self[self.previous_key_inclusive(key)]
+
     def iter_items_from(self, start: int | float, /) -> SonolusIterator[tuple[int | float, T]]:
         """Iterate over the items in the stream in ascending order starting from the given key.
 
@@ -317,6 +340,22 @@ class Stream[T](Record, BackingValue):
         _check_can_read_stream()
         return _StreamAscIterator(self, self.next_key_inclusive(start))
 
+    def iter_items_since_previous_frame(self) -> SonolusIterator[tuple[int | float, T]]:
+        """Iterate over the items in the stream since the last frame.
+
+        This is a convenience method that iterates over the items in the stream occurring after the time of the
+        previous frame and up to and including the current time.
+
+        Usage:
+        ```python
+        stream = ...
+        for key, value in stream.iter_items_since_previous_frame():
+            do_something(key, value)
+        ```
+        """
+        _check_can_read_stream()
+        return _StreamBoundedAscIterator(self, self.next_key(prev_time()), time())
+
     def iter_items_from_desc(self, start: int | float, /) -> SonolusIterator[tuple[int | float, T]]:
         """Iterate over the items in the stream in descending order starting from the given key.
 
@@ -347,6 +386,22 @@ class Stream[T](Record, BackingValue):
         _check_can_read_stream()
         return _StreamAscKeyIterator(self, self.next_key_inclusive(start))
 
+    def iter_keys_since_previous_frame(self) -> SonolusIterator[int | float]:
+        """Iterate over the keys in the stream since the last frame.
+
+        This is a convenience method that iterates over the keys in the stream occurring after the time of the
+        previous frame and up to and including the current time.
+
+        Usage:
+        ```python
+        stream = ...
+        for key in stream.iter_keys_since_previous_frame():
+            do_something(key)
+        ```
+        """
+        _check_can_read_stream()
+        return _StreamBoundedAscKeyIterator(self, self.next_key(prev_time()), time())
+
     def iter_keys_from_desc(self, start: int | float, /) -> SonolusIterator[int | float]:
         """Iterate over the keys in the stream in descending order starting from the given key.
 
@@ -377,6 +432,22 @@ class Stream[T](Record, BackingValue):
         _check_can_read_stream()
         return _StreamAscValueIterator(self, self.next_key_inclusive(start))
 
+    def iter_values_since_previous_frame(self) -> SonolusIterator[T]:
+        """Iterate over the values in the stream since the last frame.
+
+        This is a convenience method that iterates over the values in the stream occurring after the time of the
+        previous frame and up to and including the current time.
+
+        Usage:
+        ```python
+        stream = ...
+        for value in stream.iter_values_since_previous_frame():
+            do_something(value)
+        ```
+        """
+        _check_can_read_stream()
+        return _StreamBoundedAscValueIterator(self, self.next_key(prev_time()), time())
+
     def iter_values_from_desc(self, start: int | float, /) -> SonolusIterator[T]:
         """Iterate over the values in the stream in descending order starting from the given key.
 
@@ -396,7 +467,8 @@ class Stream[T](Record, BackingValue):
 class StreamGroup[T, Size](Record):
     """Represents a group of streams.
 
-    Most users should use `@stream` to declare stream groups rather than using this class directly.
+    Most users should use [`@streams`][sonolus.script.stream.streams] to declare stream groups rather than using this
+    class directly.
 
     Usage:
         Declaring a stream group:
@@ -444,13 +516,28 @@ class _StreamAscIterator[T](Record, SonolusIterator[tuple[int | float, T]]):
     current_key: int | float
 
     def has_next(self) -> bool:
-        return self.stream.next_key(self.current_key) > self.current_key
+        return self.current_key in self.stream
+
+    def get(self) -> tuple[int | float, T]:
+        return self.current_key, self.stream[self.current_key]
+
+    def advance(self):
+        self.current_key = self.stream.next_key_or_default(self.current_key, inf)
+
+
+class _StreamBoundedAscIterator[T](Record, SonolusIterator[tuple[int | float, T]]):
+    stream: Stream[T]
+    current_key: int | float
+    end_key: int | float
+
+    def has_next(self) -> bool:
+        return self.current_key in self.stream and self.current_key <= self.end_key
 
     def get(self) -> tuple[int | float, T]:
         return self.current_key, self.stream[self.current_key]
 
     def advance(self):
-        self.current_key = self.stream.next_key(self.current_key)
+        self.current_key = self.stream.next_key_or_default(self.current_key, inf)
 
 
 class _StreamDescIterator[T](Record, SonolusIterator[tuple[int | float, T]]):
@@ -458,13 +545,13 @@ class _StreamDescIterator[T](Record, SonolusIterator[tuple[int | float, T]]):
     current_key: int | float
 
     def has_next(self) -> bool:
-        return self.stream.previous_key(self.current_key) < self.current_key
+        return self.current_key in self.stream
 
     def get(self) -> tuple[int | float, T]:
         return self.current_key, self.stream[self.current_key]
 
     def advance(self):
-        self.current_key = self.stream.previous_key(self.current_key)
+        self.current_key = self.stream.previous_key_or_default(self.current_key, -inf)
 
 
 class _StreamAscKeyIterator[T](Record, SonolusIterator[int | float]):
@@ -472,13 +559,28 @@ class _StreamAscKeyIterator[T](Record, SonolusIterator[int | float]):
     current_key: int | float
 
     def has_next(self) -> bool:
-        return self.stream.next_key(self.current_key) > self.current_key
+        return self.current_key in self.stream
+
+    def get(self) -> int | float:
+        return self.current_key
+
+    def advance(self):
+        self.current_key = self.stream.next_key_or_default(self.current_key, inf)
+
+
+class _StreamBoundedAscKeyIterator[T](Record, SonolusIterator[int | float]):
+    stream: Stream[T]
+    current_key: int | float
+    end_key: int | float
+
+    def has_next(self) -> bool:
+        return self.current_key in self.stream and self.current_key <= self.end_key
 
     def get(self) -> int | float:
         return self.current_key
 
     def advance(self):
-        self.current_key = self.stream.next_key(self.current_key)
+        self.current_key = self.stream.next_key_or_default(self.current_key, inf)
 
 
 class _StreamDescKeyIterator[T](Record, SonolusIterator[int | float]):
@@ -486,13 +588,13 @@ class _StreamDescKeyIterator[T](Record, SonolusIterator[int | float]):
     current_key: int | float
 
     def has_next(self) -> bool:
-        return self.stream.previous_key(self.current_key) < self.current_key
+        return self.current_key in self.stream
 
     def get(self) -> int | float:
         return self.current_key
 
     def advance(self):
-        self.current_key = self.stream.previous_key(self.current_key)
+        self.current_key = self.stream.previous_key_or_default(self.current_key, -inf)
 
 
 class _StreamAscValueIterator[T](Record, SonolusIterator[T]):
@@ -500,13 +602,28 @@ class _StreamAscValueIterator[T](Record, SonolusIterator[T]):
     current_key: int | float
 
     def has_next(self) -> bool:
-        return self.stream.next_key(self.current_key) > self.current_key
+        return self.current_key in self.stream
+
+    def get(self) -> T:
+        return self.stream[self.current_key]
+
+    def advance(self):
+        self.current_key = self.stream.next_key_or_default(self.current_key, inf)
+
+
+class _StreamBoundedAscValueIterator[T](Record, SonolusIterator[T]):
+    stream: Stream[T]
+    current_key: int | float
+    end_key: int | float
+
+    def has_next(self) -> bool:
+        return self.current_key in self.stream and self.current_key <= self.end_key
 
     def get(self) -> T:
         return self.stream[self.current_key]
 
     def advance(self):
-        self.current_key = self.stream.next_key(self.current_key)
+        self.current_key = self.stream.next_key_or_default(self.current_key, inf)
 
 
 class _StreamDescValueIterator[T](Record, SonolusIterator[T]):
@@ -514,13 +631,13 @@ class _StreamDescValueIterator[T](Record, SonolusIterator[T]):
     current_key: int | float
 
     def has_next(self) -> bool:
-        return self.stream.previous_key(self.current_key) < self.current_key
+        return self.current_key in self.stream
 
     def get(self) -> T:
         return self.stream[self.current_key]
 
     def advance(self):
-        self.current_key = self.stream.previous_key(self.current_key)
+        self.current_key = self.stream.previous_key_or_default(self.current_key, -inf)
 
 
 @native_function(Op.StreamGetNextKey)

sonolus/script/transform.py

@@ -1,6 +1,7 @@
 from math import cos, sin
 from typing import Self
 
+from sonolus.script.interval import lerp, remap
 from sonolus.script.quad import Quad, QuadLike
 from sonolus.script.record import Record
 from sonolus.script.vec import Vec2
@@ -136,7 +137,7 @@ class Transform2d(Record):
         """Rotate about the origin and return a new transform.
 
         Args:
-            angle: The angle of rotation in radians.
+            angle: The angle of rotation in radians. Positive angles rotate counterclockwise.
 
         Returns:
             A new transform after rotation.
@@ -159,7 +160,7 @@ class Transform2d(Record):
         """Rotate about the pivot and return a new transform.
 
         Args:
-            angle: The angle of rotation in radians.
+            angle: The angle of rotation in radians. Positive angles rotate counterclockwise.
             pivot: The pivot point for rotation.
 
         Returns:
@@ -396,3 +397,291 @@ class Transform2d(Record):
             tl=self.transform_vec(quad.tl),
             tr=self.transform_vec(quad.tr),
         )
+
+
+class InvertibleTransform2d(Record):
+    """A transformation matrix for 2D points that can be inverted.
+
+    Usage:
+        ```python
+        InvertibleTransform2d.new()
+        ```
+    """
+
+    forward: Transform2d
+    inverse: Transform2d
+
+    @classmethod
+    def new(cls) -> Self:
+        """Create a new identity transform.
+
+        Returns:
+            A new identity transform.
+        """
+        return cls(
+            forward=Transform2d.new(),
+            inverse=Transform2d.new(),
+        )
+
+    def translate(self, translation: Vec2, /) -> Self:
+        """Translate along the x and y axes and return a new transform.
+
+        Args:
+            translation: The translation vector.
+
+        Returns:
+            A new invertible transform after translation.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.translate(translation),
+            inverse=Transform2d.new().translate(-translation).compose(self.inverse),
+        )
+
+    def scale(self, factor: Vec2, /) -> Self:
+        """Scale about the origin and return a new transform.
+
+        Args:
+            factor: The scale factor vector.
+
+        Returns:
+            A new invertible transform after scaling.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.scale(factor),
+            inverse=Transform2d.new().scale(Vec2.one() / factor).compose(self.inverse),
+        )
+
+    def scale_about(self, factor: Vec2, /, pivot: Vec2) -> Self:
+        """Scale about the pivot and return a new transform.
+
+        Args:
+            factor: The scale factor vector.
+            pivot: The pivot point for scaling.
+
+        Returns:
+            A new invertible transform after scaling.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.scale_about(factor, pivot),
+            inverse=Transform2d.new().scale_about(Vec2.one() / factor, pivot).compose(self.inverse),
+        )
+
+    def rotate(self, angle: float, /) -> Self:
+        """Rotate about the origin and return a new transform.
+
+        Args:
+            angle: The angle of rotation in radians. Positive angles rotate counterclockwise.
+
+        Returns:
+            A new invertible transform after rotation.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.rotate(angle),
+            inverse=Transform2d.new().rotate(-angle).compose(self.inverse),
+        )
+
+    def rotate_about(self, angle: float, /, pivot: Vec2) -> Self:
+        """Rotate about the pivot and return a new transform.
+
+        Args:
+            angle: The angle of rotation in radians. Positive angles rotate counterclockwise.
+            pivot: The pivot point for rotation.
+
+        Returns:
+            A new invertible transform after rotation.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.rotate_about(angle, pivot),
+            inverse=Transform2d.new().rotate_about(-angle, pivot).compose(self.inverse),
+        )
+
+    def shear_x(self, m: float, /) -> Self:
+        """Shear along the x-axis and return a new transform.
+
+        Args:
+            m: The shear factor along the x-axis.
+
+        Returns:
+            A new invertible transform after shearing.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.shear_x(m),
+            inverse=Transform2d.new().shear_x(-m).compose(self.inverse),
+        )
+
+    def shear_y(self, m: float, /) -> Self:
+        """Shear along the y-axis and return a new transform.
+
+        Args:
+            m: The shear factor along the y-axis.
+
+        Returns:
+            A new invertible transform after shearing.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.shear_y(m),
+            inverse=Transform2d.new().shear_y(-m).compose(self.inverse),
+        )
+
+    def simple_perspective_x(self, x: float, /) -> Self:
+        """Apply perspective along the x-axis with vanishing point at the given x coordinate and return a new transform.
+
+        Args:
+            x: The x coordinate of the vanishing point.
+
+        Returns:
+            A new invertible transform after applying perspective.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.simple_perspective_x(x),
+            inverse=Transform2d.new().simple_perspective_x(-x).compose(self.inverse),
+        )
+
+    def simple_perspective_y(self, y: float, /) -> Self:
+        """Apply perspective along the y-axis with vanishing point at the given y coordinate and return a new transform.
+
+        Args:
+            y: The y coordinate of the vanishing point.
+
+        Returns:
+            A new invertible transform after applying perspective.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.simple_perspective_y(y),
+            inverse=Transform2d.new().simple_perspective_y(-y).compose(self.inverse),
+        )
+
+    def perspective_x(self, foreground_x: float, vanishing_point: Vec2, /) -> Self:
+        """Apply a perspective transformation along the x-axis and return a new transform.
+
+        Args:
+            foreground_x: The foreground x-coordinate.
+            vanishing_point: The vanishing point vector.
+
+        Returns:
+            A new invertible transform after applying perspective.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.perspective_x(foreground_x, vanishing_point),
+            inverse=Transform2d.new().inverse_perspective_x(foreground_x, vanishing_point).compose(self.inverse),
+        )
+
+    def perspective_y(self, foreground_y: float, vanishing_point: Vec2, /) -> Self:
+        """Apply a perspective transformation along the y-axis and return a new transform.
+
+        Args:
+            foreground_y: The foreground y-coordinate.
+            vanishing_point: The vanishing point vector.
+
+        Returns:
+            A new invertible transform after applying perspective.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.perspective_y(foreground_y, vanishing_point),
+            inverse=Transform2d.new().inverse_perspective_y(foreground_y, vanishing_point).compose(self.inverse),
+        )
+
+    def normalize(self) -> Self:
+        """Normalize the transform to have a 1 in the bottom right corner and return a new transform.
+
+        This may fail in some special cases involving perspective transformations where the bottom right corner is 0.
+
+        Returns:
+            A new normalized invertible transform.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.normalize(),
+            inverse=self.inverse.normalize(),
+        )
+
+    def compose(self, other: Self, /) -> Self:
+        """Compose with another invertible transform which is applied after this transform and return a new transform.
+
+        Args:
+            other: The other invertible transform to compose with.
+
+        Returns:
+            A new invertible transform resulting from the composition.
+        """
+        return InvertibleTransform2d(
+            forward=self.forward.compose(other.forward),
+            inverse=other.inverse.compose(self.inverse),
+        )
+
+    def compose_before(self, other: Self, /) -> Self:
+        """Compose with another invertible transform which is applied before this transform and return a new transform.
+
+        Args:
+            other: The other invertible transform to compose with.
+
+        Returns:
+            A new invertible transform resulting from the composition.
+        """
+        return other.compose(self)
+
+    def transform_vec(self, v: Vec2) -> Vec2:
+        """Transform a [`Vec2`][sonolus.script.vec.Vec2] and return a new [`Vec2`][sonolus.script.vec.Vec2].
+
+        Args:
+            v: The vector to transform.
+
+        Returns:
+            A new transformed vector.
+        """
+        return self.forward.transform_vec(v)
+
+    def inverse_transform_vec(self, v: Vec2) -> Vec2:
+        """Inverse transform a [`Vec2`][sonolus.script.vec.Vec2] and return a new [`Vec2`][sonolus.script.vec.Vec2].
+
+        Args:
+            v: The vector to inverse transform.
+
+        Returns:
+            A new inverse transformed vector.
+        """
+        return self.inverse.transform_vec(v)
+
+    def transform_quad(self, quad: QuadLike) -> Quad:
+        """Transform a [`Quad`][sonolus.script.quad.Quad] and return a new [`Quad`][sonolus.script.quad.Quad].
+
+        Args:
+            quad: The quad to transform.
+
+        Returns:
+            A new transformed quad.
+        """
+        return self.forward.transform_quad(quad)
+
+    def inverse_transform_quad(self, quad: QuadLike) -> Quad:
+        """Inverse transform a [`Quad`][sonolus.script.quad.Quad] and return a new [`Quad`][sonolus.script.quad.Quad].
+
+        Args:
+            quad: The quad to inverse transform.
+
+        Returns:
+            A new inverse transformed quad.
+        """
+        return self.inverse.transform_quad(quad)
+
+
+def perspective_approach(
+    distance_ratio: float,
+    progress: float,
+) -> float:
+    """Calculate the perspective correct approach curve given the initial distance, target distance, and progress.
+
+    For typical engines with stage tilt, distance_ratio is the displayed width of a lane at the judge line divided
+    by the displayed width of a lane at note spawn. For flat stages, this will be 1.0, and this function would simply
+    return progress unchanged.
+
+    Args:
+        distance_ratio: The ratio of the distance at note spawn to the distance at the judge line.
+        progress: The progress value, where 0 corresponds to note spawn and 1 corresponds to the judge line.
+
+    Returns:
+        The perspective-corrected progress value.
+    """
+    d_0 = distance_ratio
+    d_1 = 1.0
+    d = max(lerp(d_0, d_1, progress), 1e-6)  # Avoid a zero or negative distance
+    return remap(1 / d_0, 1 / d_1, 0, 1, 1 / d)

sonolus/script/values.py

@@ -19,13 +19,19 @@ def alloc[T](type_: type[T]) -> T:
 
 @meta_fn
 def zeros[T](type_: type[T]) -> T:
-    """Make a new instance of the given type initialized with zeros."""
+    """Make a new instance of the given type initialized with zeros.
+
+    Generally works the same as the unary `+` operator on record and array types.
+    """
     return validate_concrete_type(type_)._zero_()
 
 
 @meta_fn
 def copy[T](value: T) -> T:
-    """Make a deep copy of the given value."""
+    """Make a deep copy of the given value.
+
+    Generally works the same as the unary `+` operator on records and arrays.
+    """
     value = validate_value(value)
     if ctx():
         return value._copy_()
@@ -34,7 +40,7 @@ def copy[T](value: T) -> T:
 
 
 def swap[T](a: T, b: T):
-    """Swap the values of the two given arguments."""
+    """Swap the values of the two provided mutable values."""
     temp = copy(a)
     a @= b
     b @= temp

sonolus/script/vec.py

@@ -73,6 +73,18 @@ class Vec2(Record):
         """
         return cls(x=1, y=0)
 
+    @classmethod
+    def unit(cls, angle: Num) -> Self:
+        """Return a unit vector (magnitude 1) at a given angle in radians.
+
+        Args:
+            angle: The angle in radians.
+
+        Returns:
+            A new unit vector at the specified angle.
+        """
+        return Vec2(x=cos(angle), y=sin(angle))
+
     @property
     def magnitude(self) -> Num:
         """Calculate the magnitude (length) of the vector.
@@ -106,7 +118,7 @@ class Vec2(Record):
         """Rotate the vector by a given angle in radians and return a new vector.
 
         Args:
-            angle: The angle to rotate the vector by, in radians.
+            angle: The angle to rotate the vector by, in radians. Positive angles rotate counterclockwise.
 
         Returns:
             A new vector rotated by the given angle.
@@ -120,7 +132,7 @@ class Vec2(Record):
         """Rotate the vector about a pivot by a given angle in radians and return a new vector.
 
         Args:
-            angle: The angle to rotate the vector by, in radians.
+            angle: The angle to rotate the vector by, in radians. Positive angles rotate counterclockwise.
             pivot: The pivot point to rotate about.
 
         Returns:

{sonolus_py-0.3.1.dist-info → sonolus_py-0.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sonolus.py
-Version: 0.3.1
+Version: 0.3.3
 Summary: Sonolus engine development in Python
 License-File: LICENSE
 Requires-Python: >=3.12