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

1"""Feed the player: shapes once, then one 336-byte record per object and frame. 

2 

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.""" 

11 

12import functools 

13import itertools 

14import struct 

15from collections.abc import Iterator, Sequence 

16from dataclasses import dataclass 

17from typing import TYPE_CHECKING, Protocol 

18 

19import numpy as np 

20 

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) 

43 

44if TYPE_CHECKING: 

45 from manimgx.drawing.geometry import Path 

46 from manimgx.mobject import Mobject 

47 from manimgx.scene import Camera 

48 

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] 

52 

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") 

112 

113 

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] 

117 

118 

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 

125 

126 

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)] 

130 

131 

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] 

143 

144 

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() 

153 

154 

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] 

166 

167 

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. 

178 

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 

182 

183 

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 

210 

211 

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 

220 

221 

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 ) 

244 

245 

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 

259 

260 

261def surface_steps(g: np.ndarray, linear: np.ndarray) -> int: 

262 """Estimate cells per face and direction from midpoint deviation after `linear`. 

263 

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 ) 

275 

276 

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 

294 

295 

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 ) 

325 

326 

327def rotation(phi: float, theta: float, gamma: float) -> np.ndarray: 

328 """CE's camera orbit: world → camera axes.""" 

329 

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 ) 

334 

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) 

338 

339 

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) 

343 

344 

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)) 

416 

417 

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)] 

421 

422 

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 

490 

491 

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] 

500 

501 

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.""" 

506 

507 key: int | None 

508 curves: int 

509 restarts: int = 0 

510 start: int = 0 

511 

512 

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`).""" 

516 

517 

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.""" 

522 

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: ... 

553 

554 

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.""" 

558 

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] = [] 

603 

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) 

610 

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 } 

651 

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 

698 

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 

716 

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)) 

740 

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 

752 

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 

768 

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 

835 

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 

856 

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 

872 

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 

883 

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 

899 

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 

914 

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 

925 

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 

948 

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 

971 

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 

1031 

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) 

1158 

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. 

1167 

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 

1268 

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 

1296 

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) 

1360 

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) 

1365 

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