Skip to content

The animation engine for agents: blazingly fast math and 3D videos with Manim's Python API, on a Rust GPU core.

Python

Connect render feed to player

Sina Atalay94c4e475ea6e
diff --git a/src/manimgx/animation/updaters.py b/src/manimgx/animation/updaters.py
index a56b94be..d7d461bc 100644
--- a/src/manimgx/animation/updaters.py
+++ b/src/manimgx/animation/updaters.py
@@ -7,6 +7,8 @@
from __future__ import annotations
+from warnings import deprecated
+
__all__ = [
"AnimatedBoundary",
"TracedPath",
@@ -20,7 +22,9 @@ __all__ = [
"turn_animation_into_updater",
]
import inspect
+import itertools
from collections.abc import Callable, Sequence
+from dataclasses import dataclass
from typing import TYPE_CHECKING, Self, Unpack
import numpy as np
@@ -52,6 +56,7 @@ def _owner(method: Callable[..., object]) -> tuple[Mobject, Callable[..., object
return method.__self__, method.__func__
+@deprecated("Manim CE's machinery: manimgx calls it itself", category=None)
def assert_is_mobject_method(method: Callable[..., object]) -> None:
"""Check that `method` is a method of a mobject, bound to it (as `square.move_to`):
anything else raises a TypeError.
@@ -62,6 +67,10 @@ def assert_is_mobject_method(method: Callable[..., object]) -> None:
_owner(method)
+@deprecated(
+ "always(mobject.method, *args) is mobject.always.method(*args): use it",
+ category=None,
+)
def always[**P](
method: Callable[P, object], *args: P.args, **kwargs: P.kwargs
) -> Mobject:
@@ -89,6 +98,7 @@ def always[**P](
return mobject
+@deprecated("use add_updater, or always_redraw", category=None)
def f_always(
method: Callable[..., object],
*arg_generators: Callable[[], object],
@@ -246,7 +256,8 @@ def turn_animation_into_updater(
the scene; after `delay` seconds it plays, at its run time and rate function. When
it ends, it finishes and its updater is removed; with `cycle`, it starts over from
its beginning instead, again and again. Nothing is added to the scene or taken out
- of it: add the mobject yourself.
+ of it: add the mobject yourself. The animation and its time are the mobject's: a
+ copy of it plays a copy of them, on itself.
Args:
cycle: Whether it repeats forever.
@@ -278,13 +289,20 @@ def turn_animation_into_updater(
animation.interpolate(
0
) # the object is the animation's from now: at its start, until then
- elapsed = -delay
+ # the animation and its time are kept on the mobject, so that a copy of it plays a copy
+ # of them: the updater holds only their key, and plays those of the mobject it runs on
+ key = next(_PLAYED_KEYS)
+ played: dict[int, _Played] = mobject.__dict__.setdefault("_played", {})
+ played[key] = _Played(animation, -delay)
def update(m: Mobject, dt: float) -> None:
- nonlocal elapsed
- elapsed += dt # its time now: what this frame shows
- if elapsed < 0:
+ state = m.__dict__.get("_played", {}).get(key)
+ if state is None: # nothing of its own to play
+ return
+ state.elapsed += dt # its time now: what this frame shows
+ if state.elapsed < 0:
return
+ animation, elapsed = state.animation, state.elapsed
run_time = animation.get_run_time()
if run_time > 0 and (cycle or elapsed < run_time):
animation.interpolate(
@@ -294,11 +312,24 @@ def turn_animation_into_updater(
else:
animation.finish()
m.remove_updater(update)
+ del m.__dict__["_played"][key]
mobject.add_updater(flow(update)) # the animation at the time it has run
return mobject
+@dataclass
+class _Played:
+ """An animation [turn_animation_into_updater][manimgx.turn_animation_into_updater]
+ plays, and the time it has run (before its delay, negative)."""
+
+ animation: Animation
+ elapsed: float
+
+
+_PLAYED_KEYS = itertools.count()
+
+
def cycle_animation(animation: Animation, delay: float = 0) -> Mobject:
"""Play an animation over and over, from an updater of its mobject:
[`turn_animation_into_updater`][manimgx.turn_animation_into_updater] with `cycle`.
@@ -373,7 +404,7 @@ class AnimatedBoundary(VGroup):
def __init__(
self,
vmobject: Mobject,
- colors: Sequence[ParsableManimColor] = [BLUE_D, BLUE_B, BLUE_E, GREY_BROWN],
+ colors: Sequence[ParsableManimColor] = (BLUE_D, BLUE_B, BLUE_E, GREY_BROWN),
max_stroke_width: float = 3,
cycle_rate: float = 0.5,
back_and_forth: bool = True,
@@ -382,7 +413,7 @@ class AnimatedBoundary(VGroup):
**kwargs: Unpack[Style],
):
super().__init__(**kwargs)
- self.colors = colors
+ self.colors = list(colors) # its own: the default, or what was given, as it was
self.max_stroke_width = max_stroke_width
self.cycle_rate = cycle_rate
self.back_and_forth = back_and_forth
@@ -396,6 +427,7 @@ class AnimatedBoundary(VGroup):
self.total_time = 0.0
self.add_updater(flow(lambda m, dt: m.update_boundary_copies(dt)))
+ @deprecated("Manim CE's machinery: its updater calls it", category=None)
def update_boundary_copies(self, dt: float) -> None:
"""Move the outline on by some time: its updater calls it every frame.
@@ -422,6 +454,7 @@ class AnimatedBoundary(VGroup):
self.full_family_become_partial(fading, vmobject, 0, 1)
fading.set_stroke(color=colors[index - 1], width=(1 - fade_alpha) * msw)
+ @deprecated("Manim CE's machinery: its updater calls it", category=None)
def full_family_become_partial(
self, mob1: Mobject, mob2: Mobject, a: float, b: float
) -> Self:
@@ -513,20 +546,21 @@ class TracedPath(VMobject):
self.traced_point_func = traced_point_func
self.dissipating_time = dissipating_time
self.time = 0.0 # the path's own time
- self._traced: list[float] = (
- []
- ) # when each curve's end was traced (its own time)
- self._open: list[float] = (
- []
- ) # the scene time of each curve's end since the last frame
+ # when each curve's end was traced (its own time)
+ self._traced: list[float] = []
+ # the scene time of each curve's end since the last frame
+ self._open: list[float] = []
self._framed: float | None = None # the scene time of the last frame (or event)
self._last = np.zeros(3) # the point as last traced
self._loose = (
False # its last curve runs on to the point at a frame between two ticks
)
- self.add_updater(self.update_path)
+ self.add_updater(
+ _trace
+ ) # (a function of the path it runs on: a copy traces itself)
@record
+ @deprecated("Manim CE's machinery: its updater calls it", category=None)
def update_path(self, mob: Mobject, dt: float) -> None:
"""Trace the point where it is now: the path's updater, a
[recorder][manimgx.mobject.record].
@@ -605,3 +639,11 @@ class TracedPath(VMobject):
self._last = point
self._open = [now] if self._loose else []
self._framed = now
+
+
+@record
+def _trace(path: Mobject, dt: float) -> None:
+ """A traced path's updater: it traces the path it runs on (its copies, a path that takes
+ its updaters over), and holds nothing of the path it was made for."""
+ if isinstance(path, TracedPath):
+ path.update_path(path, dt)
diff --git a/src/manimgx/rendering/feed.py b/src/manimgx/rendering/feed.py
new file mode 100644
index 00000000..ef2f399e
--- /dev/null
+++ b/src/manimgx/rendering/feed.py
@@ -0,0 +1,1255 @@
+"""Feed the player: shapes once, then one 320-byte record per object and frame.
+
+A shape is uploaded as its object defines it, and the player derives what drawing needs. A path
+goes as control points in its own space, with its subpaths as curve ranges, so a reveal is a
+window over u = curve index + t, and the player flattens curves at the size they are drawn; a
+mesh goes as its points, texture coordinates and triangles, and the player sums its faces into
+its vertices' normals (unless a surface's spline supplies them). An
+upload is named by content and resource kind (`digest`), so identical resources upload once.
+A record is an object's blend terms (two shape keys, two 3×4 matrices), reveal window, brushes,
+widths and flags; the camera is one 4×4 matrix."""
+
+import functools
+import itertools
+import struct
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from manimgx import _engine
+from manimgx._engine import Recorder, digest
+from manimgx.caches import forgets
+from manimgx.constants import CapStyleType, LineJointType
+from manimgx.drawing.geometry import (
+ IDENTITY,
+ Blend,
+ Shape,
+ grid_triangles,
+ subpath_ranges,
+)
+from manimgx.drawing.paint import stretch_array
+from manimgx.mobject import MeshMobject, PMobject, VMobject
+from manimgx.mobjects.images import ImageMobject
+from manimgx.mobjects.lights import (
+ EnvironmentLight,
+ Light,
+ PointLight,
+ SpotLight,
+ SunLight,
+)
+
+if TYPE_CHECKING:
+ from manimgx.drawing.geometry import Path
+ from manimgx.mobject import Mobject
+ from manimgx.scene import Camera
+
+# a camera's view, drawn into a texture that later views sample by its key:
+# (key, width, height, view, records)
+type CameraView = tuple[int, int, int, bytes, bytes]
+
+KEEP = 120 # frames a shape stays resident after the last frame that showed it
+SWEEP = 240 # frames between evictions
+MARK = 16 # frames between marking what the frame shows (see `sweep`)
+BUDGET = 768 << 20 # living bytes (shapes, rows, textures) before the stale go at once
+NEAR = 0.05
+ON_3D = 1e-6 # a share of a depth (8 of its f32 steps): a path this near behind a mesh lies on it
+OVERLAY, LIT = 1, 4
+# an image's reconstruction by its resampling algorithm (the player's flags; linear: none)
+NEAREST, CUBIC = 16, 32
+_RECONSTRUCTION = {0: NEAREST, 2: 0, 3: CUBIC}
+# a stroke's style, in the flags from bit 6 (cap | joint << 2): AUTO is a butt cap and a miter
+# joint (a bevel past the miter limit, 10), for every path
+CAPS = {
+ CapStyleType.AUTO: 0,
+ CapStyleType.BUTT: 0,
+ CapStyleType.ROUND: 1 << 6,
+ CapStyleType.SQUARE: 2 << 6,
+}
+JOINTS = {
+ LineJointType.AUTO: 0,
+ LineJointType.MITER: 0,
+ LineJointType.ROUND: 1 << 8,
+ LineJointType.BEVEL: 2 << 8,
+}
+_FEEDERS = itertools.count(1)
+# paint 2 (fill2 … stroke_rows2) is mixed in by dash[3]: a tween's paint, mixed by the player
+RECORD = np.dtype(
+ [
+ ("key1", "<u8"),
+ ("key2", "<u8"),
+ ("fill_rows", "<u8"),
+ ("stroke_rows", "<u8"),
+ ("fill_rows2", "<u8"),
+ ("stroke_rows2", "<u8"),
+ ("texture", "<u8"),
+ ("flags", "<u8"),
+ ("m1", "<f4", (3, 4)),
+ ("m2", "<f4", (3, 4)),
+ ("fill", "<f4", 4),
+ ("stroke", "<f4", 4),
+ ("background", "<f4", 4),
+ ("fill2", "<f4", 4),
+ ("stroke2", "<f4", 4),
+ ("background2", "<f4", 4),
+ ("params", "<f4", 4),
+ ("gradient_a", "<f4", 4),
+ ("gradient_b", "<f4", 4),
+ ("dash", "<f4", 4), # period, duty, phase (u); how far paint 2 is mixed in
+ ("material", "<f4", 4), # metallic, roughness, reflectance; 1 where it has one
+ ]
+)
+assert RECORD.itemsize == 336
+# a record as Python packs it: its 8 integers, its 68 floats
+PACKED = struct.Struct("<8Q68f")
+NO_MATERIAL = (0.0, 0.5, 0.5, 0.0)
+LIGHTS = 8 # the most lights a view takes
+assert PACKED.size == RECORD.itemsize
+NO_TERM = (0.0,) * 12
+KEYS = ("key1", "key2", "fill_rows", "stroke_rows", "fill_rows2", "stroke_rows2")
+
+
+def unpack(record: bytes | None) -> np.void | None:
+ """A record's fields (for mixing records of a pure play)."""
+ return None if record is None else np.frombuffer(record, RECORD)[0]
+
+
+def place(m: np.ndarray, a: np.ndarray) -> np.ndarray:
+ """m ∘ a for 3×4 affine maps: a shape's placement over its affine class —
+ [L | t] ∘ [A | b] = L·[A | b] + [0 | t]."""
+ out = m[:, :3] @ a
+ out[:, 3] += m[:, 3]
+ return out
+
+
+def structure(points: np.ndarray) -> list[tuple[int, int, bool]]:
+ """Subpaths as curve ranges (first curve, end curve, closed), by CE's break rule."""
+ return [(a // 4, b // 4, closed) for a, b, closed in subpath_ranges(points, 1e-6)]
+
+
+def union(
+ a: list[tuple[int, int, bool]], b: list[tuple[int, int, bool]]
+) -> list[tuple[int, int, bool]]:
+ """The subpaths of a morph between two aligned shapes: a break wherever either breaks, closed
+ only where both are."""
+ starts = sorted({s for s, _, _ in a} | {s for s, _, _ in b})
+ end = max(e for _, e, _ in a + b)
+ closed_a = {(s, e) for s, e, c in a if c}
+ closed_b = {(s, e) for s, e, c in b if c}
+ spans = list(zip(starts, starts[1:] + [end], strict=True))
+ return [(s, e, (s, e) in closed_a and (s, e) in closed_b) for s, e in spans]
+
+
+def control(
+ points: np.ndarray, ranges: list[tuple[int, int, bool]]
+) -> tuple[bytes, bytes]:
+ """(control points, subpaths) of one path shape as the player takes them: float64 x, y, z per
+ control point, four per curve; (first curve, end curve, closed, 0) per subpath."""
+ whole = points[: len(points) // 4 * 4]
+ subpaths = np.array([(c0, c1, int(closed), 0) for c0, c1, closed in ranges], "<u4")
+ return np.ascontiguousarray(whole, "<f8").tobytes(), subpaths.tobytes()
+
+
+def centroid_area(points: np.ndarray) -> list[float]:
+ """Mean of the control points and their Newell area vector (one closed polygon)."""
+ nxt = np.roll(points, -1, axis=0)
+ area = np.array(
+ [
+ np.sum((points[:, 1] - nxt[:, 1]) * (points[:, 2] + nxt[:, 2])),
+ np.sum((points[:, 2] - nxt[:, 2]) * (points[:, 0] + nxt[:, 0])),
+ np.sum((points[:, 0] - nxt[:, 0]) * (points[:, 1] + nxt[:, 1])),
+ ]
+ )
+ return [*points.mean(axis=0), *area]
+
+
+# ── surfaces: drawn as the C² spline through their samples ─────────────────────────
+#
+# A surface is its samples of func(u, v) on a grid; drawn, it is the tensor-product cubic
+# spline through them (periodic along a direction whose ends meet, not-a-knot otherwise): C²,
+# exact for cubics, O(h⁴) from a smooth func — a coarse grid draws the surface, not flat
+# quads. Each face (a grid cell) is refined into m × m cells of its spline patch, m chosen per
+# shape so that no chord leaves the spline by more than SURFACE_TOLERANCE; normals are the
+# spline's (smooth shading). A face keeps its own vertices, so a checkerboard keeps its sharp
+# cells, and its edge loop (4m + 1 vertices) is its outline.
+
+# scene units: a quarter pixel at 1080p, the frame 8 units high
+SURFACE_TOLERANCE = 2e-3
+SURFACE_STEPS = 16 # at most, per face and direction
+
+
+@forgets
+def _derivative(n: int, periodic: bool) -> np.ndarray:
+ """(n × n) tangents, per sample step, of the C² cubic spline through n evenly spaced values:
+ periodic (the last value repeats the first) or not-a-knot (below four values: the
+ polynomial through them)."""
+ if n < 4:
+ few = [
+ [[0.0]],
+ [[-1.0, 1.0]] * 2,
+ [[-1.5, 2, -0.5], [-0.5, 0, 0.5], [0.5, -2, 1.5]],
+ ]
+ return np.array(few[n - 1])
+ k = n - 1 if periodic else n
+ a, b, i = np.zeros((k, k)), np.zeros((k, k)), np.arange(k)
+ # C²: m[i-1] + 4 m[i] + m[i+1] = 3 (p[i+1] − p[i-1])
+ a[i, i], a[i, (i - 1) % k], a[i, (i + 1) % k] = 4.0, 1.0, 1.0
+ b[i, (i + 1) % k], b[i, (i - 1) % k] = 3.0, -3.0
+ if (
+ not periodic
+ ): # not-a-knot: the third derivative is continuous at the second knots
+ a[[0, -1]], b[[0, -1]] = 0.0, 0.0
+ a[0, [0, 2]], b[0, :3] = [1.0, -1.0], [-2.0, 4.0, -2.0]
+ a[-1, [-3, -1]], b[-1, -3:] = [-1.0, 1.0], [2.0, -4.0, 2.0]
+ d = np.linalg.solve(a, b)
+ return np.pad(np.vstack([d, d[:1]]), ((0, 0), (0, 1))) if periodic else d
+
+
+def _hermite(x: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+ """Cubic Hermite bases at x (value at 0, at 1; tangent at 0, at 1) and their slopes."""
+ x2, x3 = x * x, x * x * x
+ value = np.stack([2 * x3 - 3 * x2 + 1, 3 * x2 - 2 * x3, x3 - 2 * x2 + x, x3 - x2])
+ slope = np.stack(
+ [6 * x2 - 6 * x, 6 * x - 6 * x2, 3 * x2 - 4 * x + 1, 3 * x2 - 2 * x]
+ )
+ return value, slope
+
+
+def _cells(g: np.ndarray) -> np.ndarray:
+ """Each cell's bicubic Hermite data from the spline through grid `g` ((u + 1) × (v + 1) ×
+ dims): (4, 4, u, v, dims) — [value at s 0, 1; ∂u at s 0, 1] × [the same along t, ∂v].
+ """
+ tol = 1e-7 * (1.0 + np.abs(g[..., :3]).max())
+ du = _derivative(len(g), bool(np.abs(g[0, :, :3] - g[-1, :, :3]).max() <= tol))
+ dv = _derivative(g.shape[1], bool(np.abs(g[:, 0, :3] - g[:, -1, :3]).max() <= tol))
+ gu = np.einsum("ik,kjd->ijd", du, g)
+ data = (
+ (g, np.einsum("jk,ikd->ijd", dv, g)),
+ (gu, np.einsum("jk,ikd->ijd", dv, gu)),
+ )
+ u, v = len(g) - 1, g.shape[1] - 1
+ return np.array(
+ [
+ [
+ data[i // 2][j // 2][i % 2 : u + i % 2, j % 2 : v + j % 2]
+ for j in range(4)
+ ]
+ for i in range(4)
+ ]
+ )
+
+
+def _patches(cells: np.ndarray, x: np.ndarray) -> tuple[np.ndarray, ...]:
+ """Points, ∂/∂s and ∂/∂t of every cell at (s, t) ∈ x × x: each (u, v, len(x), len(x),
+ dims)."""
+ value, slope = _hermite(x)
+ along_t = np.einsum("bq,abuvd->auvqd", value, cells)
+ points = np.einsum("ap,auvqd->uvpqd", value, along_t)
+ ds = np.einsum("ap,auvqd->uvpqd", slope, along_t)
+ dt = np.einsum("ap,bq,abuvd->uvpqd", value, slope, cells, optimize=True)
+ return points, ds, dt
+
+
+def surface_steps(g: np.ndarray, linear: np.ndarray) -> int:
+ """m: cells per face and direction for no chord to leave the spline by more than
+ SURFACE_TOLERANCE where `linear` places it (a chord's deviation falls as 1/m²)."""
+ mid = _patches(_cells(g[..., :3]), np.array([0.5]))[0][:, :, 0, 0]
+ flat = (g[:-1, :-1, :3] + g[1:, :-1, :3] + g[:-1, 1:, :3] + g[1:, 1:, :3]) / 4
+ deviation = float(np.linalg.norm((mid - flat) @ linear.T, axis=-1).max())
+ return int(
+ np.clip(np.ceil(np.sqrt(deviation / SURFACE_TOLERANCE)), 1, SURFACE_STEPS)
+ )
+
+
+@forgets
+def _face_layout(m: int) -> tuple[np.ndarray, np.ndarray]:
+ """A refined face's vertices, as (p, q) on its (m + 1)² lattice — its edge loop first
+ ((0,0) → (m,0) → (m,m) → (0,m) → (0,0): the face's own loop, 4m + 1 with the first
+ repeated), then its inside — and its 2m² triangles, as indices into them."""
+ loop = [(p, 0) for p in range(m)] + [(m, q) for q in range(m)]
+ loop += [(p, m) for p in range(m, 0, -1)] + [(0, q) for q in range(m, -1, -1)]
+ order = np.array(loop + [(p, q) for p in range(1, m) for q in range(1, m)])
+ index = np.zeros((m + 1, m + 1), dtype=np.int64)
+ distinct = (
+ np.arange(len(order)) != 4 * m
+ ) # the loop's last vertex repeats its first
+ index[order[distinct, 0], order[distinct, 1]] = np.arange(len(order))[distinct]
+ triangles = index.ravel()[grid_triangles(m, m)]
+ order.flags.writeable = triangles.flags.writeable = False
+ return order, triangles
+
+
+def refine_surface(
+ g: np.ndarray, m: int
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, int]:
+ """A surface grid drawn: every face's block of the spline's points (any extra columns
+ alike), their normals, the triangles, the block's size."""
+ x = np.linspace(0.0, 1.0, m + 1)
+ cells = _cells(g)
+ points, ds, dt = _patches(cells, x)
+ normal = np.cross(ds[..., :3], dt[..., :3])
+ # where a direction collapses (a pole), the normal a hair inside the face
+ thin = (
+ np.linalg.norm(normal, axis=-1) <= 1e-10 * (1.0 + np.abs(g[..., :3]).max()) ** 2
+ )
+ if thin.any():
+ i, j = np.nonzero(thin.any(axis=(2, 3)))
+ _, ds, dt = _patches(cells[:, :, i, j][:, :, None], 1e-3 + (1.0 - 2e-3) * x)
+ nudged = np.cross(ds[..., :3], dt[..., :3])[0]
+ normal[i, j] = np.where(thin[i, j][..., None], nudged, normal[i, j])
+ order, triangles = _face_layout(m)
+ block, faces = len(order), (len(g) - 1) * (g.shape[1] - 1)
+ points = points[:, :, order[:, 0], order[:, 1]].reshape(faces * block, -1)
+ normal = normal[:, :, order[:, 0], order[:, 1]].reshape(faces * block, 3)
+ offsets = np.arange(faces)[:, None, None] * block
+ return points, normal, (triangles[None] + offsets).reshape(-1, 3), block
+
+
+def rotation(phi: float, theta: float, gamma: float) -> np.ndarray:
+ """CE's camera orbit: world → camera axes."""
+
+ def rz(a: float) -> np.ndarray:
+ return np.array(
+ [[np.cos(a), -np.sin(a), 0.0], [np.sin(a), np.cos(a), 0.0], [0.0, 0.0, 1.0]]
+ )
+
+ c, s = np.cos(-phi), np.sin(-phi)
+ rx = np.array([[1.0, 0.0, 0.0], [0.0, c, -s], [0.0, s, c]])
+ return rz(gamma) @ rx @ rz(-theta - np.pi / 2)
+
+
+def linear(rgb: np.ndarray) -> np.ndarray:
+ """sRGB-encoded colors in linear light (what light adds)."""
+ return np.where(rgb <= 0.04045, rgb / 12.92, ((rgb + 0.055) / 1.055) ** 2.4)
+
+
+def lighting(camera: "Camera", lights: "list[Light]") -> list[float]:
+ """A view's lights, four vectors each, `LIGHTS` of them (the first ones): where (an ambient
+ light: nowhere; a sun: its direction; a point or spot: its point; an environment: its
+ picture's right) and its kind; its color in linear light times its intensity, and a
+ point's or spot's reach (an environment: its picture's id, 0 the studio); a spot's axis
+ (an environment: its picture's up) and the scale and offset of its cone's falloff
+ (Filament's), and whether it casts shadows (an environment: its picture's sun, which
+ the engine lights by as a sun of the view's). A scene with no lights has the camera's: a sun
+ from its light source, and a dim ambient light (as Manim's shading always has its light).
+ """
+ if not lights:
+ sun = np.asarray(camera.light_source.get_center(), dtype=float)
+ sun = sun / max(float(np.linalg.norm(sun)), 1e-9)
+ out = [*sun, 1.0, 1.0, 1.0, 1.0, 0.0, *[0.0] * 8] # a white sun
+ out += [
+ 0.0,
+ 0.0,
+ 0.0,
+ 0.0,
+ 0.1,
+ 0.1,
+ 0.1,
+ 0.0,
+ *[0.0] * 8,
+ ] # an ambient light, 0.1
+ return out + [0.0] * (16 * LIGHTS - len(out))
+ out = []
+ for light in lights[:LIGHTS]:
+ place = np.asarray(light.get_center(), dtype=float)
+ color = [*(linear(light.light_color.to_rgb()) * light.intensity)]
+ if isinstance(light, EnvironmentLight):
+ right, up = light.axes()
+ picture = 0.0 if light.picture is None else float(light.picture.id)
+ out += [
+ *right,
+ 4.0,
+ *color,
+ picture,
+ *up,
+ 0.0,
+ 0.0,
+ float(light.shadows),
+ 0,
+ 0,
+ ]
+ continue
+ axis, scale, offset = np.zeros(3), 0.0, 0.0
+ if isinstance(light, SunLight):
+ place = place / max(float(np.linalg.norm(place)), 1e-9)
+ if isinstance(light, SpotLight):
+ axis = light.toward - place
+ axis = axis / max(float(np.linalg.norm(axis)), 1e-9)
+ outer = np.cos(light.angle)
+ inner = np.cos(light.angle * (1.0 - light.softness))
+ scale = 1.0 / max(inner - outer, 1e-4)
+ offset = -outer * scale
+ reach = light.radius if isinstance(light, PointLight) else 0.0
+ shadows = isinstance(light, (SunLight, SpotLight)) and light.shadows
+ out += [
+ *place,
+ float(light.kind),
+ *color,
+ reach,
+ *axis,
+ scale,
+ offset,
+ float(shadows), # (the engine fits its shadow map)
+ 0.0,
+ 0.0,
+ ]
+ return out + [0.0] * (16 * LIGHTS - len(out))
+
+
+def lit(mobjects: "list[Mobject]") -> "list[Light]":
+ """The lights among a view's mobjects."""
+ return [m for m in mobjects if isinstance(m, Light)]
+
+
+def view(
+ camera: "Camera", width: int, height: int, lights: "list[Light] | None" = None
+) -> tuple[bytes, np.ndarray, bool]:
+ """(uniform bytes, world → clip matrix, 3D?) of a camera; 2D is orthographic, so the painter's
+ order stands. Reads only the camera's mobjects (`get_mobjects_indicating_movement`) and settings,
+ and the view's `lights` (a 3D view's: those that light the mobjects with a material).
+ """
+ hw, hh = camera.frame_width / 2, camera.frame_height / 2
+ center = np.asarray(camera.frame_center, dtype=float)
+ three_d = bool(camera.three_d)
+ overlay = np.diag([1 / hw, 1 / hh, 0.0, 1.0])
+ if three_d:
+ r = rotation(camera.get_phi(), camera.get_theta(), camera.get_gamma())
+ zoom, f = camera.get_zoom(), camera.get_focal_distance()
+ rc = r @ center
+ projection = np.array(
+ [
+ [*(zoom / hw * r[0]), -zoom / hw * rc[0]],
+ [*(zoom / hh * r[1]), -zoom / hh * rc[1]],
+ # reversed Z: depth NEAR / distance (1 at the near plane, 0 at infinity): a
+ # float depth's digits where things are far, as the composite's own depths
+ [0.0, 0.0, 0.0, NEAR / f],
+ [*(-r[2] / f), (f + rc[2]) / f],
+ ]
+ )
+ toward, bias = r[2], ON_3D
+ eye = [*(center + f * r[2]), 1.0]
+ else:
+ eye = [0.0, 0.0, 0.0, 0.0]
+ zoom = 1.0
+ projection = np.array(
+ [
+ [1 / hw, 0, 0, -center[0] / hw],
+ [0, 1 / hh, 0, -center[1] / hh],
+ [0, 0, 0, 0.5],
+ [0, 0, 0, 1.0],
+ ]
+ )
+ toward, bias = np.array([0.0, 0.0, 1.0]), 0.0
+ uniform = np.concatenate(
+ [
+ projection.T.ravel(), # WGSL matrices are column-major
+ overlay.T.ravel(),
+ [width, height, height / camera.frame_height, zoom],
+ [*camera.light_source.get_center(), float(three_d)],
+ [*toward, bias],
+ camera.background_color.to_rgba_with_alpha(camera.background_opacity),
+ # where it sees from (3D), then its lights: how many, the exposure, the tone mapping,
+ # the bloom
+ eye,
+ [
+ (min(len(lights), LIGHTS) if lights else 2) if three_d else 0,
+ camera.exposure,
+ float(camera.tone_mapping == "agx"),
+ camera.bloom if three_d else 0.0,
+ ],
+ lighting(camera, lights or []) if three_d else [0.0] * (16 * LIGHTS),
+ # its ambient occlusion: how much (0: none), how far around
+ [
+ camera.ambient_occlusion if three_d else 0.0,
+ camera.ambient_occlusion_radius,
+ 0.0,
+ 0.0,
+ ],
+ ]
+ ).astype("<f4")
+ return uniform.tobytes(), projection, three_d
+
+
+def _same_topology(
+ a: "tuple[np.ndarray | tuple[int, int], np.ndarray | None] | None",
+ b: "tuple[np.ndarray | tuple[int, int], np.ndarray | None] | None",
+) -> bool:
+ """Topology and UV values are immutable; retaining them also retains their identity."""
+ if a is None or b is None:
+ return a is b
+ return a[0] is b[0] and a[1] is b[1]
+
+
+@dataclass(slots=True)
+class Growth:
+ """A growing path as the player has it: its key (None until it grows), its curves, its uploads
+ afresh (a new subpath began) and its last subpath's first point."""
+
+ key: int | None
+ curves: int
+ restarts: int = 0
+ start: int = 0
+
+
+Player: type[_engine.Player] | None = getattr(_engine, "Player", None)
+"""The engine's player, which draws with the GPU; None in Pyodide, whose engine has no GPU (a
+film is then recorded as a take, with a `Recorder`)."""
+
+
+class Feeder:
+ """Turns a frame's display list into player records, uploading what appears the first time:
+ to the GPU's player, or to a recorder writing them into a take."""
+
+ def __init__(
+ self, width: int, height: int, player: "_engine.Player | Recorder"
+ ) -> None:
+ self.player = player
+ self.serial = next(_FEEDERS) # records kept on objects are this feeder's
+ self.width, self.height = width, height
+ # key → a resident shape's size: path curves (-1: nothing), cloud points, or
+ # mesh vertices; rows and textures use zero, as only their presence is read
+ self.sizes: dict[int, int] = {}
+ # key → a resident path's subpaths (first curve, end curve, closed)
+ self.structures: dict[int, list[tuple[int, int, bool]]] = {}
+ self.materialized = 0
+ self.pairs: dict[tuple[int, int], list[int]] = {}
+ self.environments: set[int] = (
+ set()
+ ) # the environment pictures the player has, by id
+ # id(texture array) → (the array, its key): kept, so no other array takes its id
+ self.textures: dict[int, tuple[np.ndarray, int]] = {}
+ self.texture_bytes: dict[int, int] = {} # key → bytes, for the budget
+ # id(read-only rows) → (rows, key)
+ self.row_keys: dict[int, tuple[np.ndarray, int]] = {}
+ # id(shape) → (shape, topology, uvs, steps, key, A): the mesh's upload inputs.
+ self.mesh_keys: dict[
+ int,
+ tuple[
+ Shape,
+ np.ndarray | tuple[int, int],
+ np.ndarray | None,
+ int,
+ int,
+ np.ndarray,
+ ],
+ ] = {}
+ # a surface shape's refinement: (shape key, grid) → m (0: not a grid, drawn as faces)
+ self.steps: dict[tuple[int, tuple[int, int]], int] = {}
+ # (id(rows), key) → (rows, a row per vertex of the refined surface `key`)
+ self.expanded: dict[tuple[int, int], tuple[np.ndarray, np.ndarray]] = {}
+ # a growing path, by log — uploaded whole once, then only the curves it gains
+ self.logs: dict[int, Growth] = {}
+ self.frames = 0 # frames made so far
+ # key → the last frame that showed (or uploaded) it
+ self.last_used: dict[int, int] = {}
+ self.swept = 0
+ # sweeps that evicted: a record made since draws only what is resident
+ self.evictions = 0
+ self.latest: list[bytes] = [] # the records of the last frame made
+
+ # ── residency ────────────────────────────────────────────────────────────
+ def shown(self, records: np.ndarray, last: int) -> None:
+ """The keys these records draw stay resident at least until frame `last` + KEEP."""
+ keys = np.concatenate([records[name] for name in (*KEYS, "texture")]).tolist()
+ self.last_used.update(dict.fromkeys(keys, last))
+ self.last_used.pop(0, None)
+
+ def sweep(self) -> None:
+ """Evict what no frame has shown for KEEP frames (frames mark what they show every MARK
+ frames; the film holds back at most one frame). Past BUDGET living bytes (a scene making
+ big new shapes every frame), all the last frame does not show goes at once: the store
+ stays far below wgpu's 4 GiB buffer limit however long the scene."""
+ stored, dead = self.player.stored()
+ pressed = stored - dead + sum(self.texture_bytes.values()) > BUDGET
+ if self.frames - self.swept < SWEEP and not pressed:
+ return
+ for data in self.latest:
+ self.shown(np.frombuffer(data, RECORD), self.frames)
+ self.swept = self.frames
+ keep = 0 if pressed else KEEP
+ stale = [k for k, t in self.last_used.items() if t < self.frames - keep]
+ if not stale:
+ return
+ self.player.evict(stale)
+ self.evictions += 1
+ gone = set(stale)
+ for key in stale:
+ del self.last_used[key]
+ self.sizes.pop(key, None)
+ self.structures.pop(key, None)
+ self.texture_bytes.pop(key, None)
+ # inputs of evicted resources are hashed again if shown again
+ self.textures = {
+ i: kept for i, kept in self.textures.items() if kept[1] not in gone
+ }
+ self.row_keys = {
+ i: kept for i, kept in self.row_keys.items() if kept[1] not in gone
+ }
+ self.mesh_keys = {
+ i: kept for i, kept in self.mesh_keys.items() if kept[4] not in gone
+ }
+ self.pairs = {
+ ab: keys for ab, keys in self.pairs.items() if gone.isdisjoint(keys)
+ }
+
+ # ── uploads ──────────────────────────────────────────────────────────────
+ def grown(self, shape: Shape) -> tuple[int, np.ndarray] | None:
+ """A growing path (a prefix of a log seen growing): uploaded whole once, then only the curves it
+ gains. None at first sight: a log that never grows is an ordinary shape."""
+ log = shape.log
+ assert log is not None
+ points = shape.array
+ curves = len(points) // 4
+ state = self.logs.get(log.id)
+ if state is None:
+ self.logs[log.id] = Growth(None, curves)
+ return None
+ key = state.key
+ if key is None and curves == state.curves:
+ return None # not grown (yet)
+ if key is not None and key in self.sizes and curves > state.curves:
+ have = state.curves
+ continuing = (
+ len(subpath_ranges(points[have * 4 - 4 : curves * 4], 1e-6)) == 1
+ )
+ # no break: the last subpath goes on (closed or not, as it now ends)
+ if continuing:
+ closed = bool(
+ np.allclose(points[state.start], points[curves * 4 - 1], atol=1e-6)
+ )
+ tail = np.ascontiguousarray(points[have * 4 : curves * 4], "<f8")
+ self.player.grow_path(key, tail.tobytes(), closed)
+ state.curves = curves
+ self.sizes[key] = curves
+ *before, (first, _, _) = self.structures[key]
+ self.structures[key] = [*before, (first, curves, closed)]
+ else:
+ key = None # a new subpath began: upload afresh
+ if key is None or key not in self.sizes:
+ restarts = state.restarts
+ key = digest(
+ b"log", log.id.to_bytes(8, "little"), restarts.to_bytes(8, "little")
+ )
+ ranges = structure(points)
+ if not ranges:
+ return None
+ self.player.add_path(key, *control(points, ranges), centroid_area(points))
+ self.sizes[key], self.structures[key] = curves, ranges
+ self.logs[log.id] = Growth(key, curves, restarts + 1, ranges[-1][0] * 4)
+ self.last_used[key] = self.frames
+ return key, IDENTITY
+
+ def path(self, shape: Shape) -> tuple[int, np.ndarray]:
+ """(key, A): the shape's affine class, uploaded once, and where it is placed — or, for
+ a path that grows, the path itself (see `grown`)."""
+ if shape.log is not None and (placed := self.grown(shape)) is not None:
+ return placed
+ key, canonical, a = shape.affine
+ if key not in self.sizes:
+ self.last_used[key] = self.frames
+ ranges = structure(canonical)
+ if not ranges:
+ self.sizes[key] = -1
+ return key, a
+ self.player.add_path(
+ key, *control(canonical, ranges), centroid_area(canonical)
+ )
+ self.sizes[key], self.structures[key] = len(canonical) // 4, ranges
+ return key, a
+
+ def pair(self, a: Shape, b: Shape) -> list[tuple[int, np.ndarray]]:
+ """Keys and placements of a morph pair: the classes themselves if their subpaths agree, else
+ both uploaded again with the union of their subpaths (once per pair)."""
+ (ka, aa), (kb, ab) = self.path(a), self.path(b)
+ sa, sb = self.structures.get(ka), self.structures.get(kb)
+ if sa is None or sb is None or sa == sb:
+ return [
+ (ka, aa),
+ (kb, ab),
+ ] # (a shape that draws nothing: not drawn as a pair)
+ if (ka, kb) not in self.pairs:
+ shared = union(sa, sb)
+ keys = []
+ for tag, points in ((1, a.affine[1]), (2, b.affine[1])):
+ key = digest(f"{ka}:{kb}:{tag}".encode())
+ self.last_used[key] = self.frames
+ self.player.add_path(
+ key, *control(points, shared), centroid_area(points)
+ )
+ self.sizes[key], self.structures[key] = len(points) // 4, shared
+ keys.append(key)
+ self.pairs[(ka, kb)] = keys
+ return list(zip(self.pairs[(ka, kb)], (aa, ab), strict=True))
+
+ def points(self, shape: Shape) -> tuple[int, np.ndarray]:
+ form, array, a = shape.affine
+ key = digest(b"points", form.to_bytes(8, "little"))
+ if key not in self.sizes:
+ self.last_used[key] = self.frames
+ self.player.add_points(
+ key,
+ np.hstack([array, np.zeros((len(array), 1))]).astype("<f4").tobytes(),
+ )
+ self.sizes[key] = len(array)
+ return key, a
+
+ def surface_steps(self, shape: Shape, grid: tuple[int, int] | None) -> int:
+ """A surface shape's refinement m (0: not a surface's grid — drawn as its faces), once
+ per shape: its own size decides, not where a frame puts it (a morph keeps its m).
+ """
+ if grid is None:
+ return 0
+ known = self.steps.get((shape.key, grid))
+ if known is None:
+ _, array, a = shape.affine
+ g = array.reshape(grid[0] + 1, grid[1] + 1, -1)
+ known = surface_steps(g, a[:, :3])
+ if len(self.steps) > 1 << 12:
+ self.steps.clear()
+ self.steps[(shape.key, grid)] = known
+ return known
+
+ def mesh(
+ self,
+ shape: Shape,
+ topology: np.ndarray | tuple[int, int],
+ uvs: np.ndarray | None,
+ steps: int = 0,
+ ) -> tuple[int, np.ndarray]:
+ """Upload explicit triangles or lower a sample lattice to refined spline cells."""
+ grid = topology if isinstance(topology, tuple) else None
+ steps = steps if grid is not None else 0
+ known = self.mesh_keys.get(id(shape))
+ if (
+ known is not None
+ and known[0] is shape
+ and known[1] is topology
+ and known[2] is uvs
+ and known[3] == steps
+ and known[4] in self.sizes
+ ):
+ return known[4], known[5]
+ uv = (
+ np.zeros((len(shape.array), 2))
+ if uvs is None
+ else np.asarray(uvs, dtype=float)
+ )
+ form, array, a = shape.affine
+ if isinstance(topology, tuple):
+ indices = b"grid" + struct.pack("<3I", *topology, steps)
+ else:
+ tri = np.ascontiguousarray(topology, dtype="<u4")
+ indices = b"triangles" + tri.tobytes()
+ key = digest(form.to_bytes(8, "little"), indices, uv.tobytes())
+ if len(self.mesh_keys) > 1 << 12:
+ self.mesh_keys.clear()
+ self.mesh_keys[id(shape)] = (shape, topology, uvs, steps, key, a)
+ if key not in self.sizes:
+ self.last_used[key] = self.frames
+ block = outline = 0
+ if grid is not None:
+ g = np.hstack([array, uv]).reshape(grid[0] + 1, grid[1] + 1, -1)
+ points, normals, faces, block = refine_surface(g, steps)
+ array, uv, tri = points[:, :3], points[:, 3:], faces.astype("<u4")
+ outline = 4 * steps + 1
+ else:
+ normals = None
+ self.player.add_mesh(
+ key,
+ np.ascontiguousarray(array, "<f8").tobytes(),
+ np.ascontiguousarray(uv, "<f8").tobytes(),
+ (
+ b""
+ if normals is None
+ else np.ascontiguousarray(normals, "<f8").tobytes()
+ ),
+ tri.tobytes(),
+ outline,
+ block,
+ )
+ self.sizes[key] = len(array)
+ return key, a
+
+ def per_vertex(self, rows: np.ndarray, n: int, key: int, faces: int) -> np.ndarray:
+ """A mesh's rows, one per vertex the player draws: each lattice cell's paint row
+ repeats on every vertex of its refined block. Zero faces means an ordinary mesh.
+ """
+ count = faces or n
+ rows = rows if len(rows) == count else stretch_array(rows, count)
+ if not faces:
+ return rows
+ known = self.expanded.get((id(rows), key))
+ if known is not None and known[0] is rows:
+ return known[1]
+ block = self.sizes[key] // faces
+ out = np.repeat(rows, block, axis=0)
+ out.flags.writeable = False
+ if len(self.expanded) > 1 << 10:
+ self.expanded.clear()
+ self.expanded[(id(rows), key)] = (rows, out)
+ return out
+
+ def rows(self, rows: np.ndarray) -> int:
+ known = self.row_keys.get(id(rows))
+ if known is not None and known[0] is rows and known[1] in self.sizes:
+ return known[1] # a paint's rows never change: hashed once
+ data = np.ascontiguousarray(rows, dtype="<f4").tobytes()
+ key = digest(b"rows", data)
+ if not rows.flags.writeable:
+ if len(self.row_keys) > 1 << 12:
+ self.row_keys.clear()
+ self.row_keys[id(rows)] = (rows, key)
+ if key not in self.sizes:
+ self.last_used[key] = self.frames
+ self.player.add_rows(key, data)
+ self.sizes[key] = 0
+ return key
+
+ def lights(self, mobjects: "list[Mobject]") -> "list[Light]":
+ """The lights among a view's mobjects, their environments' pictures uploaded the first
+ time."""
+ lights = lit(mobjects)
+ for light in lights:
+ p = light.picture if isinstance(light, EnvironmentLight) else None
+ if p is not None and p.id not in self.environments:
+ self.player.add_environment(p.id, p.width, p.height, p.rgbe)
+ self.environments.add(p.id)
+ return lights
+
+ def texture(self, pixels: np.ndarray) -> int:
+ known = self.textures.get(id(pixels))
+ if known is not None and known[0] is pixels:
+ return known[1]
+ data = np.ascontiguousarray(pixels, dtype=np.uint8)
+ key = digest(b"texture", str(data.shape).encode(), data.tobytes())
+ if key not in self.sizes:
+ h, w = data.shape[:2]
+ self.player.add_texture(key, w, h, data.tobytes())
+ self.sizes[key] = 0
+ self.texture_bytes[key] = data.nbytes
+ self.last_used[key] = self.frames
+ if len(self.textures) > 1 << 8:
+ self.textures.clear()
+ self.textures[id(pixels)] = (pixels, key)
+ return key
+
+ # ── one frame ────────────────────────────────────────────────────────────
+ def frame(
+ self, camera: "Camera", mobjects: "list[Mobject]"
+ ) -> tuple[bytes, bytes, list[CameraView]]:
+ """(view, records, camera views to draw first) — the arguments of `Player.render`."""
+ self.sweep()
+ self.latest = []
+ cameras: list[CameraView] = []
+ uniform, records = self.view(camera, mobjects, self.width, self.height, cameras)
+ self.frames += 1
+ return uniform, records, cameras
+
+ def camera_view(
+ self,
+ seen_by: "Camera",
+ display: "Mobject",
+ camera: "Camera",
+ mobjects: "list[Mobject]",
+ width: int,
+ height: int,
+ cameras: list[CameraView],
+ ) -> int:
+ """The texture key of what `seen_by` sees — everything but `display` — drawn at the size
+ `display` covers on screen (CE's rule), before the view that shows it."""
+ key = digest(b"camera", id(seen_by).to_bytes(8, "little"))
+ if all(c[0] != key for c in cameras):
+ w = max(1, int(width * display.width / camera.frame_width))
+ h = max(1, int(height * display.height / camera.frame_height))
+ hidden = {id(m) for m in display.get_family()}
+ uniform, records = self.view(
+ seen_by, [m for m in mobjects if id(m) not in hidden], w, h, cameras
+ )
+ cameras.append((key, w, h, uniform, records))
+ return key
+
+ def view(
+ self,
+ camera: "Camera",
+ mobjects: "list[Mobject]",
+ width: int,
+ height: int,
+ cameras: list[CameraView],
+ ) -> tuple[bytes, bytes]:
+ uniform, _, three_d = view(camera, width, height, self.lights(mobjects))
+ fixed = camera.fixed_in_frame_mobjects # read once a view
+ data = b"".join(
+ [
+ r
+ for mob in mobjects
+ if (
+ r := self.record(
+ mob, camera, three_d, mobjects, width, height, cameras, fixed
+ )
+ )
+ ]
+ )
+ if data:
+ self.latest.append(data)
+ if self.frames % MARK == 0:
+ self.shown(np.frombuffer(data, RECORD), self.frames)
+ return uniform, data
+
+ def record(
+ self,
+ mob: "Mobject",
+ camera: "Camera",
+ three_d: bool,
+ mobjects: "list[Mobject]",
+ width: int,
+ height: int,
+ cameras: list[CameraView],
+ fixed: "set[Mobject]",
+ ) -> bytes | None:
+ """One object's record (320 bytes), or None if it draws nothing. It is a function of the
+ object's geometry and paint (values), a mesh's topology (indices or lattice dimensions, with uvs:
+ values too), its camera flags and lighting, so it is kept on the object and remade only
+ when one of them changes (or what it draws was evicted); a camera's picture is remade
+ every frame."""
+ g: Blend = mob._geometry
+ if not g.terms:
+ return None
+ p = mob.paint
+ state = (
+ mob in fixed,
+ bool(p.shade_in_3d and three_d),
+ bool(p.material and three_d),
+ )
+ live = p.texture is not None and not isinstance(p.texture, np.ndarray)
+ topology = (mob._topology, mob.uvs) if isinstance(mob, MeshMobject) else None
+ memo = mob.__dict__.get("_film_record")
+ if (
+ memo is not None
+ and not live
+ and memo[0] == self.serial
+ and memo[1] is g
+ and memo[2] is p
+ and memo[3] == state
+ and _same_topology(memo[7], topology)
+ ):
+ if memo[6] == self.evictions: # nothing evicted since it was made
+ return memo[4]
+ if all(k in self.sizes for k in memo[5]):
+ mob.__dict__["_film_record"] = (*memo[:6], self.evictions, memo[7])
+ return memo[4]
+ made = self.make_record(
+ mob, camera, three_d, mobjects, width, height, cameras, state[0]
+ )
+ if made is None:
+ return None
+ record, keys = made
+ mob.__dict__["_film_record"] = (
+ self.serial,
+ g,
+ p,
+ state,
+ record,
+ keys,
+ self.evictions,
+ topology,
+ )
+ return record
+
+ def make_record(
+ self,
+ mob: "Mobject",
+ camera: "Camera",
+ three_d: bool,
+ mobjects: "list[Mobject]",
+ width: int,
+ height: int,
+ cameras: list[CameraView],
+ fixed: bool,
+ ) -> tuple[bytes, tuple[int, ...]] | None:
+ """(record, the keys it draws) — see `record`; `fixed`: is it fixed in the frame?"""
+ g: Blend = mob._geometry
+ p = mob.paint
+ # key1, key2; fill rows, stroke rows of paint 1, of paint 2; texture, flags
+ head = [0, 0, 0, 0, 0, 0, 0, 0]
+ params = [0.0, 0.0, 0.0, 0.0]
+ gradient_a, gradient_b = [0.0] * 4, [0.0] * 4
+ # a tween's paint is two, mixed by the player (see `Paint.mix`)
+ fill, stroke, background = (
+ p.ends("fill"),
+ p.ends("stroke"),
+ p.ends("background"),
+ )
+ dash = [0.0, 0.0, 0.0, p.mix[2] if p.mix is not None else 0.0]
+ terms = g.terms
+ grid: tuple[int, int] | None = None
+ m = 0
+ for materialized in (False, True):
+ if isinstance(mob, VMobject):
+ keys = [self.path(shape) for _, shape in terms[:2]]
+ if len(terms) == 2:
+ keys = self.pair(terms[0][1], terms[1][1])
+ elif isinstance(mob, PMobject):
+ keys = [self.points(shape) for _, shape in terms[:2]]
+ elif isinstance(mob, MeshMobject):
+ if not materialized:
+ grid = mob.grid
+ steps = [self.surface_steps(shape, grid) for _, shape in terms[:2]]
+ m = max(steps) if min(steps) > 0 else 0
+ keys = [
+ self.mesh(shape, mob._topology, mob.uvs, m)
+ for _, shape in terms[:2]
+ ]
+ else:
+ return None
+ counts = {self.sizes[key] for key, _ in keys}
+ if len(terms) <= 2 and len(counts) == 1 and min(counts) >= 0:
+ break
+ if materialized:
+ return None
+ terms = (Blend.of(mob.points).terms[0],)
+ self.materialized += 1
+ faces = grid[0] * grid[1] if grid is not None and m > 0 else 0
+ if isinstance(mob, VMobject):
+ lo, hi = p.window(g.n // 4)
+ params = [lo, hi, p.stroke_width * 0.01, p.background_width * 0.01]
+ head[7] |= CAPS[p.cap] | JOINTS[p.joint]
+ if p.dash is not None: # a periodic window, in u: (period, duty, phase)
+ curves = g.n // 4
+ dash[:3] = p.dash[0] * curves, p.dash[1], p.dash[2] * curves
+ if max(len(fill[0]), len(stroke[0])) > 1:
+ a, b = mob.get_gradient_start_and_end_points()
+ gradient_a[:3], gradient_b[:3] = a, b
+ if len(fill[0]) > 1:
+ head[2], head[4] = self.rows(fill[0]), self.rows(fill[1])
+ if len(stroke[0]) > 1:
+ head[3], head[5] = self.rows(stroke[0]), self.rows(stroke[1])
+ elif isinstance(mob, PMobject):
+ params[:2] = np.clip(p.trim, 0.0, 1.0)
+ gradient_a[3] = p.stroke_width / 135 # a point's size, in scene units
+ if len(fill[0]) > 1:
+ head[2], head[4] = self.rows(fill[0]), self.rows(fill[1])
+ elif isinstance(mob, MeshMobject):
+ params = [*np.clip(p.trim, 0.0, 1.0), p.stroke_width * 0.01, 0.0]
+ if (
+ len(fill[0]) > 1
+ ): # a color per vertex (the player reads a row per vertex)
+ head[2], head[4] = (
+ self.rows(self.per_vertex(f, g.n, keys[0][0], faces)) for f in fill
+ )
+ if isinstance(p.texture, np.ndarray):
+ head[6] = self.texture(p.texture)
+ if isinstance(mob, ImageMobject):
+ head[7] |= _RECONSTRUCTION[mob.resampling_algorithm]
+ elif p.texture is not None: # a camera: its view is a texture
+ head[6] = self.camera_view(
+ p.texture, mob, camera, mobjects, width, height, cameras
+ )
+ else:
+ return None
+ placed: list[float] = []
+ for i, ((key, a), (matrix, _)) in enumerate(zip(keys, terms[:2], strict=False)):
+ head[i] = key
+ placed += place(matrix, a).ravel().tolist()
+ if len(placed) == 12:
+ placed += NO_TERM
+ if fixed:
+ head[7] |= OVERLAY
+ if p.shade_in_3d and three_d:
+ head[7] |= LIT
+ record = PACKED.pack(
+ *head,
+ *placed,
+ *fill[0][0].tolist(),
+ *stroke[0][0].tolist(),
+ *background[0][0].tolist(),
+ *fill[1][0].tolist(),
+ *stroke[1][0].tolist(),
+ *background[1][0].tolist(),
+ *params,
+ *gradient_a,
+ *gradient_b,
+ *dash,
+ # how its surface reflects the scene's lights (a 3D view's)
+ *(
+ (p.material.metallic, p.material.roughness, p.material.reflectance, 1.0)
+ if p.material is not None and three_d
+ else NO_MATERIAL
+ ),
+ )
+ # the keys it draws: shapes, rows and its texture (what must be resident to reuse it)
+ return record, tuple(k for k in head[:7] if k)
+
+ # ── a pure play, all frames at once ──────────────────────────────────────
+ def tween(
+ self,
+ camera: "Camera",
+ mobjects: "list[Mobject]",
+ leaves: "list[tuple[Mobject, list[Mobject], Path, np.ndarray, np.ndarray]]",
+ ) -> list[tuple[bytes, bytes]]:
+ """(view, records) for every frame of a pure play at once: per leaf and keyframe interval, the
+ two keyframe records are mixed over all its frames (`mix`); a leaf that cannot be mixed is
+ materialized per distinct t. The view is the play's first, unless the play moves the camera.
+ """
+ self.sweep()
+ frames = len(leaves[0][3]) if leaves else 0
+ uniform, _, three_d = view(
+ camera, self.width, self.height, self.lights(mobjects)
+ )
+ views = self.views(camera, mobjects, leaves, frames)
+ fixed = camera.fixed_in_frame_mobjects # read once a play
+ args = (camera, three_d, mobjects, self.width, self.height, [], fixed)
+ base = [unpack(self.record(mob, *args)) for mob in mobjects]
+ rows = np.zeros((frames, len(mobjects)), RECORD)
+ present = np.zeros((frames, len(mobjects)), bool)
+ for k, r in enumerate(base):
+ if r is not None:
+ rows[:, k], present[:, k] = r, True
+ position = {id(mob): k for k, mob in enumerate(mobjects)}
+ drawn = [
+ r for r in base if r is not None
+ ] # a record of every key the play draws
+ for leaf, keys, path, index, t in leaves:
+ k = position.get(id(leaf))
+ if k is None:
+ continue
+ present[index == -2, k] = False # not in the scene yet
+ for interval in dict.fromkeys(index[index >= 0].tolist()):
+ at = np.nonzero(index == interval)[0]
+ a, b = keys[interval], keys[interval + 1]
+ # a frame is a function of its t: each distinct t once (a held stretch is one)
+ distinct = dict.fromkeys(t[at].tolist())
+ ts = np.array(list(distinct))
+ where = np.array(
+ [*map({x: j for j, x in enumerate(distinct)}.get, t[at].tolist())]
+ )
+ mixed = self.mix(a, b, path, ts, args, base[k])
+ if mixed is not None:
+ rows[at, k], present[at, k] = mixed[where], True
+ drawn.append(mixed[0])
+ continue
+ for j, x in enumerate(
+ ts
+ ): # not mixable here: the leaf itself, at each t
+ leaf.interpolate(a, b, float(x), path)
+ r = unpack(self.record(leaf, *args))
+ shown = at[where == j]
+ present[shown, k] = r is not None
+ if r is not None:
+ rows[shown, k] = r
+ drawn.append(r)
+ if drawn:
+ self.shown(np.array(drawn, RECORD), self.frames + frames)
+ self.frames += frames
+ return [
+ (uniform if views is None else views[f], rows[f][present[f]].tobytes())
+ for f in range(frames)
+ ]
+
+ def views(
+ self,
+ camera: "Camera",
+ mobjects: "list[Mobject]",
+ leaves: "list[tuple[Mobject, list[Mobject], Path, np.ndarray, np.ndarray]]",
+ frames: int,
+ ) -> list[bytes] | None:
+ """Each frame's view of a pure play that moves the camera or a light (None if it moves
+ neither): their leaves stepped frame by frame, the view read after each step."""
+ lights = self.lights(mobjects)
+ own = {
+ id(m)
+ for mob in [*camera.get_mobjects_indicating_movement(), *lights]
+ for m in mob.get_family()
+ }
+ moving = [leaf for leaf in leaves if id(leaf[0]) in own]
+ if not moving:
+ return None
+ views: list[bytes] = []
+ for f in range(frames):
+ for leaf, keys, path, index, t in moving:
+ if index[f] >= 0:
+ leaf.interpolate(
+ keys[index[f]], keys[index[f] + 1], float(t[f]), path
+ )
+ views.append(view(camera, self.width, self.height, lights)[0])
+ return views
+
+ def mix(
+ self,
+ a: "Mobject",
+ b: "Mobject",
+ path: "Path",
+ t: np.ndarray,
+ args: tuple,
+ live: np.void | None,
+ ) -> np.ndarray | None:
+ """The leaf's records between keyframes a and b at every t: shapes by the path's coefficients,
+ paints as the player mixes them (b's is paint 2); None unless both are one-term paths.
+ """
+ if not (isinstance(a, VMobject) and isinstance(b, VMobject)) or live is None:
+ return None
+ ra, rb = unpack(self.record(a, *args)), unpack(self.record(b, *args))
+ if (
+ ra is None
+ or rb is None
+ or ra["key2"]
+ or rb["key2"]
+ or ra["dash"][3] # a paint mixed already
+ or rb["dash"][3]
+ or (ra["fill_rows"] == 0) != (rb["fill_rows"] == 0)
+ or (ra["stroke_rows"] == 0) != (rb["stroke_rows"] == 0)
+ or (
+ ra["material"] != rb["material"]
+ ).any() # (a material's tween: frame by frame)
+ ):
+ return None
+ ga, gb = a._geometry, b._geometry
+ if len(ga.terms) != 1 or len(gb.terms) != 1 or ga.n != gb.n:
+ return None
+ coefficients = [path.coefficients(float(x)) for x in t]
+ ls = np.array([c[0] for c in coefficients])
+ le = np.array([c[1] for c in coefficients])
+ offset = np.array([c[2] for c in coefficients])
+ ma, mb = ra["m1"].astype(float), rb["m1"].astype(float)
+ out = np.empty(len(t), RECORD)
+ out[:] = live
+ if ra["key1"] == rb["key1"]:
+ m = ls @ ma + le @ mb
+ m[:, :, 3] += offset
+ out["key1"], out["m1"], out["key2"] = ra["key1"], m, 0
+ else:
+ keys = [key for key, _ in self.pair(ga.terms[0][1], gb.terms[0][1])]
+ m1, m2 = ls @ ma, le @ mb
+ m1[:, :, 3] += offset
+ out["key1"], out["m1"], out["key2"], out["m2"] = keys[0], m1, keys[1], m2
+ tt = t[:, None]
+ for name in ("fill", "stroke", "background", "fill_rows", "stroke_rows"):
+ out[name], out[name + "2"] = ra[name], rb[name]
+ # a gradient's axis moves with the leaf
+ for name in ("gradient_a", "gradient_b"):
+ out[name][:, :3] = ra[name][:3] * (1 - tt) + rb[name][:3] * tt
+ da, db = ra["dash"][:3].astype(float), rb["dash"][:3].astype(float)
+ out["dash"][:, :3] = ( # as Paint.mixed: dashed ↔ solid at the middle
+ da * (1 - tt) + db * tt if da[0] and db[0] else np.where(tt >= 0.5, db, da)
+ )
+ # the paints' mix, as Paint.mixed: past its ends a color is its end's
+ out["dash"][:, 3] = np.clip(t, 0.0, 1.0)
+ pa, pb = a.paint, b.paint
+ trim = pa.trim[None] * (1 - tt) + pb.trim[None] * tt
+ curves = max(ga.n // 4, 1)
+
+ def window(
+ trims: np.ndarray, pace: tuple[np.ndarray, np.ndarray] | None
+ ) -> np.ndarray:
+ return trims * curves if pace is None else np.interp(trims, *pace)
+
+ # as Paint.mixed: the start's pace (else the end's), the end's at exactly 1
+ out["params"][:, :2] = window(trim, pa.pace if pa.pace is not None else pb.pace)
+ last = t == 1.0
+ if last.any():
+ out["params"][last, :2] = window(trim[last], pb.pace)
+ out["params"][:, 2:] = np.maximum( # as Paint.mixed: no width is < 0
+ ra["params"][2:][None] * (1 - tt) + rb["params"][2:][None] * tt, 0.0
+ )
+ return out
diff --git a/tests/unit/rendering/test_feed.py b/tests/unit/rendering/test_feed.py
new file mode 100644
index 00000000..b745291b
--- /dev/null
+++ b/tests/unit/rendering/test_feed.py
@@ -0,0 +1,640 @@
+"""The feed hands the player each shape as its object defines it, named by its content, and
+keeps the player's store in step with its own books; the player derives what drawing needs.
+
+- An upload is named by its content: `digest` reads its parts as one stream, wherever they are
+ split, tells apart content that differs by a bit, and is never 0, the key no upload may have.
+- A smooth mesh's normals are the player's own: each vertex's is the sum of its faces'
+ (b − a) × (c − a) (`oracles.area_weighted_normals`), to the bit: a lit mesh is drawn exactly
+ as it is with those normals given.
+- The player takes a mesh whose texture coordinates, normals and triangles fit its points,
+ and refuses one whose do not.
+- A record's reveal window is over u, which counts its shape's steps: a path's curves, a
+ cloud's points, a mesh's triangles, a surface's faces.
+- A surface's part uploads the faces it draws, cut from its whole lattice as it draws them.
+- A batch of a reveal's frames has each frame's window, as the frame alone would.
+- A path and a cloud of points drawn in one frame draw as each does alone.
+- Over any run of frames of any mobjects (paths, graded paths, colored clouds and meshes,
+ surfaces, images; moved, copied, recolored, stretched, morphed, turned partway into
+ another shape, cut to a part), idle time, sweeps, and uploads or evictions that fail:
+ what the feed counts resident is what the player holds; nothing is uploaded while it is
+ resident, nothing evicted that is not (a path that draws nothing, an upload that failed),
+ and a key names one content of one kind for good (a shape's affine class: its floats to a
+ class's precision, since the class made again from other points may differ in its last
+ bits); a frame draws only what is resident, a path from paths, a cloud from points, a
+ mesh from meshes, its rows the brush its mobject shows (a row for each vertex of a mesh
+ as sent), its textures the image's pixels; an upload given directly names its content as
+ it is then (a texture is borrowed: by identity); and nothing the caller let go of
+ outlives the sweep that finds its key stale.
+"""
+
+import contextlib
+import gc
+import weakref
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import numpy as np
+import pytest
+from hypothesis import given, settings
+from hypothesis import strategies as st
+from hypothesis.stateful import RuleBasedStateMachine, initialize, invariant, rule
+from tests import oracles
+from tests.scenes import frames, scene_3d
+
+import manimgx as m
+from manimgx._engine import Player, Recorder, digest
+from manimgx.rendering import feed
+
+
+class TestDigest:
+ @given(data=st.binary(max_size=2048), cut=st.integers(0, 2048))
+ def test_it_reads_its_parts_as_one_stream(self, data: bytes, cut: int) -> None:
+ cut = min(cut, len(data))
+ assert digest(data[:cut], data[cut:]) == digest(data) == digest(b"", data, b"")
+
+ @given(
+ data=st.binary(min_size=1, max_size=512),
+ at=st.integers(0),
+ bit=st.integers(0, 7),
+ )
+ def test_it_tells_apart_content_that_differs_by_a_bit(
+ self, data: bytes, at: int, bit: int
+ ) -> None:
+ changed = bytearray(data)
+ changed[at % len(data)] ^= 1 << bit
+ assert digest(bytes(changed)) != digest(data)
+
+ @given(data=st.binary(max_size=512))
+ def test_it_is_never_0(self, data: bytes) -> None:
+ assert digest(data) != 0
+
+
+def bumpy_sphere(seed: int) -> tuple[np.ndarray, np.ndarray]:
+ """A sphere's grid of points, pushed in and out at random, and its triangles."""
+ rng = np.random.default_rng(seed)
+ u, v = np.meshgrid(np.linspace(0, 2 * np.pi, 24), np.linspace(0.2, 2.9, 12))
+ r = 2 + 0.3 * rng.random(u.shape)
+ points = np.stack(
+ [r * np.sin(v) * np.cos(u), r * np.sin(v) * np.sin(u), r * np.cos(v)], -1
+ ).reshape(-1, 3)
+ i, j = np.meshgrid(np.arange(11), np.arange(23), indexing="ij")
+ a, b, c, d = i * 24 + j, (i + 1) * 24 + j, (i + 1) * 24 + j + 1, i * 24 + j + 1
+ triangles = np.concatenate(
+ [np.stack([a, b, c], -1).reshape(-1, 3), np.stack([a, c, d], -1).reshape(-1, 3)]
+ )
+ return points, triangles
+
+
+class GivenNormals:
+ """The player, with a smooth mesh's normals given: the oracle's."""
+
+ def __init__(self, *args: int) -> None:
+ self.player = Player(*args)
+
+ def __getattr__(self, name: str) -> object:
+ return getattr(self.player, name)
+
+ def add_mesh(
+ self,
+ key: int,
+ points: bytes,
+ uvs: bytes,
+ normals: bytes,
+ triangles: bytes,
+ outline: int = 0,
+ block: int = 0,
+ ) -> None:
+ if not normals:
+ p = np.frombuffer(points, "<f8").reshape(-1, 3)
+ t = np.frombuffer(triangles, "<u4").reshape(-1, 3).astype(np.int64)
+ normals = oracles.area_weighted_normals(p, t).tobytes()
+ self.player.add_mesh(key, points, uvs, normals, triangles, outline, block)
+
+
+def picture(seed: int) -> np.ndarray:
+ """The first frame of a lit bumpy sphere, seen from above and aside."""
+ points, triangles = bumpy_sphere(seed)
+
+ def construct(scene: m.ThreeDScene) -> None:
+ scene.set_camera_orientation(phi=60 * m.DEGREES, theta=-50 * m.DEGREES)
+ scene.add(m.MeshMobject(points, triangles, shade_in_3d=True))
+ scene.wait(0.1)
+
+ return frames(scene_3d(construct))[0]
+
+
[email protected](pixel_width=320, pixel_height=180)
[email protected]("seed", [0, 1])
+def test_a_lit_mesh_is_drawn_with_the_normals_its_faces_sum_to(
+ seed: int, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ derived = picture(seed)
+ monkeypatch.setattr(feed, "Player", GivenNormals)
+ given_normals = picture(seed)
+ assert np.array_equal(derived, given_normals)
+ assert derived[..., :3].any() # something was drawn
+
+
+MESHES: dict[str, tuple[dict[str, np.ndarray], bool]] = { # a mesh's changes; taken?
+ "as it is": ({}, True),
+ "with normals": ({"normals": np.ones((4, 3))}, True),
+ "uvs for 3 points of 4": ({"uvs": np.zeros((3, 2))}, False),
+ "normals for 3 points of 4": ({"normals": np.ones((3, 3))}, False),
+ "a point it lacks": ({"triangles": np.array([[0, 1, 4]])}, False),
+ "part of a triangle": ({"triangles": np.array([0, 1, 2, 3])}, False),
+}
+
+
[email protected]("name", MESHES)
+def test_a_mesh_is_taken_if_it_fits_its_points(name: str) -> None:
+ changes, taken = MESHES[name]
+ mesh = {
+ "points": np.zeros((4, 3)),
+ "uvs": np.zeros((4, 2)),
+ "normals": np.zeros((0, 3)),
+ "triangles": np.array([[0, 1, 2], [1, 2, 3]]),
+ } | changes
+
+ def add() -> None:
+ Player(16, 16, 1).add_mesh(
+ 1,
+ np.asarray(mesh["points"], "<f8").tobytes(),
+ np.asarray(mesh["uvs"], "<f8").tobytes(),
+ np.asarray(mesh["normals"], "<f8").tobytes(),
+ np.asarray(mesh["triangles"], "<u4").tobytes(),
+ )
+
+ if taken:
+ add()
+ else:
+ with pytest.raises(ValueError, match="mesh"):
+ add()
+
+
[email protected]("start_paced", [False, True])
[email protected]("end_paced", [False, True])
+def test_batched_reveals_follow_the_same_pace_as_individual_frames(
+ start_paced: bool, end_paced: bool
+) -> None:
+ start = m.VMobject().set_points_as_corners([m.ORIGIN, m.RIGHT, 4 * m.RIGHT])
+ end = start.copy()
+ start.paint = start.paint.but(
+ trim=np.array([0.1, 0.4]),
+ pace=start.reveal_pace() if start_paced else None,
+ )
+ end.paint = end.paint.but(
+ trim=np.array([0.2, 0.7]),
+ pace=(
+ (np.array([0.0, 0.75, 1.0]), np.array([0.0, 1.0, 2.0]))
+ if end_paced
+ else None
+ ),
+ )
+ camera = m.Camera()
+ feeder = feed.Feeder(32, 32, Recorder(32, 32, 10))
+ objects: list[m.Mobject] = [start, end]
+ cameras: list[feed.CameraView] = []
+ fixed: set[m.Mobject] = set()
+ args = (camera, False, objects, 32, 32, cameras, fixed)
+ live = feed.unpack(feeder.record(start, *args))
+ progress = np.array([0.8, 0.0, 0.2, 1.0, 0.5, 0.2, -0.1, 1.2])
+
+ batch = feeder.mix(start, end, m.straight_path(), progress, args, live)
+
+ assert batch is not None
+ expected = np.array(
+ [
+ start.paint.mixed(start.paint, end.paint, float(t)).window(2)
+ for t in progress
+ ],
+ dtype=np.float32,
+ )
+ np.testing.assert_array_equal(batch["params"][:, :2], expected)
+
+
+def record_of(mob: m.Mobject, sink: "Sink | Recorder") -> np.void:
+ """The record a feed of its own makes of a mobject alone, in a 2D view."""
+ feeder = feed.Feeder(32, 32, sink) # ty: ignore[invalid-argument-type]
+ objects: list[m.Mobject] = [mob]
+ made = feed.unpack(
+ feeder.record(mob, m.Camera(), False, objects, 32, 32, [], set())
+ )
+ assert made is not None
+ return made
+
+
[email protected]("trim", [(0.0, 1.0), (0.25, 0.5), (-0.1, 0.0)])
+def test_a_records_window_is_over_its_shapes_steps(trim: tuple[float, float]) -> None:
+ corners = np.array([[0.0, 0, 0], [1.0, 0, 0], [0.0, 1, 0], [1.0, 1, 0]])
+ surface = m.Surface(lambda u, v: np.array([u, v, 0.0]), resolution=(2, 3))
+ shapes: list[tuple[m.Mobject, int]] = [
+ (m.VMobject().set_points_as_corners([m.ORIGIN, m.RIGHT, m.UP]), 2),
+ (m.PMobject().add_points(np.zeros((8, 3))), 8),
+ (m.MeshMobject(corners, np.array([[0, 1, 2], [1, 3, 2], [0, 1, 3]])), 3),
+ (surface, 6),
+ ]
+ for mob, steps in shapes:
+ mob.paint = mob.paint.but(trim=np.array(trim))
+ window = record_of(mob, Recorder(32, 32, 10))["params"][:2]
+ np.testing.assert_allclose(window, np.array(trim) * steps, rtol=1e-6)
+
+
+def test_a_surfaces_part_uploads_its_faces_as_its_whole_lattice_draws_them() -> None:
+ whole = m.Surface(
+ lambda u, v: np.array([u, v, u * v]), resolution=(4, 3)
+ ) # 12 faces
+ part = whole.copy().pointwise_become_partial(whole, 0.25, 0.5) # faces 3 to 6
+ sinks = Sink(), Sink()
+ windows = [
+ record_of(mob, sink)["params"][:2] for mob, sink in zip((whole, part), sinks)
+ ]
+ uploads = [
+ next(sink.parts[key] for key, kind in sink.kinds.items() if kind == "mesh")
+ for sink in sinks
+ ]
+ (points, _), _, (normals, _), (triangles, _), (sizes, _) = uploads[0]
+ outline, block = (int(x) for x in sizes.split())
+ (p, _), _, (n, _), (t, _), (part_sizes, _) = uploads[1]
+ assert part_sizes == sizes
+
+ def floats(data: bytes) -> np.ndarray:
+ return np.frombuffer(data, "<f8").reshape(-1, 3)
+
+ drawn = slice(3 * block, 6 * block)
+ np.testing.assert_array_equal(floats(p), floats(points)[drawn])
+ np.testing.assert_array_equal(floats(n), floats(normals)[drawn])
+ every = np.frombuffer(triangles, "<u4")
+ per = len(every) // 12 # a face's triangles' indices
+ np.testing.assert_array_equal(
+ np.frombuffer(t, "<u4"), every[3 * per : 6 * per] - 3 * block
+ )
+ assert outline > 2
+ assert tuple(windows[0]) == (0.0, 12.0)
+ assert tuple(windows[1]) == (0.0, 3.0) # u counts the faces it draws
+
+
[email protected]("points_first", [False, True])
[email protected]("n", [3, 4])
+def test_public_path_and_point_cloud_draw_independently_in_one_frame(
+ points_first: bool,
+ n: int,
+) -> None:
+ points = np.array(
+ [[-0.5, -0.5, 0.0], [-0.5, 0.5, 0.0], [0.5, 0.5, 0.0], [0.5, -0.5, 0.0]]
+ )[:n]
+ path = m.VMobject(color=m.BLUE, stroke_width=8).set_points(points).shift(2 * m.LEFT)
+ cloud = (
+ m.PMobject(stroke_width=20).add_points(points, color=m.RED).shift(2 * m.RIGHT)
+ )
+ camera = m.Camera()
+
+ def picture(objects: list[m.Mobject]) -> np.ndarray:
+ player = Player(160, 90)
+ feeder = feed.Feeder(160, 90, player)
+ return np.frombuffer(
+ player.render(*feeder.frame(camera, objects)), np.uint8
+ ).reshape(90, 160, 4)
+
+ alone_path, alone_cloud = picture([path]), picture([cloud])
+ together = picture([cloud, path] if points_first else [path, cloud])
+ assert alone_cloud[:, 80:, :3].any()
+ if n == 4:
+ assert alone_path[:, :80, :3].any()
+ np.testing.assert_array_equal(together[:, :80], alone_path[:, :80])
+ np.testing.assert_array_equal(together[:, 80:], alone_cloud[:, 80:])
+
+
+# ── residency ──────────────────────────────────────────────────────────────────────────
+class Injected(RuntimeError):
+ """A failure the test asked the player for."""
+
+
+type Part = tuple[bytes, str | None] # an upload's part, and the type of its floats
+
+
+def same(a: list[Part], b: list[Part]) -> bool:
+ """Whether two uploads are one content: their parts the same bytes, their floats to a
+ shape class's precision (1e-9 of their size; a float32 part, to its own)."""
+ if [t for _, t in a] != [t for _, t in b]:
+ return False
+ for (x, kind), (y, _) in zip(a, b, strict=True):
+ if kind is None or len(x) != len(y):
+ if x != y:
+ return False
+ continue
+ u, v = np.frombuffer(x, kind), np.frombuffer(y, kind)
+ scale = 1 + float(np.abs(u).max(initial=0))
+ if not np.allclose(
+ u, v, rtol=0, atol=(1e-9 if kind == "<f8" else 1e-6) * scale
+ ):
+ return False
+ return True
+
+
+class Sink:
+ """The engine's take recorder, with the test's own books: what is resident under each
+ key, what each key was first uploaded with, and a failure on demand."""
+
+ def __init__(self) -> None:
+ self.engine = Recorder(32, 32, 10)
+ self.resident: dict[int, bytes] = {}
+ self.named: dict[int, bytes] = {}
+ self.parts: dict[int, list[Part]] = {}
+ self.kinds: dict[int, str] = {} # what each key was uploaded as
+ self.vertices: dict[int, int] = {} # a mesh's vertex count, as sent
+ self.failing: set[str] = set()
+
+ def _add(self, kind: str, key: int, parts: list[Part], *args: object) -> None:
+ if kind in self.failing:
+ self.failing.discard(kind)
+ raise Injected(kind)
+ assert key not in self.resident, f"{kind} {key:x} uploaded while resident"
+ assert same(self.parts.setdefault(key, parts), parts), f"{key:x}: two contents"
+ assert self.kinds.setdefault(key, kind) == kind, f"{key:x}: two kinds"
+ content = b"".join(part for part, _ in parts)
+ self.named.setdefault(key, content)
+ getattr(self.engine, "add_" + kind)(key, *args)
+ self.resident[key] = content
+
+ def add_path(
+ self, key: int, points: bytes, subpaths: bytes, ca: list[float]
+ ) -> None:
+ self._add(
+ "path", key, [(points, "<f8"), (subpaths, None)], points, subpaths, ca
+ )
+
+ def add_points(self, key: int, vertices: bytes) -> None:
+ self._add("points", key, [(vertices, "<f4")], vertices)
+
+ def add_mesh(self, key: int, points: bytes, uvs: bytes, normals: bytes,
+ triangles: bytes, outline: int = 0, block: int = 0) -> None: # fmt: skip
+ parts: list[Part] = [(points, "<f8"), (uvs, "<f8"), (normals, "<f8"),
+ (triangles, None), (b"%d %d" % (outline, block), None)] # fmt: skip
+ self._add("mesh", key, parts, points, uvs, normals, triangles, outline, block)
+ self.vertices[key] = len(points) // 24
+
+ def add_rows(self, key: int, rows: bytes) -> None:
+ self._add("rows", key, [(rows, None)], rows)
+
+ def add_texture(self, key: int, width: int, height: int, rgba: bytes) -> None:
+ self._add("texture", key, [(rgba, None)], width, height, rgba)
+
+ def add_environment(self, key: int, width: int, height: int, rgbe: bytes) -> None:
+ self.engine.add_environment(key, width, height, rgbe)
+
+ def grow_path(self, key: int, points: bytes, closed: bool = False) -> None:
+ raise AssertionError("no growing paths here")
+
+ def evict(self, keys: list[int]) -> None:
+ if "evict" in self.failing:
+ self.failing.discard("evict")
+ raise Injected("evict")
+ for key in keys:
+ assert key in self.resident, f"{key:x} evicted, never resident"
+ del self.resident[key]
+ self.engine.evict(keys)
+
+ def stored(self) -> tuple[int, int]:
+ return self.engine.stored()
+
+
+PIXELS = [np.full((2, 2, 4), v, np.uint8) for v in (0, 90, 200)]
+ROWS = [np.linspace(0, 1, 4 * n).reshape(n, 4) for n in (2, 3, 6)]
+FORMS = [
+ m.Square().points, # the square's path as a cloud: one form, two kinds of resource
+ np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0]], float),
+ np.array([[0, 0, 0], [2, 0, 0], [0, 1, 0], [0, 0, 1]], float),
+ np.array([[0, 0, 0], [0, 1, 0], [1, 1, 0], [1, 0, 0]], float),
+]
+# rows given directly: a picture's pixels as floats among them (one bytes, two kinds)
+GIVEN_ROWS = [*ROWS, PIXELS[1].reshape(-1, 4).astype(float)]
+
+
+def mobject(kind: int, variant: int) -> m.Mobject:
+ """A leaf of each kind the feed uploads: a path, a graded path (rows), a cloud with a
+ color per point (rows), a mesh with a color per vertex, a surface with a color per
+ cell, an image (a texture)."""
+ rows = ROWS[variant % len(ROWS)]
+ if kind == 0:
+ return m.RegularPolygon(3 + variant)
+ if kind == 1:
+ return m.Square().set_fill([m.RED, m.BLUE, m.GREEN][: 2 + variant % 2], 1)
+ if kind == 2:
+ form = FORMS[variant % len(FORMS)]
+ cloud = m.PMobject().add_points(form)
+ cloud.paint = cloud.paint.but(fill=np.resize(rows, (len(form), 4)))
+ return cloud
+ if kind == 3:
+ mesh = m.MeshMobject(FORMS[1], np.array([[0, 1, 2]]))
+ mesh.paint = mesh.paint.but(fill=np.resize(rows, (3, 4)))
+ return mesh
+ if kind == 4:
+ surface = m.Surface(
+ lambda u, v: np.array([u, v, 0.2 * variant * u * v]),
+ resolution=(2, 3),
+ checkerboard_colors=False,
+ )
+ surface.paint = surface.paint.but(fill=np.resize(rows, (6, 4)))
+ return surface
+ return m.ImageMobject(PIXELS[variant % len(PIXELS)])
+
+
+def bent(mob: m.Mobject, by: float) -> m.Mobject:
+ return mob.copy().apply_function(lambda p: p + by * p[0] * m.UP)
+
+
+def morph(mob: m.Mobject, alpha: float, twice: bool) -> None:
+ """The mobject partway between two bent copies of itself (`twice`: between two such
+ mixes): a geometry of two terms, or of four."""
+ a, b = bent(mob, 0.3), bent(mob, -0.2)
+ if twice:
+ x, y = a.copy(), b.copy()
+ x.interpolate(a, b, 0.3)
+ y.interpolate(b, bent(mob, 0.5), 0.6)
+ a, b = x, y
+ mob.interpolate(a, b, alpha)
+
+
+def into_a_ring(mob: m.Mobject) -> None:
+ """A path partway into a ring: two shapes whose subpaths differ (a pair to upload)."""
+ if isinstance(mob, m.VMobject):
+ ring, start = m.Annulus(), mob.copy()
+ start.align_data(ring)
+ mob.align_data(ring)
+ mob.interpolate(start, ring, 0.5)
+
+
+EDITS: dict[str, Callable[[m.Mobject, int], object]] = {
+ "move": lambda mob, v: mob.shift(0.25 * m.RIGHT),
+ "recolor": lambda mob, v: (
+ None
+ if isinstance(mob, m.ImageMobject)
+ else mob.set_color(m.ManimColor.from_rgb((v / 5, 0.5, 0.2)))
+ ),
+ "stretch": lambda mob, v: mob.stretch(1 + v / 4, 0),
+ "morph": lambda mob, v: morph(mob, v / 6, twice=v % 2 == 1),
+ "into a ring": lambda mob, v: into_a_ring(mob),
+ "part": lambda mob, v: mob.pointwise_become_partial(mob.copy(), 0.0, 0.4 + v / 10),
+}
+
+
+@dataclass
+class Handed:
+ """An upload made directly: of rows or a texture, its input, and the key it was given."""
+
+ kind: str
+ data: np.ndarray
+ key: int
+
+
+class Residency(RuleBasedStateMachine):
+ @initialize()
+ def begin(self) -> None:
+ self.sink = Sink()
+ self.feeder = feed.Feeder(32, 32, self.sink) # ty: ignore[invalid-argument-type]
+ self.camera = m.Camera()
+ self.pool: list[m.Mobject] = [mobject(k, 0) for k in range(6)]
+ self.held: list[Handed] = [] # the direct uploads whose inputs the test holds
+ self.dropped: list[tuple[weakref.ref[np.ndarray], int]] = []
+
+ @rule(which=st.lists(st.integers(0, 63), min_size=1, max_size=6))
+ def frame(self, which: list[int]) -> None:
+ shown = list(dict.fromkeys(self.pool[i % len(self.pool)] for i in which))
+ try:
+ _, data, _ = self.feeder.frame(self.camera, shown)
+ except Injected:
+ return
+ drawn = [mob for mob in shown if mob.has_points()]
+ records = np.frombuffer(data, feed.RECORD)
+ assert len(records) == len(drawn)
+ for mob, record in zip(drawn, records, strict=True):
+ keys = [int(record[name]) for name in (*feed.KEYS, "texture")]
+ missing = [k for k in keys if k and k not in self.sink.resident]
+ assert not missing, f"a {type(mob).__name__} draws what is not resident"
+ kind = (
+ "path"
+ if isinstance(mob, m.VMobject)
+ else "points"
+ if isinstance(mob, m.PMobject)
+ else "mesh"
+ )
+ shapes = {
+ self.sink.kinds[int(record[k])] for k in ("key1", "key2") if record[k]
+ }
+ assert shapes <= {kind}, f"a {type(mob).__name__} draws {shapes} resources"
+ self.assert_shows(mob, record)
+
+ def assert_shows(self, mob: m.Mobject, record: np.void) -> None:
+ """A record's rows are the brush its mobject shows (each end of a tween's), a row
+ for each vertex of a mesh as sent; an image's texture is its pixels."""
+ resident = self.sink.resident
+ ends = mob.paint.ends("fill")
+ for rows, shape, brush in (("fill_rows", "key1", ends[0]),
+ ("fill_rows2", "key2", ends[1])): # fmt: skip
+ if not (key := int(record[rows])):
+ continue
+ if isinstance(mob, m.MeshMobject): # (one shape: it is both ends')
+ sent = int(record[shape]) or int(record["key1"])
+ assert len(resident[key]) // 16 == self.sink.vertices[sent]
+ else:
+ assert resident[key] == np.ascontiguousarray(brush, "<f4").tobytes()
+ if record["texture"] and isinstance(mob, m.ImageMobject):
+ pixels = np.ascontiguousarray(mob.pixel_array, np.uint8).tobytes()
+ assert resident[int(record["texture"])] == pixels
+
+ @rule(
+ i=st.integers(0, 63),
+ how=st.sampled_from([*EDITS, "another", "copy"]),
+ variant=st.integers(0, 5),
+ )
+ def edit(self, i: int, how: str, variant: int) -> None:
+ k = i % len(self.pool)
+ if how == "another":
+ self.pool[k] = mobject(i % 6, variant)
+ elif how == "copy":
+ self.pool.append(self.pool[k].copy()) # copies share what they draw
+ else:
+ EDITS[how](self.pool[k], variant)
+
+ @rule(frames=st.sampled_from([1, feed.MARK, feed.KEEP, feed.SWEEP]))
+ def idle(self, frames: int) -> None:
+ self.feeder.frames += frames
+
+ @rule(fails=st.booleans())
+ def sweep(self, fails: bool) -> None:
+ """Time enough for a sweep, whose eviction may fail."""
+ self.feeder.frames += feed.SWEEP
+ if fails:
+ self.sink.failing.add("evict")
+ with contextlib.suppress(Injected):
+ self.feeder.sweep()
+ self.sink.failing.discard("evict")
+
+ @rule(kind=st.sampled_from(["path", "points", "mesh", "rows", "texture", "evict"]))
+ def fail_next(self, kind: str) -> None:
+ self.sink.failing.add(kind)
+
+ @rule(which=st.integers(0, 3), readonly=st.booleans(),
+ kind=st.sampled_from(["rows", "texture"])) # fmt: skip
+ def upload(self, which: int, readonly: bool, kind: str) -> None:
+ given = GIVEN_ROWS if kind == "rows" else PIXELS
+ data = given[which % len(given)].copy()
+ data.flags.writeable = not readonly
+ try:
+ key = getattr(self.feeder, kind)(data)
+ except Injected:
+ return
+ content = np.ascontiguousarray(data, "<f4") if kind == "rows" else data
+ assert self.sink.named[key] == content.tobytes()
+ self.held.append(Handed(kind, data, key))
+
+ @rule(i=st.integers(0, 63), change=st.booleans())
+ def again(self, i: int, change: bool) -> None:
+ """An input handed over again, perhaps changed in place first (if it can be)."""
+ if not self.held:
+ return
+ item = self.held[i % len(self.held)]
+ if change and item.data.flags.writeable:
+ item.data.reshape(-1)[0] += 1
+ try:
+ item.key = getattr(self.feeder, item.kind)(item.data)
+ except Injected:
+ return
+ if item.kind == "rows": # rows by content; a texture is borrowed: by identity
+ content = np.ascontiguousarray(item.data, "<f4").tobytes()
+ assert self.sink.named[item.key] == content
+
+ @rule(i=st.integers(0, 63))
+ def let_go(self, i: int) -> None:
+ if self.held:
+ item = self.held.pop(i % len(self.held))
+ self.dropped.append((weakref.ref(item.data), item.key))
+ del item
+
+ @invariant()
+ def its_books_are_the_players(self) -> None:
+ counted = {
+ k for k, n in self.feeder.sizes.items() if n != -1
+ } # -1: draws nothing
+ assert counted <= set(self.sink.resident), "counted resident, but not"
+ assert set(self.sink.resident) <= counted, (
+ "resident, but forgotten: never evicted"
+ )
+
+ def teardown(self) -> None:
+ """With nothing shown for long enough, a sweep forgets every key, and every input let
+ go of is collected: a key in flight (a failed upload's) holds its input until then."""
+ self.held, self.pool = [], []
+ self.sink.failing.clear()
+ self.feeder.frame(
+ self.camera, []
+ ) # a frame of nothing: the last shown holds nothing
+ self.feeder.frames += feed.KEEP + 2 * feed.SWEEP
+ self.feeder.sweep()
+ gc.collect()
+ alive = [key for ref, key in self.dropped if ref() is not None]
+ assert not alive, f"{len(alive)} inputs let go of outlive their keys' sweep"
+
+
+TestResidency = Residency.TestCase
+TestResidency.settings = settings(max_examples=60, stateful_step_count=40)