Coverage for src/manimgx/rendering/feed.py: 99%
673 statements
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
1"""Feed the player: shapes once, then one 336-byte record per object and frame.
3A shape is uploaded as its object defines it, and the player derives what drawing needs. A path
4goes as control points in its own space, with its subpaths as curve ranges, so a reveal is a
5window over u = curve index + t, and the player flattens curves at the size they are drawn; a
6mesh goes as its points, texture coordinates and triangles, and the player sums its faces into
7its vertices' normals (unless a surface's spline supplies them). An
8upload is named by content and resource kind (`digest`), so identical resources upload once.
9A record is an object's blend terms (two shape keys, two 3×4 matrices), reveal window, brushes,
10widths and flags; the camera is one 4×4 matrix."""
12import functools
13import itertools
14import struct
15from collections.abc import Iterator, Sequence
16from dataclasses import dataclass
17from typing import TYPE_CHECKING, Protocol
19import numpy as np
21from manimgx import _engine
22from manimgx._engine import digest
23from manimgx.caches import forgets
24from manimgx.constants import CapStyleType, LineJointType
25from manimgx.drawing.geometry import (
26 IDENTITY,
27 Blend,
28 Lattice,
29 Shape,
30 grid_triangles,
31 subpath_ranges,
32)
33from manimgx.drawing.paint import stretch_array
34from manimgx.mobject import MeshMobject, PMobject, VMobject
35from manimgx.mobjects.images import ImageMobject
36from manimgx.mobjects.lights import (
37 EnvironmentLight,
38 Light,
39 PointLight,
40 SpotLight,
41 SunLight,
42)
44if TYPE_CHECKING:
45 from manimgx.drawing.geometry import Path
46 from manimgx.mobject import Mobject
47 from manimgx.scene import Camera
49# a camera's view, drawn into a texture that later views sample by its key:
50# (key, width, height, view, records)
51type CameraView = tuple[int, int, int, bytes, bytes]
53KEEP = 120 # frames a shape stays resident after the last frame that showed it
54SWEEP = 240 # frames between evictions
55MARK = 16 # frames between marking what the frame shows (see `sweep`)
56BUDGET = 768 << 20 # living bytes (shapes, rows, textures) before the stale go at once
57NEAR = 0.05
58ON_3D = 1e-6 # a share of a depth (8 of its f32 steps): a path this near behind a mesh lies on it
59OVERLAY, LIT = 1, 4
60# an image's reconstruction by its resampling algorithm (the player's flags; linear: none)
61NEAREST, CUBIC = 16, 32
62_RECONSTRUCTION = {0: NEAREST, 2: 0, 3: CUBIC}
63# a stroke's style, in the flags from bit 6 (cap | joint << 2): AUTO is a butt cap and a miter
64# joint (a bevel past the miter limit, 10), for every path
65CAPS = {
66 CapStyleType.AUTO: 0,
67 CapStyleType.BUTT: 0,
68 CapStyleType.ROUND: 1 << 6,
69 CapStyleType.SQUARE: 2 << 6,
70}
71JOINTS = {
72 LineJointType.AUTO: 0,
73 LineJointType.MITER: 0,
74 LineJointType.ROUND: 1 << 8,
75 LineJointType.BEVEL: 2 << 8,
76}
77_FEEDERS = itertools.count(1)
78# paint 2 (fill2 … stroke_rows2) is mixed in by dash[3]: a tween's paint, mixed by the player
79RECORD = np.dtype(
80 [
81 ("key1", "<u8"),
82 ("key2", "<u8"),
83 ("fill_rows", "<u8"),
84 ("stroke_rows", "<u8"),
85 ("fill_rows2", "<u8"),
86 ("stroke_rows2", "<u8"),
87 ("texture", "<u8"),
88 ("flags", "<u8"),
89 ("m1", "<f4", (3, 4)),
90 ("m2", "<f4", (3, 4)),
91 ("fill", "<f4", 4),
92 ("stroke", "<f4", 4),
93 ("background", "<f4", 4),
94 ("fill2", "<f4", 4),
95 ("stroke2", "<f4", 4),
96 ("background2", "<f4", 4),
97 ("params", "<f4", 4),
98 ("gradient_a", "<f4", 4),
99 ("gradient_b", "<f4", 4),
100 ("dash", "<f4", 4), # period, duty, phase (u); how far paint 2 is mixed in
101 ("material", "<f4", 4), # metallic, roughness, reflectance; 1 where it has one
102 ]
103)
104assert RECORD.itemsize == 336
105# a record as Python packs it: its 8 integers, its 68 floats
106PACKED = struct.Struct("<8Q68f")
107NO_MATERIAL = (0.0, 0.5, 0.5, 0.0)
108LIGHTS = 8 # the most lights a view takes
109assert PACKED.size == RECORD.itemsize
110NO_TERM = (0.0,) * 12
111KEYS = ("key1", "key2", "fill_rows", "stroke_rows", "fill_rows2", "stroke_rows2")
114def unpack(record: bytes | None) -> np.void | None:
115 """A record's fields (for mixing records of a pure play)."""
116 return None if record is None else np.frombuffer(record, RECORD)[0]
119def place(m: np.ndarray, a: np.ndarray) -> np.ndarray:
120 """m ∘ a for 3×4 affine maps: a shape's placement over its affine class —
121 [L | t] ∘ [A | b] = L·[A | b] + [0 | t]."""
122 out = m[:, :3] @ a
123 out[:, 3] += m[:, 3]
124 return out
127def structure(points: np.ndarray) -> list[tuple[int, int, bool]]:
128 """Subpaths as curve ranges (first curve, end curve, closed), by CE's break rule."""
129 return [(a // 4, b // 4, closed) for a, b, closed in subpath_ranges(points, 1e-6)]
132def union(
133 a: list[tuple[int, int, bool]], b: list[tuple[int, int, bool]]
134) -> list[tuple[int, int, bool]]:
135 """The subpaths of a morph between two aligned shapes: a break wherever either breaks, closed
136 only where both are."""
137 starts = sorted({s for s, _, _ in a} | {s for s, _, _ in b})
138 end = max(e for _, e, _ in a + b)
139 closed_a = {(s, e) for s, e, c in a if c}
140 closed_b = {(s, e) for s, e, c in b if c}
141 spans = list(zip(starts, starts[1:] + [end], strict=True))
142 return [(s, e, (s, e) in closed_a and (s, e) in closed_b) for s, e in spans]
145def control(
146 points: np.ndarray, ranges: list[tuple[int, int, bool]]
147) -> tuple[bytes, bytes]:
148 """(control points, subpaths) of one path shape as the player takes them: float64 x, y, z per
149 control point, four per curve; (first curve, end curve, closed, 0) per subpath."""
150 whole = points[: len(points) // 4 * 4]
151 subpaths = np.array([(c0, c1, int(closed), 0) for c0, c1, closed in ranges], "<u4")
152 return np.ascontiguousarray(whole, "<f8").tobytes(), subpaths.tobytes()
155def centroid_area(points: np.ndarray) -> list[float]:
156 """Mean of the control points and their Newell area vector (one closed polygon)."""
157 nxt = np.roll(points, -1, axis=0)
158 area = np.array(
159 [
160 np.sum((points[:, 1] - nxt[:, 1]) * (points[:, 2] + nxt[:, 2])),
161 np.sum((points[:, 2] - nxt[:, 2]) * (points[:, 0] + nxt[:, 0])),
162 np.sum((points[:, 0] - nxt[:, 0]) * (points[:, 1] + nxt[:, 1])),
163 ]
164 )
165 return [*points.mean(axis=0), *area]
168# ── surfaces: drawn as the C² spline through their samples ─────────────────────────
169#
170# A surface is its samples of func(u, v) on a grid; drawn, it is the tensor-product cubic
171# spline through them (periodic along a direction whose ends meet, not-a-knot otherwise): C²,
172# exact for cubics, O(h⁴) from a smooth func — a coarse grid draws the surface, not flat
173# quads. Each face (a grid cell) is refined into m × m cells of its spline patch. The shape's
174# midpoint deviation estimates m, capped by SURFACE_STEPS; this is not a bound on triangle
175# error (a saddle can have zero midpoint deviation). Normals are the spline's. A face keeps
176# its own vertices, so a checkerboard keeps its sharp
177# cells, and its edge loop (4m + 1 vertices) is its outline.
179# scene units: a quarter pixel at 1080p, the frame 8 units high
180SURFACE_TOLERANCE = 2e-3
181SURFACE_STEPS = 16 # at most, per face and direction
184@forgets
185@functools.cache
186def _derivative(n: int, periodic: bool) -> np.ndarray:
187 """(n × n) tangents, per sample step, of the C² cubic spline through n evenly spaced values:
188 periodic (the last value repeats the first) or not-a-knot (below four values: the
189 polynomial through them)."""
190 if n < 4:
191 few = [
192 [[0.0]],
193 [[-1.0, 1.0]] * 2,
194 [[-1.5, 2, -0.5], [-0.5, 0, 0.5], [0.5, -2, 1.5]],
195 ]
196 return np.array(few[n - 1])
197 k = n - 1 if periodic else n
198 a, b, i = np.zeros((k, k)), np.zeros((k, k)), np.arange(k)
199 # C²: m[i-1] + 4 m[i] + m[i+1] = 3 (p[i+1] − p[i-1])
200 a[i, i], a[i, (i - 1) % k], a[i, (i + 1) % k] = 4.0, 1.0, 1.0
201 b[i, (i + 1) % k], b[i, (i - 1) % k] = 3.0, -3.0
202 if (
203 not periodic
204 ): # not-a-knot: the third derivative is continuous at the second knots
205 a[[0, -1]], b[[0, -1]] = 0.0, 0.0
206 a[0, [0, 2]], b[0, :3] = [1.0, -1.0], [-2.0, 4.0, -2.0]
207 a[-1, [-3, -1]], b[-1, -3:] = [-1.0, 1.0], [2.0, -4.0, 2.0]
208 d = np.linalg.solve(a, b)
209 return np.pad(np.vstack([d, d[:1]]), ((0, 0), (0, 1))) if periodic else d
212def _hermite(x: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
213 """Cubic Hermite bases at x (value at 0, at 1; tangent at 0, at 1) and their slopes."""
214 x2, x3 = x * x, x * x * x
215 value = np.stack([2 * x3 - 3 * x2 + 1, 3 * x2 - 2 * x3, x3 - 2 * x2 + x, x3 - x2])
216 slope = np.stack(
217 [6 * x2 - 6 * x, 6 * x - 6 * x2, 3 * x2 - 4 * x + 1, 3 * x2 - 2 * x]
218 )
219 return value, slope
222def _cells(g: np.ndarray) -> np.ndarray:
223 """Each cell's bicubic Hermite data from the spline through grid `g` ((u + 1) × (v + 1) ×
224 dims): (4, 4, u, v, dims) — [value at s 0, 1; ∂u at s 0, 1] × [the same along t, ∂v].
225 """
226 tol = 1e-7 * (1.0 + np.abs(g[..., :3]).max())
227 du = _derivative(len(g), bool(np.abs(g[0, :, :3] - g[-1, :, :3]).max() <= tol))
228 dv = _derivative(g.shape[1], bool(np.abs(g[:, 0, :3] - g[:, -1, :3]).max() <= tol))
229 gu = np.einsum("ik,kjd->ijd", du, g)
230 data = (
231 (g, np.einsum("jk,ikd->ijd", dv, g)),
232 (gu, np.einsum("jk,ikd->ijd", dv, gu)),
233 )
234 u, v = len(g) - 1, g.shape[1] - 1
235 return np.array(
236 [
237 [
238 data[i // 2][j // 2][i % 2 : u + i % 2, j % 2 : v + j % 2]
239 for j in range(4)
240 ]
241 for i in range(4)
242 ]
243 )
246def _patches(
247 cells: np.ndarray, x: np.ndarray, *, derivatives: bool = True
248) -> tuple[np.ndarray, ...]:
249 """Points, and when requested their derivatives, of every cell at (s, t) ∈ x × x:
250 each (u, v, len(x), len(x), dims)."""
251 value, slope = _hermite(x)
252 along_t = np.einsum("bq,abuvd->auvqd", value, cells)
253 points = np.einsum("ap,auvqd->uvpqd", value, along_t)
254 if not derivatives:
255 return (points,)
256 ds = np.einsum("ap,auvqd->uvpqd", slope, along_t)
257 dt = np.einsum("ap,bq,abuvd->uvpqd", value, slope, cells, optimize=True)
258 return points, ds, dt
261def surface_steps(g: np.ndarray, linear: np.ndarray) -> int:
262 """Estimate cells per face and direction from midpoint deviation after `linear`.
264 SURFACE_TOLERANCE is the target of this estimate, not a guaranteed error bound;
265 refinement is capped at SURFACE_STEPS and midpoint sampling can miss curvature.
266 """
267 mid = _patches(_cells(g[..., :3]), np.array([0.5]), derivatives=False)[0][
268 :, :, 0, 0
269 ]
270 flat = (g[:-1, :-1, :3] + g[1:, :-1, :3] + g[:-1, 1:, :3] + g[1:, 1:, :3]) / 4
271 deviation = float(np.linalg.norm((mid - flat) @ linear.T, axis=-1).max())
272 return int(
273 np.clip(np.ceil(np.sqrt(deviation / SURFACE_TOLERANCE)), 1, SURFACE_STEPS)
274 )
277@forgets
278@functools.cache
279def _face_layout(m: int) -> tuple[np.ndarray, np.ndarray]:
280 """A refined face's vertices, as (p, q) on its (m + 1)² lattice — its edge loop first
281 ((0,0) → (m,0) → (m,m) → (0,m) → (0,0): the face's own loop, 4m + 1 with the first
282 repeated), then its inside — and its 2m² triangles, as indices into them."""
283 loop = [(p, 0) for p in range(m)] + [(m, q) for q in range(m)]
284 loop += [(p, m) for p in range(m, 0, -1)] + [(0, q) for q in range(m, -1, -1)]
285 order = np.array(loop + [(p, q) for p in range(1, m) for q in range(1, m)])
286 index = np.zeros((m + 1, m + 1), dtype=np.int64)
287 distinct = (
288 np.arange(len(order)) != 4 * m
289 ) # the loop's last vertex repeats its first
290 index[order[distinct, 0], order[distinct, 1]] = np.arange(len(order))[distinct]
291 triangles = index.ravel()[grid_triangles(m, m)]
292 order.flags.writeable = triangles.flags.writeable = False
293 return order, triangles
296def refine_surface(
297 g: np.ndarray, m: int
298) -> tuple[np.ndarray, np.ndarray, np.ndarray, int]:
299 """A surface grid drawn: every face's block of the spline's points (any extra columns
300 alike), their normals, the triangles, the block's size."""
301 x = np.linspace(0.0, 1.0, m + 1)
302 cells = _cells(g)
303 points, ds, dt = _patches(cells, x)
304 normal = np.cross(ds[..., :3], dt[..., :3])
305 # where a direction collapses (a pole), the normal a hair inside the face
306 thin = (
307 np.linalg.norm(normal, axis=-1) <= 1e-10 * (1.0 + np.abs(g[..., :3]).max()) ** 2
308 )
309 if thin.any():
310 i, j = np.nonzero(thin.any(axis=(2, 3)))
311 _, ds, dt = _patches(cells[:, :, i, j][:, :, None], 1e-3 + (1.0 - 2e-3) * x)
312 nudged = np.cross(ds[..., :3], dt[..., :3])[0]
313 normal[i, j] = np.where(thin[i, j][..., None], nudged, normal[i, j])
314 order, triangles = _face_layout(m)
315 block, u, v = len(order), len(g) - 1, g.shape[1] - 1
316 selected = order[:, 0] * (m + 1) + order[:, 1]
317 points = np.take(points.reshape(u, v, -1, points.shape[-1]), selected, axis=2)
318 normal = np.take(normal.reshape(u, v, -1, 3), selected, axis=2)
319 return (
320 points.reshape(u * v * block, -1),
321 normal.reshape(u * v * block, 3),
322 (triangles[None] + np.arange(u * v)[:, None, None] * block).reshape(-1, 3),
323 block,
324 )
327def rotation(phi: float, theta: float, gamma: float) -> np.ndarray:
328 """CE's camera orbit: world → camera axes."""
330 def rz(a: float) -> np.ndarray:
331 return np.array(
332 [[np.cos(a), -np.sin(a), 0.0], [np.sin(a), np.cos(a), 0.0], [0.0, 0.0, 1.0]]
333 )
335 c, s = np.cos(-phi), np.sin(-phi)
336 rx = np.array([[1.0, 0.0, 0.0], [0.0, c, -s], [0.0, s, c]])
337 return rz(gamma) @ rx @ rz(-theta - np.pi / 2)
340def linear(rgb: np.ndarray) -> np.ndarray:
341 """sRGB-encoded colors in linear light (what light adds)."""
342 return np.where(rgb <= 0.04045, rgb / 12.92, ((rgb + 0.055) / 1.055) ** 2.4)
345def lighting(camera: "Camera", lights: "list[Light]") -> list[float]:
346 """A view's lights, four vectors each, `LIGHTS` of them (the first ones): where (an ambient
347 light: nowhere; a sun: its direction; a point or spot: its point; an environment: its
348 picture's right) and its kind; its color in linear light times its intensity, and a
349 point's or spot's reach (an environment: its picture's id, 0 the studio); a spot's axis
350 (an environment: its picture's up) and the scale and offset of its cone's falloff,
351 and whether it casts shadows (an environment: its picture's sun, which the engine
352 lights by as a sun of the view's). A scene with no lights has the camera's: a sun
353 from its light source, and a dim ambient light (as Manim's shading always has its light).
354 """
355 if not lights:
356 sun = np.asarray(camera.light_source.get_center(), dtype=float)
357 sun = sun / max(float(np.linalg.norm(sun)), 1e-9)
358 out = [*sun, 1.0, 1.0, 1.0, 1.0, 0.0, *[0.0] * 8] # a white sun
359 out += [
360 0.0,
361 0.0,
362 0.0,
363 0.0,
364 0.1,
365 0.1,
366 0.1,
367 0.0,
368 *[0.0] * 8,
369 ] # an ambient light, 0.1
370 return out + [0.0] * (16 * LIGHTS - len(out))
371 out = []
372 for light in lights[:LIGHTS]:
373 place = np.asarray(light.get_center(), dtype=float)
374 color = [*(linear(light.light_color.to_rgb()) * light.intensity)]
375 if isinstance(light, EnvironmentLight):
376 right, up = light.axes()
377 picture = 0.0 if light.picture is None else float(light.picture.id)
378 out += [
379 *right,
380 4.0,
381 *color,
382 picture,
383 *up,
384 0.0,
385 0.0,
386 float(light.shadows),
387 0,
388 0,
389 ]
390 continue
391 axis, scale, offset = np.zeros(3), 0.0, 0.0
392 if isinstance(light, SunLight):
393 place = place / max(float(np.linalg.norm(place)), 1e-9)
394 if isinstance(light, SpotLight):
395 axis = light.toward - place
396 axis = axis / max(float(np.linalg.norm(axis)), 1e-9)
397 outer = np.cos(light.angle)
398 inner = np.cos(light.angle * (1.0 - light.softness))
399 scale = 1.0 / max(inner - outer, 1e-4)
400 offset = -outer * scale
401 reach = light.radius if isinstance(light, PointLight) else 0.0
402 shadows = isinstance(light, (SunLight, SpotLight)) and light.shadows
403 out += [
404 *place,
405 float(light.kind),
406 *color,
407 reach,
408 *axis,
409 scale,
410 offset,
411 float(shadows), # (the engine fits its shadow map)
412 0.0,
413 0.0,
414 ]
415 return out + [0.0] * (16 * LIGHTS - len(out))
418def lit(mobjects: "list[Mobject]") -> "list[Light]":
419 """The lights among a view's mobjects."""
420 return [m for m in mobjects if isinstance(m, Light)]
423def view(
424 camera: "Camera", width: int, height: int, lights: "list[Light] | None" = None
425) -> tuple[bytes, np.ndarray, bool]:
426 """(uniform bytes, world → clip matrix, 3D?) of a camera; 2D is orthographic, so the painter's
427 order stands. Reads only the camera's mobjects (`get_mobjects_indicating_movement`) and settings,
428 and the view's `lights` (a 3D view's: those that light the mobjects with a material).
429 """
430 hw, hh = camera.frame_width / 2, camera.frame_height / 2
431 center = np.asarray(camera.frame_center, dtype=float)
432 three_d = bool(camera.three_d)
433 overlay = np.diag([1 / hw, 1 / hh, 0.0, 1.0])
434 if three_d:
435 r = rotation(camera.get_phi(), camera.get_theta(), camera.get_gamma())
436 zoom, f = camera.get_zoom(), camera.get_focal_distance()
437 rc = r @ center
438 projection = np.array(
439 [
440 [*(zoom / hw * r[0]), -zoom / hw * rc[0]],
441 [*(zoom / hh * r[1]), -zoom / hh * rc[1]],
442 # reversed Z: depth NEAR / distance (1 at the near plane, 0 at infinity): a
443 # float depth's digits where things are far, as the composite's own depths
444 [0.0, 0.0, 0.0, NEAR / f],
445 [*(-r[2] / f), (f + rc[2]) / f],
446 ]
447 )
448 toward, bias = r[2], ON_3D
449 eye = [*(center + f * r[2]), 1.0]
450 else:
451 eye = [0.0, 0.0, 0.0, 0.0]
452 zoom = 1.0
453 projection = np.array(
454 [
455 [1 / hw, 0, 0, -center[0] / hw],
456 [0, 1 / hh, 0, -center[1] / hh],
457 [0, 0, 0, 0.5],
458 [0, 0, 0, 1.0],
459 ]
460 )
461 toward, bias = np.array([0.0, 0.0, 1.0]), 0.0
462 uniform = np.concatenate(
463 [
464 projection.T.ravel(), # WGSL matrices are column-major
465 overlay.T.ravel(),
466 [width, height, height / camera.frame_height, zoom],
467 [*camera.light_source.get_center(), float(three_d)],
468 [*toward, bias],
469 camera.background_color.to_rgba_with_alpha(camera.background_opacity),
470 # where it sees from (3D), then its lights: how many, the exposure, the tone mapping,
471 # the bloom
472 eye,
473 [
474 (min(len(lights), LIGHTS) if lights else 2) if three_d else 0,
475 camera.exposure,
476 float(camera.tone_mapping == "agx"),
477 camera.bloom if three_d else 0.0,
478 ],
479 lighting(camera, lights or []) if three_d else [0.0] * (16 * LIGHTS),
480 # its ambient occlusion: how much (0: none), how far around
481 [
482 camera.ambient_occlusion if three_d else 0.0,
483 camera.ambient_occlusion_radius,
484 0.0,
485 0.0,
486 ],
487 ]
488 ).astype("<f4")
489 return uniform.tobytes(), projection, three_d
492def _same_topology(
493 a: "tuple[np.ndarray | Lattice, np.ndarray | None] | None",
494 b: "tuple[np.ndarray | Lattice, np.ndarray | None] | None",
495) -> bool:
496 """Topology and UV values are immutable; retaining them also retains their identity."""
497 if a is None or b is None:
498 return a is b
499 return a[0] is b[0] and a[1] is b[1]
502@dataclass(slots=True)
503class Growth:
504 """A growing path as the player has it: its key (None until it grows), its curves, its uploads
505 afresh (a new subpath began) and its last subpath's first point."""
507 key: int | None
508 curves: int
509 restarts: int = 0
510 start: int = 0
513Player: type[_engine.Player] | None = getattr(_engine, "Player", None)
514"""The engine's player, which draws with the GPU; None in Pyodide, whose engine has no GPU (a
515film is then recorded as a take, with a `Recorder`)."""
518class Store(Protocol):
519 """What a feed uploads to, by key: the GPU's player, or a recorder writing a take. It
520 takes each shape, row block, texture and environment once, grows paths, forgets what is
521 evicted, and tells the bytes it holds."""
523 def add_path(
524 self,
525 key: int,
526 points: bytes,
527 subpaths: bytes,
528 centroid_area: Sequence[float],
529 /,
530 ) -> None: ...
531 def add_points(self, key: int, vertices: bytes, /) -> None: ...
532 def add_mesh(
533 self,
534 key: int,
535 points: bytes,
536 uvs: bytes,
537 normals: bytes,
538 triangles: bytes,
539 outline: int,
540 block: int,
541 /,
542 ) -> None: ...
543 def add_rows(self, key: int, rows: bytes, /) -> None: ...
544 def add_texture(
545 self, key: int, width: int, height: int, rgba: bytes, /
546 ) -> None: ...
547 def add_environment(
548 self, id: int, width: int, height: int, rgbe: bytes, /
549 ) -> None: ...
550 def grow_path(self, key: int, points: bytes, closed: bool, /) -> None: ...
551 def evict(self, keys: Sequence[int], /) -> None: ...
552 def held(self) -> int: ...
555class Feeder:
556 """Turns a frame's display list into player records, uploading what appears the first time:
557 to the GPU's player, or to a recorder writing them into a take."""
559 def __init__(self, width: int, height: int, player: Store) -> None:
560 self.player = player
561 self.serial = next(_FEEDERS) # records kept on objects are this feeder's
562 self.width, self.height = width, height
563 # key → a resident shape's size: path curves (-1: nothing), cloud points, or
564 # mesh vertices; rows and textures use zero, as only their presence is read
565 self.sizes: dict[int, int] = {}
566 # key → a resident path's subpaths (first curve, end curve, closed)
567 self.structures: dict[int, list[tuple[int, int, bool]]] = {}
568 self.materialized = 0
569 self.pairs: dict[tuple[int, int], list[int]] = {}
570 self.environments: set[int] = (
571 set()
572 ) # the environment pictures the player has, by id
573 # id(texture array) → (the array, its key): kept, so no other array takes its id
574 self.textures: dict[int, tuple[np.ndarray, int]] = {}
575 # id(read-only rows) → (rows, key)
576 self.row_keys: dict[int, tuple[np.ndarray, int]] = {}
577 # id(shape) → (shape, topology, uvs, steps, key, A): the mesh's upload inputs.
578 self.mesh_keys: dict[
579 int,
580 tuple[
581 Shape,
582 np.ndarray | Lattice,
583 np.ndarray | None,
584 int,
585 int,
586 np.ndarray,
587 ],
588 ] = {}
589 # a surface shape's refinement: (shape key, grid) → m (0: not a grid, drawn as faces)
590 self.steps: dict[tuple[int, tuple[int, int]], int] = {}
591 # (id(rows), key) → (rows, a row per vertex of the refined surface `key`)
592 self.expanded: dict[tuple[int, int], tuple[np.ndarray, np.ndarray]] = {}
593 # a growing path, by log — uploaded whole once, then only the curves it gains
594 self.logs: dict[int, Growth] = {}
595 self.frames = 0 # frames made so far
596 # key → the last frame that showed (or uploaded) it
597 self.last_used: dict[int, int] = {}
598 self.swept = 0
599 # sweeps that evicted: a record made since draws only what is resident
600 self.evictions = 0
601 # the records of the film's last frame made, and of its camera views (not a picture's)
602 self.latest: list[bytes] = []
604 # ── residency ────────────────────────────────────────────────────────────
605 def shown(self, records: np.ndarray, last: int) -> None:
606 """The keys these records draw stay resident at least until frame `last` + KEEP."""
607 keys = np.concatenate([records[name] for name in (*KEYS, "texture")]).tolist()
608 self.last_used.update(dict.fromkeys(keys, last))
609 self.last_used.pop(0, None)
611 def sweep(self, pinned: Sequence[bytes] = (), *, pressed: bool = False) -> None:
612 """Evict what no frame has shown for KEEP frames (frames mark what they show every MARK
613 frames; the film holds back at most one frame). Memory pressure keeps only the latest
614 frame and the records pinned by the caller, including every pending camera view.
615 The player evicts in turn: after the frames sent before, and once its video's frames
616 in flight that may be drawn again are settled."""
617 pressed |= self.player.held() > BUDGET
618 if self.frames - self.swept < SWEEP and not pressed:
619 return
620 for data in (*self.latest, *pinned):
621 self.shown(np.frombuffer(data, RECORD), self.frames)
622 self.swept = self.frames
623 keep = 0 if pressed else KEEP
624 stale = [k for k, t in self.last_used.items() if t < self.frames - keep]
625 if not stale:
626 return
627 # a key whose path draws nothing, or whose upload failed, never reached the player:
628 # it is only forgotten
629 resident = [k for k in stale if self.sizes.get(k, -1) != -1]
630 if resident:
631 self.player.evict(resident)
632 self.evictions += 1
633 gone = set(stale)
634 for key in stale:
635 del self.last_used[key]
636 self.sizes.pop(key, None)
637 self.structures.pop(key, None)
638 # inputs of evicted resources are hashed again if shown again
639 self.textures = {
640 i: kept for i, kept in self.textures.items() if kept[1] not in gone
641 }
642 self.row_keys = {
643 i: kept for i, kept in self.row_keys.items() if kept[1] not in gone
644 }
645 self.mesh_keys = {
646 i: kept for i, kept in self.mesh_keys.items() if kept[4] not in gone
647 }
648 self.pairs = {
649 ab: keys for ab, keys in self.pairs.items() if gone.isdisjoint(keys)
650 }
652 # ── uploads ──────────────────────────────────────────────────────────────
653 def grown(self, shape: Shape) -> tuple[int, np.ndarray] | None:
654 """A growing path (a prefix of a log seen growing): uploaded whole once, then only the curves it
655 gains. None at first sight: a log that never grows is an ordinary shape."""
656 log = shape.log
657 assert log is not None
658 points = shape.array
659 curves = len(points) // 4
660 state = self.logs.get(log.id)
661 if state is None:
662 self.logs[log.id] = Growth(None, curves)
663 return None
664 key = state.key
665 if key is None and curves == state.curves:
666 return None # not grown (yet)
667 if key is not None and key in self.sizes and curves > state.curves:
668 have = state.curves
669 continuing = (
670 len(subpath_ranges(points[have * 4 - 4 : curves * 4], 1e-6)) == 1
671 )
672 # no break: the last subpath goes on (closed or not, as it now ends)
673 if continuing:
674 closed = bool(
675 np.allclose(points[state.start], points[curves * 4 - 1], atol=1e-6)
676 )
677 tail = np.ascontiguousarray(points[have * 4 : curves * 4], "<f8")
678 self.player.grow_path(key, tail.tobytes(), closed)
679 state.curves = curves
680 self.sizes[key] = curves
681 *before, (first, _, _) = self.structures[key]
682 self.structures[key] = [*before, (first, curves, closed)]
683 else:
684 key = None # a new subpath began: upload afresh
685 if key is None or key not in self.sizes:
686 restarts = state.restarts
687 key = digest(
688 b"log", log.id.to_bytes(8, "little"), restarts.to_bytes(8, "little")
689 )
690 ranges = structure(points)
691 if not ranges:
692 return None
693 self.player.add_path(key, *control(points, ranges), centroid_area(points))
694 self.sizes[key], self.structures[key] = curves, ranges
695 self.logs[log.id] = Growth(key, curves, restarts + 1, ranges[-1][0] * 4)
696 self.last_used[key] = self.frames
697 return key, IDENTITY
699 def path(self, shape: Shape) -> tuple[int, np.ndarray]:
700 """(key, A): the shape's affine class, uploaded once, and where it is placed — or, for
701 a path that grows, the path itself (see `grown`)."""
702 if shape.log is not None and (placed := self.grown(shape)) is not None:
703 return placed
704 key, canonical, a = shape.affine
705 if key not in self.sizes:
706 self.last_used[key] = self.frames
707 ranges = structure(canonical)
708 if not ranges:
709 self.sizes[key] = -1
710 return key, a
711 self.player.add_path(
712 key, *control(canonical, ranges), centroid_area(canonical)
713 )
714 self.sizes[key], self.structures[key] = len(canonical) // 4, ranges
715 return key, a
717 def pair(self, a: Shape, b: Shape) -> list[tuple[int, np.ndarray]]:
718 """Keys and placements of a morph pair: the classes themselves if their subpaths agree, else
719 both uploaded again with the union of their subpaths (once per pair)."""
720 (ka, aa), (kb, ab) = self.path(a), self.path(b)
721 sa, sb = self.structures.get(ka), self.structures.get(kb)
722 if sa is None or sb is None or sa == sb:
723 return [
724 (ka, aa),
725 (kb, ab),
726 ] # (a shape that draws nothing: not drawn as a pair)
727 if (ka, kb) not in self.pairs:
728 shared = union(sa, sb)
729 keys = []
730 for tag, points in ((1, a.affine[1]), (2, b.affine[1])):
731 key = digest(f"{ka}:{kb}:{tag}".encode())
732 self.last_used[key] = self.frames
733 self.player.add_path(
734 key, *control(points, shared), centroid_area(points)
735 )
736 self.sizes[key], self.structures[key] = len(points) // 4, shared
737 keys.append(key)
738 self.pairs[(ka, kb)] = keys
739 return list(zip(self.pairs[(ka, kb)], (aa, ab), strict=True))
741 def points(self, shape: Shape) -> tuple[int, np.ndarray]:
742 form, array, a = shape.affine
743 key = digest(b"points", form.to_bytes(8, "little"))
744 if key not in self.sizes:
745 self.last_used[key] = self.frames
746 self.player.add_points(
747 key,
748 np.hstack([array, np.zeros((len(array), 1))]).astype("<f4").tobytes(),
749 )
750 self.sizes[key] = len(array)
751 return key, a
753 def surface_steps(self, shape: Shape, grid: tuple[int, int] | None) -> int:
754 """A surface shape's refinement m (0: not a surface's grid — drawn as its faces), once
755 per shape: its own size decides, not where a frame puts it (a morph keeps its m).
756 """
757 if grid is None:
758 return 0
759 known = self.steps.get((shape.key, grid))
760 if known is None:
761 _, array, a = shape.affine
762 g = array.reshape(grid[0] + 1, grid[1] + 1, -1)
763 known = surface_steps(g, a[:, :3])
764 if len(self.steps) > 1 << 12:
765 self.steps.clear()
766 self.steps[(shape.key, grid)] = known
767 return known
769 def mesh(
770 self,
771 shape: Shape,
772 topology: np.ndarray | Lattice,
773 uvs: np.ndarray | None,
774 steps: int = 0,
775 ) -> tuple[int, np.ndarray]:
776 """Upload explicit triangles or lower a sample lattice to refined spline cells:
777 the faces it draws, cut from its whole lattice's spline."""
778 lattice = topology if isinstance(topology, Lattice) else None
779 steps = steps if lattice is not None else 0
780 known = self.mesh_keys.get(id(shape))
781 if (
782 known is not None
783 and known[0] is shape
784 and known[1] is topology
785 and known[2] is uvs
786 and known[3] == steps
787 and known[4] in self.sizes
788 ):
789 return known[4], known[5]
790 uv = (
791 np.zeros((len(shape.array), 2))
792 if uvs is None
793 else np.asarray(uvs, dtype=float)
794 )
795 form, array, a = shape.affine
796 if lattice is not None:
797 indices = b"grid" + struct.pack("<5I", *lattice, steps)
798 else:
799 tri = np.ascontiguousarray(topology, dtype="<u4")
800 indices = b"triangles" + tri.tobytes()
801 key = digest(form.to_bytes(8, "little"), indices, uv.tobytes())
802 if len(self.mesh_keys) > 1 << 12:
803 self.mesh_keys.clear()
804 self.mesh_keys[id(shape)] = (shape, topology, uvs, steps, key, a)
805 if key not in self.sizes:
806 self.last_used[key] = self.frames
807 block = outline = 0
808 if lattice is not None:
809 u, v, first, end = lattice
810 g = np.hstack([array, uv]).reshape(u + 1, v + 1, -1)
811 points, normals, faces, block = refine_surface(g, steps)
812 drawn = slice(first * block, end * block)
813 per = len(faces) // (u * v) # a face's triangles
814 faces = faces[first * per : end * per] - first * block
815 points, normals = points[drawn], normals[drawn]
816 array, uv, tri = points[:, :3], points[:, 3:], faces.astype("<u4")
817 outline = 4 * steps + 1
818 else:
819 normals = None
820 self.player.add_mesh(
821 key,
822 np.ascontiguousarray(array, "<f8").tobytes(),
823 np.ascontiguousarray(uv, "<f8").tobytes(),
824 (
825 b""
826 if normals is None
827 else np.ascontiguousarray(normals, "<f8").tobytes()
828 ),
829 tri.tobytes(),
830 outline,
831 block,
832 )
833 self.sizes[key] = len(array)
834 return key, a
836 def per_vertex(
837 self, rows: np.ndarray, n: int, key: int, lattice: Lattice | None
838 ) -> np.ndarray:
839 """A mesh's rows, one per vertex the player draws: each drawn lattice cell's paint
840 row repeats on every vertex of its refined block. No lattice: an ordinary mesh's.
841 """
842 count = n if lattice is None else lattice.u * lattice.v
843 rows = rows if len(rows) == count else stretch_array(rows, count)
844 if lattice is None:
845 return rows
846 known = self.expanded.get((id(rows), key))
847 if known is not None and known[0] is rows:
848 return known[1]
849 drawn = rows[lattice.first : lattice.end]
850 out = np.repeat(drawn, self.sizes[key] // max(len(drawn), 1), axis=0)
851 out.flags.writeable = False
852 if len(self.expanded) > 1 << 10:
853 self.expanded.clear()
854 self.expanded[(id(rows), key)] = (rows, out)
855 return out
857 def rows(self, rows: np.ndarray) -> int:
858 known = self.row_keys.get(id(rows))
859 if known is not None and known[0] is rows and known[1] in self.sizes:
860 return known[1] # a paint's rows never change: hashed once
861 data = np.ascontiguousarray(rows, dtype="<f4").tobytes()
862 key = digest(b"rows", data)
863 if not rows.flags.writeable:
864 if len(self.row_keys) > 1 << 12:
865 self.row_keys.clear()
866 self.row_keys[id(rows)] = (rows, key)
867 if key not in self.sizes:
868 self.last_used[key] = self.frames
869 self.player.add_rows(key, data)
870 self.sizes[key] = 0
871 return key
873 def lights(self, mobjects: "list[Mobject]") -> "list[Light]":
874 """The lights among a view's mobjects, their environments' pictures uploaded the first
875 time."""
876 lights = lit(mobjects)
877 for light in lights:
878 p = light.picture if isinstance(light, EnvironmentLight) else None
879 if p is not None and p.id not in self.environments:
880 self.player.add_environment(p.id, p.width, p.height, p.rgbe)
881 self.environments.add(p.id)
882 return lights
884 def texture(self, pixels: np.ndarray) -> int:
885 known = self.textures.get(id(pixels))
886 if known is not None and known[0] is pixels:
887 return known[1]
888 data = np.ascontiguousarray(pixels, dtype=np.uint8)
889 key = digest(b"texture", str(data.shape).encode(), data.tobytes())
890 if key not in self.sizes:
891 h, w = data.shape[:2]
892 self.player.add_texture(key, w, h, data.tobytes())
893 self.sizes[key] = 0
894 self.last_used[key] = self.frames
895 if len(self.textures) > 1 << 8:
896 self.textures.clear()
897 self.textures[id(pixels)] = (pixels, key)
898 return key
900 # ── one frame ────────────────────────────────────────────────────────────
901 def frame(
902 self, camera: "Camera", mobjects: "list[Mobject]"
903 ) -> tuple[bytes, bytes, list[CameraView]]:
904 """(view, records, camera views to draw first) of the film's next frame: the arguments
905 of `Player.render`. It is the latest frame, which the film may hold back (see `sweep`).
906 """
907 uniform, records, cameras = self.picture(camera, mobjects)
908 self.latest = [records, *[c[4] for c in cameras]]
909 if self.frames % MARK == 0:
910 for data in self.latest:
911 self.shown(np.frombuffer(data, RECORD), self.frames)
912 self.frames += 1
913 return uniform, records, cameras
915 def picture(
916 self, camera: "Camera", mobjects: "list[Mobject]"
917 ) -> tuple[bytes, bytes, list[CameraView]]:
918 """(view, records, camera views to draw first) of the world now, drawn at once: not a
919 frame of the film, so the latest frame, which the film may still hold back, stays the
920 one a sweep keeps."""
921 self.sweep()
922 cameras: list[CameraView] = []
923 uniform, records = self.view(camera, mobjects, self.width, self.height, cameras)
924 return uniform, records, cameras
926 def camera_view(
927 self,
928 seen_by: "Camera",
929 display: "Mobject",
930 camera: "Camera",
931 mobjects: "list[Mobject]",
932 width: int,
933 height: int,
934 cameras: list[CameraView],
935 ) -> int:
936 """The texture key of what `seen_by` sees — everything but `display` — drawn at the size
937 `display` covers on screen (CE's rule), before the view that shows it."""
938 key = digest(b"camera", id(seen_by).to_bytes(8, "little"))
939 if all(c[0] != key for c in cameras):
940 w = max(1, int(width * display.width / camera.frame_width))
941 h = max(1, int(height * display.height / camera.frame_height))
942 hidden = {id(m) for m in display.get_family()}
943 uniform, records = self.view(
944 seen_by, [m for m in mobjects if id(m) not in hidden], w, h, cameras
945 )
946 cameras.append((key, w, h, uniform, records))
947 return key
949 def view(
950 self,
951 camera: "Camera",
952 mobjects: "list[Mobject]",
953 width: int,
954 height: int,
955 cameras: list[CameraView],
956 ) -> tuple[bytes, bytes]:
957 uniform, _, three_d = view(camera, width, height, self.lights(mobjects))
958 fixed = camera.fixed_in_frame_mobjects # read once a view
959 data = b"".join(
960 [
961 r
962 for mob in mobjects
963 if (
964 r := self.record(
965 mob, camera, three_d, mobjects, width, height, cameras, fixed
966 )
967 )
968 ]
969 )
970 return uniform, data
972 def record(
973 self,
974 mob: "Mobject",
975 camera: "Camera",
976 three_d: bool,
977 mobjects: "list[Mobject]",
978 width: int,
979 height: int,
980 cameras: list[CameraView],
981 fixed: "set[Mobject]",
982 ) -> bytes | None:
983 """One object's record (336 bytes), or None if it draws nothing. It is a function of the
984 object's geometry and paint (values), a mesh's topology (indices or lattice dimensions, with uvs:
985 values too), its camera flags and lighting, so it is kept on the object and remade only
986 when one of them changes (or what it draws was evicted); a camera's picture is remade
987 every frame."""
988 g: Blend = mob._geometry
989 if not g.terms:
990 return None
991 p = mob.paint
992 state = (
993 mob in fixed,
994 bool(p.shade_in_3d and three_d),
995 bool(p.material and three_d),
996 )
997 live = p.texture is not None and not isinstance(p.texture, np.ndarray)
998 topology = (mob._topology, mob.uvs) if isinstance(mob, MeshMobject) else None
999 memo = mob.__dict__.get("_film_record")
1000 if (
1001 memo is not None
1002 and not live
1003 and memo[0] == self.serial
1004 and memo[1] is g
1005 and memo[2] is p
1006 and memo[3] == state
1007 and _same_topology(memo[7], topology)
1008 ):
1009 if memo[6] == self.evictions: # nothing evicted since it was made
1010 return memo[4]
1011 if all(k in self.sizes for k in memo[5]):
1012 mob.__dict__["_film_record"] = (*memo[:6], self.evictions, memo[7])
1013 return memo[4]
1014 made = self.make_record(
1015 mob, camera, three_d, mobjects, width, height, cameras, state[0]
1016 )
1017 if made is None:
1018 return None
1019 record, keys = made
1020 mob.__dict__["_film_record"] = (
1021 self.serial,
1022 g,
1023 p,
1024 state,
1025 record,
1026 keys,
1027 self.evictions,
1028 topology,
1029 )
1030 return record
1032 def make_record(
1033 self,
1034 mob: "Mobject",
1035 camera: "Camera",
1036 three_d: bool,
1037 mobjects: "list[Mobject]",
1038 width: int,
1039 height: int,
1040 cameras: list[CameraView],
1041 fixed: bool,
1042 ) -> tuple[bytes, tuple[int, ...]] | None:
1043 """(record, the keys it draws) — see `record`; `fixed`: is it fixed in the frame?"""
1044 g: Blend = mob._geometry
1045 p = mob.paint
1046 # key1, key2; fill rows, stroke rows of paint 1, of paint 2; texture, flags
1047 head = [0, 0, 0, 0, 0, 0, 0, 0]
1048 params = [0.0, 0.0, 0.0, 0.0]
1049 gradient_a, gradient_b = [0.0] * 4, [0.0] * 4
1050 # a tween's paint is two, mixed by the player (see `Paint.mix`)
1051 fill, stroke, background = (
1052 p.ends("fill"),
1053 p.ends("stroke"),
1054 p.ends("background"),
1055 )
1056 dash = [0.0, 0.0, 0.0, p.mix[2] if p.mix is not None else 0.0]
1057 terms = g.terms
1058 grid: tuple[int, int] | None = None
1059 m = 0
1060 for materialized in (False, True):
1061 if isinstance(mob, VMobject):
1062 keys = [self.path(shape) for _, shape in terms[:2]]
1063 if len(terms) == 2:
1064 keys = self.pair(terms[0][1], terms[1][1])
1065 elif isinstance(mob, PMobject):
1066 keys = [self.points(shape) for _, shape in terms[:2]]
1067 elif isinstance(mob, MeshMobject):
1068 if not materialized:
1069 grid = mob.grid
1070 steps = [self.surface_steps(shape, grid) for _, shape in terms[:2]]
1071 m = max(steps) if min(steps) > 0 else 0
1072 keys = [
1073 self.mesh(shape, mob._topology, mob.uvs, m)
1074 for _, shape in terms[:2]
1075 ]
1076 else:
1077 return None
1078 counts = {self.sizes[key] for key, _ in keys}
1079 if len(terms) <= 2 and len(counts) == 1 and min(counts) >= 0:
1080 break
1081 if materialized:
1082 return None
1083 terms = (Blend.of(mob.points).terms[0],)
1084 self.materialized += 1
1085 # a surface's lattice, refined (m > 0): its faces are u's steps and own its rows
1086 topology = mob._topology if isinstance(mob, MeshMobject) and m > 0 else None
1087 lattice = topology if isinstance(topology, Lattice) else None
1088 if isinstance(mob, VMobject):
1089 lo, hi = p.window(g.n // 4)
1090 params = [lo, hi, p.stroke_width * 0.01, p.background_width * 0.01]
1091 head[7] |= CAPS[p.cap] | JOINTS[p.joint]
1092 if p.dash is not None: # a periodic window, in u: (period, duty, phase)
1093 curves = g.n // 4
1094 dash[:3] = p.dash[0] * curves, p.dash[1], p.dash[2] * curves
1095 if max(len(fill[0]), len(stroke[0])) > 1:
1096 a, b = mob.get_gradient_start_and_end_points()
1097 gradient_a[:3], gradient_b[:3] = a, b
1098 if len(fill[0]) > 1:
1099 head[2], head[4] = self.rows(fill[0]), self.rows(fill[1])
1100 if len(stroke[0]) > 1:
1101 head[3], head[5] = self.rows(stroke[0]), self.rows(stroke[1])
1102 elif isinstance(mob, PMobject):
1103 params[:2] = p.window(g.n)
1104 # a point's size, in scene units: as wide as a stroke of its width
1105 gradient_a[3] = p.stroke_width * 0.01
1106 if len(fill[0]) > 1:
1107 head[2], head[4] = self.rows(fill[0]), self.rows(fill[1])
1108 else: # a mesh: the first dispatch drew nothing else
1109 steps = len(mob.triangles) // (1 if lattice is None else 2)
1110 params = [*p.window(steps), p.stroke_width * 0.01, 0.0]
1111 if (
1112 len(fill[0]) > 1
1113 ): # a color per vertex (the player reads a row per vertex)
1114 head[2], head[4] = (
1115 self.rows(self.per_vertex(f, g.n, keys[0][0], lattice))
1116 for f in fill
1117 )
1118 if isinstance(p.texture, np.ndarray):
1119 head[6] = self.texture(p.texture)
1120 if isinstance(mob, ImageMobject):
1121 head[7] |= _RECONSTRUCTION[mob.resampling_algorithm]
1122 elif p.texture is not None: # a camera: its view is a texture
1123 head[6] = self.camera_view(
1124 p.texture, mob, camera, mobjects, width, height, cameras
1125 )
1126 placed: list[float] = []
1127 for i, ((key, a), (matrix, _)) in enumerate(zip(keys, terms[:2], strict=False)):
1128 head[i] = key
1129 placed += place(matrix, a).ravel().tolist()
1130 if len(placed) == 12:
1131 placed += NO_TERM
1132 if fixed:
1133 head[7] |= OVERLAY
1134 if p.shade_in_3d and three_d:
1135 head[7] |= LIT
1136 record = PACKED.pack(
1137 *head,
1138 *placed,
1139 *fill[0][0].tolist(),
1140 *stroke[0][0].tolist(),
1141 *background[0][0].tolist(),
1142 *fill[1][0].tolist(),
1143 *stroke[1][0].tolist(),
1144 *background[1][0].tolist(),
1145 *params,
1146 *gradient_a,
1147 *gradient_b,
1148 *dash,
1149 # how its surface reflects the scene's lights (a 3D view's)
1150 *(
1151 (p.material.metallic, p.material.roughness, p.material.reflectance, 1.0)
1152 if p.material is not None and three_d
1153 else NO_MATERIAL
1154 ),
1155 )
1156 # the keys it draws: shapes, rows and its texture (what must be resident to reuse it)
1157 return record, tuple(k for k in head[:7] if k)
1159 # ── a pure play, all frames at once ──────────────────────────────────────
1160 def tween(
1161 self,
1162 camera: "Camera",
1163 mobjects: "list[Mobject]",
1164 leaves: "list[tuple[Mobject, list[Mobject], Path, np.ndarray, np.ndarray]]",
1165 ) -> Iterator[tuple[bytes, bytes]]:
1166 """Mix whole keyframe intervals on the CPU; upload an interval when it first appears.
1168 A leaf that cannot be mixed is materialized when its frame is yielded, so a long
1169 play never makes every future shape resident on the GPU before drawing its first.
1170 """
1171 self.sweep()
1172 frames = len(leaves[0][3]) if leaves else 0
1173 uniform, _, three_d = view(
1174 camera, self.width, self.height, self.lights(mobjects)
1175 )
1176 views = self.views(camera, mobjects, leaves, frames)
1177 fixed = camera.fixed_in_frame_mobjects
1178 args = (camera, three_d, mobjects, self.width, self.height, [], fixed)
1179 base = [unpack(self.record(mob, *args)) for mob in mobjects]
1180 rows = np.zeros((frames, len(mobjects)), RECORD)
1181 present = np.zeros((frames, len(mobjects)), bool)
1182 for k, r in enumerate(base):
1183 if r is not None:
1184 rows[:, k], present[:, k] = r, True
1185 position = {id(mob): k for k, mob in enumerate(mobjects)}
1186 type Interval = tuple[
1187 Mobject, Mobject, Mobject, Path, np.ndarray, np.ndarray, int
1188 ]
1189 type Cached = dict[float, tuple[np.void | None, tuple[int, ...]]]
1190 type Materialize = tuple[
1191 Mobject, Mobject, Mobject, Path, np.ndarray, float, int, Cached
1192 ]
1193 starts: dict[int, list[Interval]] = {}
1194 moving: dict[int, list[Materialize]] = {}
1195 restores: dict[int, list[tuple[Mobject, np.ndarray, int, set[Mobject]]]] = {}
1196 for leaf, keys, path, index, t in leaves:
1197 k = position.get(id(leaf))
1198 if k is None:
1199 continue
1200 present[index == -2, k] = False
1201 initial = None
1202 for interval in dict.fromkeys(index[index >= -1].tolist()):
1203 at = np.nonzero(index == interval)[0]
1204 # A nonmonotone clock can leave an interval and return: its inputs may
1205 # have been evicted while absent, so entering it prepares them again.
1206 for run in np.split(at, np.flatnonzero(np.diff(at) != 1) + 1):
1207 if interval == -1:
1208 if run[0] > 0:
1209 # A clock can return to before the animation began. Keep
1210 # its original CPU state, not its now-unused uploads.
1211 if initial is None:
1212 initial = leaf.copy()
1213 pinned = fixed | {initial} if leaf in fixed else fixed
1214 restores.setdefault(int(run[0]), []).append(
1215 (initial, run, k, pinned)
1216 )
1217 continue
1218 starts.setdefault(int(run[0]), []).append(
1219 (leaf, keys[interval], keys[interval + 1], path, run, t[run], k)
1220 )
1221 for f in range(frames):
1222 self.sweep()
1223 for initial, at, k, pinned in restores.pop(f, ()):
1224 r = unpack(self.record(initial, *args[:-1], pinned))
1225 present[at, k] = r is not None
1226 if r is not None:
1227 rows[at, k] = r
1228 for leaf, a, b, path, at, t, k in starts.pop(f, ()):
1229 distinct = dict.fromkeys(t.tolist())
1230 ts = np.array(list(distinct))
1231 where = np.array([*map({x: j for j, x in enumerate(distinct)}.get, t)])
1232 mixed = self.mix(a, b, path, ts, args, base[k])
1233 if mixed is not None:
1234 rows[at, k], present[at, k] = mixed[where], True
1235 continue
1236 cache: Cached = {}
1237 # A hold has one materialization. Revisited values reuse their records
1238 # while resident, and reconstruct from their keyframes after eviction.
1239 for run in np.split(
1240 np.arange(len(at)), np.flatnonzero(np.diff(where)) + 1
1241 ):
1242 moving.setdefault(int(at[run[0]]), []).append(
1243 (leaf, a, b, path, at[run], float(t[run[0]]), k, cache)
1244 )
1245 for leaf, a, b, path, at, t, k, cache in moving.pop(f, ()):
1246 known = cache.get(t)
1247 if known is None or any(key not in self.sizes for key in known[1]):
1248 leaf.interpolate(a, b, t, path)
1249 r = unpack(self.record(leaf, *args))
1250 keys = (
1251 ()
1252 if r is None
1253 else tuple(
1254 int(r[name]) for name in (*KEYS, "texture") if r[name]
1255 )
1256 )
1257 known = cache[t] = (r, keys)
1258 r = known[0]
1259 present[at, k] = r is not None
1260 if r is not None:
1261 rows[at, k] = r
1262 data = rows[f][present[f]].tobytes()
1263 self.latest = [data]
1264 if self.frames % MARK == 0:
1265 self.shown(np.frombuffer(data, RECORD), self.frames)
1266 self.frames += 1
1267 yield uniform if views is None else views[f], data
1269 def views(
1270 self,
1271 camera: "Camera",
1272 mobjects: "list[Mobject]",
1273 leaves: "list[tuple[Mobject, list[Mobject], Path, np.ndarray, np.ndarray]]",
1274 frames: int,
1275 ) -> list[bytes] | None:
1276 """Each frame's view of a pure play that moves the camera or a light (None if it moves
1277 neither): their leaves stepped frame by frame, the view read after each step."""
1278 lights = self.lights(mobjects)
1279 own = {
1280 id(m)
1281 for mob in [*camera.get_mobjects_indicating_movement(), *lights]
1282 for m in mob.get_family()
1283 }
1284 moving = [leaf for leaf in leaves if id(leaf[0]) in own]
1285 if not moving:
1286 return None
1287 views: list[bytes] = []
1288 for f in range(frames):
1289 for leaf, keys, path, index, t in moving:
1290 if index[f] >= 0:
1291 leaf.interpolate(
1292 keys[index[f]], keys[index[f] + 1], float(t[f]), path
1293 )
1294 views.append(view(camera, self.width, self.height, lights)[0])
1295 return views
1297 def mix(
1298 self,
1299 a: "Mobject",
1300 b: "Mobject",
1301 path: "Path",
1302 t: np.ndarray,
1303 args: tuple,
1304 live: np.void | None,
1305 ) -> np.ndarray | None:
1306 """The leaf's records between keyframes a and b at every t: shapes by the path's coefficients,
1307 paints as the player mixes them (b's is paint 2); None unless both are one-term paths.
1308 """
1309 if not (isinstance(a, VMobject) and isinstance(b, VMobject)) or live is None:
1310 return None
1311 ra, rb = unpack(self.record(a, *args)), unpack(self.record(b, *args))
1312 if (
1313 ra is None
1314 or rb is None
1315 or ra["key2"]
1316 or rb["key2"]
1317 or ra["dash"][3] # a paint mixed already
1318 or rb["dash"][3]
1319 or (ra["fill_rows"] == 0) != (rb["fill_rows"] == 0)
1320 or (ra["stroke_rows"] == 0) != (rb["stroke_rows"] == 0)
1321 or (
1322 ra["material"] != rb["material"]
1323 ).any() # (a material's tween: frame by frame)
1324 ):
1325 return None
1326 ga, gb = a._geometry, b._geometry
1327 if len(ga.terms) != 1 or len(gb.terms) != 1 or ga.n != gb.n:
1328 return None
1329 coefficients = [path.coefficients(float(x)) for x in t]
1330 ls = np.array([c[0] for c in coefficients])
1331 le = np.array([c[1] for c in coefficients])
1332 offset = np.array([c[2] for c in coefficients])
1333 ma, mb = ra["m1"].astype(float), rb["m1"].astype(float)
1334 out = np.empty(len(t), RECORD)
1335 out[:] = live
1336 if ra["key1"] == rb["key1"]:
1337 m = ls @ ma + le @ mb
1338 m[:, :, 3] += offset
1339 out["key1"], out["m1"], out["key2"] = ra["key1"], m, 0
1340 else:
1341 keys = [key for key, _ in self.pair(ga.terms[0][1], gb.terms[0][1])]
1342 m1, m2 = ls @ ma, le @ mb
1343 m1[:, :, 3] += offset
1344 out["key1"], out["m1"], out["key2"], out["m2"] = keys[0], m1, keys[1], m2
1345 tt = t[:, None]
1346 for name in ("fill", "stroke", "background", "fill_rows", "stroke_rows"):
1347 out[name], out[name + "2"] = ra[name], rb[name]
1348 # a gradient's axis moves with the leaf
1349 for name in ("gradient_a", "gradient_b"):
1350 out[name][:, :3] = ra[name][:3] * (1 - tt) + rb[name][:3] * tt
1351 da, db = ra["dash"][:3].astype(float), rb["dash"][:3].astype(float)
1352 out["dash"][:, :3] = ( # as Paint.mixed: dashed ↔ solid at the middle
1353 da * (1 - tt) + db * tt if da[0] and db[0] else np.where(tt >= 0.5, db, da)
1354 )
1355 # the paints' mix, as Paint.mixed: past its ends a color is its end's
1356 out["dash"][:, 3] = np.clip(t, 0.0, 1.0)
1357 pa, pb = a.paint, b.paint
1358 trim = pa.trim[None] * (1 - tt) + pb.trim[None] * tt
1359 curves = max(ga.n // 4, 1)
1361 def window(
1362 trims: np.ndarray, pace: tuple[np.ndarray, np.ndarray] | None
1363 ) -> np.ndarray:
1364 return trims * curves if pace is None else np.interp(trims, *pace)
1366 # as Paint.mixed: the start's pace (else the end's), the end's at exactly 1
1367 out["params"][:, :2] = window(trim, pa.pace if pa.pace is not None else pb.pace)
1368 last = t == 1.0
1369 if last.any():
1370 out["params"][last, :2] = window(trim[last], pb.pace)
1371 out["params"][:, 2:] = np.maximum( # as Paint.mixed: no width is < 0
1372 ra["params"][2:][None] * (1 - tt) + rb["params"][2:][None] * tt, 0.0
1373 )
1374 return out