Skip to content

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

Python

Fix resource eviction during queued video retries

apoogdk9be411121be5
diff --git a/docs/content/changelog.md b/docs/content/changelog.md
index 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.rs
index 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 asks
capture: 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.rs
index 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.rs
index 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.rs
index 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.pyi
index 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.py
index 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 MARK
frames; 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()) > BUDGET
if self.frames - self.swept < SWEEP and not pressed:
@@ -592,7 +593,11 @@ class Feeder:
# it is only forgotten
resident = [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:
+ return
self.evictions += 1
gone = set(stale)
for key in stale:
diff --git a/tests/integration/test_video.py b/tests/integration/test_video.py
index 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_frames
import manimgx as m
from manimgx._engine import Player
+from manimgx.rendering import feed
from manimgx.rendering.feed import Feeder
from 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.py
index 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 as
self.vertices: dict[int, int] = {} # a mesh's vertex count, as sent
self.failing: set[str] = set()
+ self.protected: set[int] = set() # resources retained by queued frames
def _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 accepted
def 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