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.pyindex 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 itertoolsfrom collections.abc import Callable, Sequence+from dataclasses import dataclassfrom typing import TYPE_CHECKING, Self, Unpackimport numpy as np@@ -52,6 +56,7 @@ def _owner(method: Callable[..., object]) -> tuple[Mobject, Callable[..., objectreturn 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. Whenit ends, it finishes and its updater is removed; with `cycle`, it starts over fromits 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.elapsedrun_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 runreturn 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 wasself.max_stroke_width = max_stroke_widthself.cycle_rate = cycle_rateself.back_and_forth = back_and_forth@@ -396,6 +427,7 @@ class AnimatedBoundary(VGroup):self.total_time = 0.0self.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_funcself.dissipating_time = dissipating_timeself.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 tracedself._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 = pointself._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.pynew file mode 100644index 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 outdiff --git a/tests/unit/rendering/test_feed.py b/tests/unit/rendering/test_feed.pynew file mode 100644index 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)