The animation engine for agents: blazingly fast math and 3D videos with Manim's Python API, on a Rust GPU core.
Python
Fix resource eviction during queued video retries
apoogdk9be411121be5
diff --git a/docs/content/changelog.md b/docs/content/changelog.mdindex 975eb3db..e12f7989 100644--- a/docs/content/changelog.md+++ b/docs/content/changelog.md@@ -33,6 +33,7 @@ The notable changes to ManimGX, release by release. The format follows### Fixed+- Keep resources needed by queued video frames until their transparency retries finish, fixing render failures during cache cleanup ([#16](https://github.com/academa-labs/manimgx/issues/16)).- Preserve the benchmark comparison images' aspect ratios when PyPI narrows the README table.- Credit Filament, whose code the 3D lighting is adapted from, in the README and the wheels' third-party notices.diff --git a/rust/engine/src/export.rs b/rust/engine/src/export.rsindex 22eeefdd..ba7e7954 100644--- a/rust/engine/src/export.rs+++ b/rust/engine/src/export.rs@@ -1,7 +1,7 @@//! A film's video, natively: each frame drawn, converted to NV12 on the GPU where it changed,//! read back and handed to x264 on a thread of its own (see `encode`), muxed into an MP4.-use std::collections::VecDeque;+use std::collections::{HashSet, VecDeque};use std::sync::Arc;use std::sync::atomic::{AtomicBool, Ordering};use std::time::Instant;@@ -89,7 +89,7 @@ impl Player {gpu.device.poll(wgpu::PollType::Poll).map_err(|e| e.to_string())?;let first = export.previous.is_none();let kept = lists.map(|capacity| (frames.clone(), capacity));- export.pending.push_back(Pending { slot, listed, repeat, first, key, kept, capture });+ export.pending.push_back(Pending { slot, listed, repeat, first, key, kept, capture, keys: None });export.previous = frames.into_iter().last();export.drawn += 1;Ok(())@@ -172,6 +172,7 @@ pub(crate) struct Pending {first: bool,key: bool,kept: Option<(Vec<Frame>, u64)>, // a frame composited through the lists, and their capacity+ keys: Option<Vec<u64>>, // retry dependencies, collected only when eviction askscapture: bool, // copy its final successful draw for a simultaneous pixel consumer}@@ -227,6 +228,32 @@ impl Export {})}+ /// Keep uploads a queued retry may still draw, in any of its camera views. Cache each+ /// pending frame's unique keys so repeated pressure does not rescan all its records.+ pub(crate) fn evictable(&mut self, mut keys: Vec<u64>) -> Vec<u64> {+ if keys.is_empty() {+ return keys;+ }+ let candidates: HashSet<u64> = keys.iter().copied().collect();+ let mut blocked = HashSet::new();+ for pending in &mut self.pending {+ if let Some((frames, _)) = &pending.kept {+ let cached = pending.keys.get_or_insert_with(|| {+ let mut unique = HashSet::new();+ for frame in frames {+ for slots in crate::take::slots(bytemuck::cast_slice(&frame.records)) {+ unique.extend(slots.into_iter().filter(|&key| key != 0));+ }+ }+ unique.into_iter().collect()+ });+ blocked.extend(cached.iter().copied().filter(|key| candidates.contains(key)));+ }+ }+ keys.retain(|key| !blocked.contains(key));+ keys+ }+/// Read `slot` back once its frame is converted: its `listed` macroblocks, and the lists'/// count after them.fn map(&self, slot: usize, listed: usize) {diff --git a/rust/engine/src/project.rs b/rust/engine/src/project.rsindex b7356925..401db956 100644--- a/rust/engine/src/project.rs+++ b/rust/engine/src/project.rs@@ -155,7 +155,7 @@ impl Recipe {// a fully grown path's curve window cannot recover its earlier picture.let wanted = grown.partition_point(|&(first, _, _)| first <= frame);if !player.has(key) || *applied > wanted {- player.evict(&[key]);+ player.evict(vec![key]);player.add_path(key, &pack.get(*points)?, &pack.get(*subpaths)?, *centroid_area)?;*applied = 0;}@@ -274,9 +274,8 @@ impl Take {break;}let keys: Vec<u64> = chunk.iter().map(|&(_, k)| k).collect();- player.evict(&keys);- for k in &keys {- used.remove(k);+ for k in player.evict(keys) {+ used.remove(&k);}}}diff --git a/rust/engine/src/python.rs b/rust/engine/src/python.rsindex 1d854c7a..5d1f6eac 100644--- a/rust/engine/src/python.rs+++ b/rust/engine/src/python.rs@@ -104,8 +104,8 @@ impl Player {}#[pyo3(name = "evict")]- fn py_evict(&mut self, keys: Vec<u64>) {- self.evict(&keys);+ fn py_evict(&mut self, keys: Vec<u64>) -> Vec<u64> {+ self.evict(keys)}#[pyo3(name = "stored")]@@ -324,9 +324,9 @@ impl Recorder {self.writer.grow(key, points, closed);}- /// Nothing: a take keeps everything (its player keeps what the frames it shows need).- fn evict(&mut self, keys: Vec<u64>) {- let _ = keys;+ /// The feeder may forget every key: a take keeps the uploads its frames need itself.+ fn evict(&mut self, keys: Vec<u64>) -> Vec<u64> {+ keys}/// (0, 0): a take holds nothing on a GPU (its player keeps what it is sent).diff --git a/rust/engine/src/render.rs b/rust/engine/src/render.rsindex 6345ae01..4dcaa794 100644--- a/rust/engine/src/render.rs+++ b/rust/engine/src/render.rs@@ -2667,11 +2667,17 @@ impl Player {}#[cfg(any(feature = "python", feature = "player"))]- /// Forget shapes, brushes and textures no frame shows any more (unknown keys are ignored);- /// the shapes' space is reused once most of the store is dead.- pub(crate) fn evict(&mut self, keys: &[u64]) {- self.store.evict(keys);- for key in keys {+ /// Forget shapes, brushes and textures, except those queued export retries still need.+ /// Return the accepted keys (unknown keys are ignored); the shapes' space is reused once+ /// most of the store is dead. Refused keys may be offered again after their frames retire.+ pub(crate) fn evict(&mut self, keys: Vec<u64>) -> Vec<u64> {+ #[cfg(feature = "export")]+ let keys = match &mut self.export {+ Some(export) => export.evictable(keys),+ None => keys,+ };+ self.store.evict(&keys);+ for key in &keys {// a texture goes with its key (key 0, the white image, is never a texture's)if *key != 0 {self.images.remove(key);@@ -2679,6 +2685,7 @@ impl Player {self.image_groups.remove(key);}}+ keys}#[cfg(feature = "python")]diff --git a/src/manimgx/_engine.pyi b/src/manimgx/_engine.pyiindex c6b37162..4c5477c2 100644--- a/src/manimgx/_engine.pyi+++ b/src/manimgx/_engine.pyi@@ -61,8 +61,8 @@ class Player:"""Append curves (float64 control points, four per curve) to a path's last subpath;`closed`: whether it now ends where it begins."""- def evict(self, keys: Sequence[int]) -> None:- """Forget shapes, brushes and textures no frame shows any more."""+ def evict(self, keys: Sequence[int]) -> list[int]:+ """Forget resources except those needed by queued export retries; return the accepted keys."""def stored(self) -> tuple[int, int]:"""(bytes in the store's arrays, of which dead): what the arrays sent to the GPU hold."""@@ -186,7 +186,8 @@ class Recorder:self, id: int, width: int, height: int, rgbe: bytes) -> None: ...def grow_path(self, key: int, points: bytes, closed: bool = False) -> None: ...- def evict(self, keys: Sequence[int]) -> None: ...+ def evict(self, keys: Sequence[int]) -> list[int]:+ """Return all keys: the feeder may forget uploads retained by the take itself."""def stored(self) -> tuple[int, int]:"""(0, 0): a take holds nothing on a GPU."""diff --git a/src/manimgx/rendering/feed.py b/src/manimgx/rendering/feed.pyindex 0870213b..dc6cea8c 100644--- a/src/manimgx/rendering/feed.py+++ b/src/manimgx/rendering/feed.py@@ -576,7 +576,8 @@ class Feeder:def sweep(self, pinned: Sequence[bytes] = (), *, pressed: bool = False) -> None:"""Evict what no frame has shown for KEEP frames (frames mark what they show every MARKframes; the film holds back at most one frame). Memory pressure keeps only the latest- frame and the records pinned by the caller, including every pending camera view."""+ frame and the records pinned by the caller, including every pending camera view.+ The player also retains resources its queued export retries still need."""stored, dead = self.player.stored()pressed |= stored - dead + sum(self.texture_bytes.values()) > BUDGETif self.frames - self.swept < SWEEP and not pressed:@@ -592,7 +593,11 @@ class Feeder:# it is only forgottenresident = [k for k in stale if self.sizes.get(k, -1) != -1]if resident:- self.player.evict(resident)+ accepted = set(self.player.evict(resident))+ blocked = set(resident) - accepted+ stale = [key for key in stale if key not in blocked]+ if not stale:+ returnself.evictions += 1gone = set(stale)for key in stale:diff --git a/tests/integration/test_video.py b/tests/integration/test_video.pyindex 2aa3f7b6..11ff7441 100644--- a/tests/integration/test_video.py+++ b/tests/integration/test_video.py@@ -13,6 +13,7 @@ from tests.integration.corpus.run_manimgx import mp4_framesimport manimgx as mfrom manimgx._engine import Player+from manimgx.rendering import feedfrom manimgx.rendering.feed import Feederfrom manimgx.rendering.film import Cut, Frame, X264Preset@@ -148,6 +149,123 @@ def test_captured_exports_preserve_pixels_and_video_across_pending_draws(assert np.abs(picture - frame).mean() < 2.0[email protected](frame_rate=30)[email protected]("pressed", [False, True])[email protected]("resource", ["points", "mesh", "rows", "texture"])+def test_eviction_preserves_queued_transparency_retries(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, resource: str, pressed: bool+) -> None:+ class Recurring(m.ThreeDScene):+ def construct(self) -> None:+ rng = np.random.default_rng(4)+ points = rng.uniform(-3, 3, (60, 3))+ rows = rng.random((60, 4))+ rows[:, 3] = 1+ pixels = rng.integers(0, 256, (16, 32, 4), dtype=np.uint8)+ pixels[:, :, 3] = 255+ cloud = m.PMobject(stroke_width=4).add_points(points, rgbas=rows)+ mesh = m.MeshMobject(points, np.arange(60).reshape(-1, 3))+ image = m.ImageMobject(pixels).scale_to_fit_width(4)+ target = {"points": cloud, "mesh": mesh, "rows": cloud, "texture": image}[+ resource+ ]+ layers = [+ m.MeshMobject(+ np.array([[-8, -5, z], [8, -5, z], [8, 5, z], [-8, 5, z]]),+ np.array([[0, 1, 2], [0, 2, 3]]),+ color=m.BLUE if i % 2 else m.RED,+ fill_opacity=1,+ )+ for i, z in enumerate(np.linspace(-0.2, 0.2, 12))+ ]++ def update(_: m.Mobject) -> None:+ frame = self.film.feeder.frames+ # Reuse an old upload between the feeder's marks, just before its sweep.+ # Twelve transparent layers force a retry after that sweep has run.+ repeated = frame in (5, 235)+ for layer in layers:+ layer.set_fill(opacity=0.2 if frame == 235 else 1)+ if resource in ("points", "mesh"):+ target.points = points if repeated else rng.uniform(-3, 3, (60, 3))+ elif resource == "rows":+ colors = rows if repeated else rng.random((60, 4))+ if not repeated:+ colors[:, 3] = 1+ cloud.fill_rgbas = colors+ else:+ texture = (+ pixels+ if repeated+ else rng.integers(0, 256, pixels.shape, dtype=np.uint8)+ )+ if not repeated:+ texture[:, :, 3] = 255+ texture.flags.writeable = False+ image.paint = image.paint.but(texture=texture)++ target.add_updater(update)+ self.add(*layers, target)+ self.wait(9)++ reference, swept = tmp_path / "reference.mp4", tmp_path / "swept.mp4"+ with monkeypatch.context() as disabled:+ disabled.setattr(feed, "SWEEP", 10_000)+ disabled.setattr(feed, "BUDGET", 1 << 40)+ Recurring().render(reference)+ if pressed:+ monkeypatch.setattr(feed, "BUDGET", 0)+ film = Recurring().render(swept)+ assert film.feeder.evictions > 0+ assert swept.read_bytes() == reference.read_bytes()++[email protected]("auxiliary", [False, True])+def test_retry_resources_become_evictable_after_their_last_pending_frame(+ tmp_path: Path, auxiliary: bool+) -> None:+ player = Player(*SIZE)+ feeder = Feeder(*SIZE, player)+ camera = m.Camera(three_d=True)+ cloud = m.PMobject(stroke_width=4).add_points(+ np.random.default_rng(7).uniform(-3, 3, (20, 3)),+ rgbas=np.random.default_rng(8).random((20, 4)),+ )+ image = m.ImageMobject(np.full((2, 2, 4), 128, np.uint8))+ view, records, _ = feeder.frame(camera, [cloud, image])+ keys = sorted(+ {+ int(row[name])+ for row in np.frombuffer(records, feed.RECORD)+ for name in (*feed.KEYS, "texture")+ if row[name]+ }+ )+ empty_view, empty_records, _ = feeder.frame(camera, [])+ unused = feeder.texture(np.zeros((2, 2, 4), np.uint8))+ player.begin_export(str(tmp_path / "pending.mp4"), 30)+ for _ in range(2):+ cloud.shift(0.1 * m.RIGHT)+ view, records, _ = feeder.frame(camera, [cloud, image])+ if auxiliary:+ player.push(+ empty_view, empty_records, cameras=[(123, *SIZE, view, records)]+ )+ else:+ player.push(view, records)+ # Empty and repeated requests must not discard dependencies cached on the first.+ assert player.evict([]) == []+ assert player.evict(keys[:1]) == []+ assert player.evict([*keys, unused]) == [unused]+ # The ring holds six frames. After five more pushes only the second use is pending.+ for _ in range(5):+ player.push(empty_view, empty_records)+ assert player.evict(keys) == []+ player.push(empty_view, empty_records)+ assert player.evict(keys) == keys+ player.end_export()++@pytest.mark.config(frame_rate=10)@pytest.mark.parametrize("story", ["empty", "static", "hold", "off_grid", "sections", "cut"]diff --git a/tests/unit/rendering/test_feed.py b/tests/unit/rendering/test_feed.pyindex 0d8c19ca..190b1247 100644--- a/tests/unit/rendering/test_feed.py+++ b/tests/unit/rendering/test_feed.py@@ -480,6 +480,7 @@ class Sink:self.kinds: dict[int, str] = {} # what each key was uploaded asself.vertices: dict[int, int] = {} # a mesh's vertex count, as sentself.failing: set[str] = set()+ self.protected: set[int] = set() # resources retained by queued framesdef _add(self, kind: str, key: int, parts: list[Part], *args: object) -> None:if kind in self.failing:@@ -522,14 +523,15 @@ class Sink:def grow_path(self, key: int, points: bytes, closed: bool = False) -> None:raise AssertionError("no growing paths here")- def evict(self, keys: list[int]) -> None:+ def evict(self, keys: list[int]) -> list[int]:if "evict" in self.failing:self.failing.discard("evict")raise Injected("evict")- for key in keys:+ accepted = self.engine.evict([key for key in keys if key not in self.protected])+ for key in accepted:assert key in self.resident, f"{key:x} evicted, never resident"del self.resident[key]- self.engine.evict(keys)+ return accepteddef stored(self) -> tuple[int, int]:return self.engine.stored()@@ -844,6 +846,12 @@ class Residency(RuleBasedStateMachine):self.feeder.sweep()self.sink.failing.discard("evict")+ @rule(which=st.lists(st.integers(0, 63), max_size=6))+ def pending(self, which: list[int]) -> None:+ """Queued frames may retain some resources until a later sweep."""+ keys = list(self.sink.resident)+ self.sink.protected = {keys[i % len(keys)] for i in which} if keys else set()+@rule(kind=st.sampled_from(["path", "points", "mesh", "rows", "texture", "evict"]))def fail_next(self, kind: str) -> None:self.sink.failing.add(kind)@@ -900,6 +908,7 @@ class Residency(RuleBasedStateMachine):go of is collected: a key in flight (a failed upload's) holds its input until then."""self.held, self.pool = [], []self.sink.failing.clear()+ self.sink.protected.clear()self.feeder.frame(self.camera, []) # a frame of nothing: the last shown holds nothing