Struct StreamPlanner 

pub struct StreamPlanner { /* private fields */ }

Decides what to stream in and out of a fixed-size residency pool.

The planner owns only residency bookkeeping: it never reads or writes a GPU resource. Each frame the driver updates scores, calls plan, and reports completed loads back via mark_resident.

Implementations

impl StreamPlanner

pub fn new(count: usize, load_budget: usize, resident_cap: usize) -> Self

Create a planner tracking count items, all initially Unloaded.

load_budget and resident_cap are both clamped to at least 1 so a zero from a misconfigured asset cannot wedge streaming permanently.

pub fn set_byte_budget(&mut self, budget: Option<u64>)

Set (or clear with None) the total resident-byte budget. None keeps the count-only policy; Some(b) additionally evicts to hold resident bytes at or under b. Off by default so worlds that never set it behave exactly as the count-only planner.

pub fn byte_budget(&self) -> Option<u64>

The active resident-byte budget, or None when byte accounting is off (the count-only policy). For diagnostics.

pub fn len(&self) -> usize

Number of tracked items.

pub fn is_empty(&self) -> bool

Whether the planner tracks no items.

pub fn state(&self, id: usize) -> Option<StreamState>

Residency state of item id, or None if id is out of range.

pub fn set_score(&mut self, id: usize, score: f32)

Set item id’s priority score (lower = loaded sooner / evicted later). Out-of-range ids are ignored.

pub fn touch(&mut self, id: usize, frame: u64)

Record that item id was referenced on frame. Refreshes the LRU tiebreak used when evicting equally-scored resident items.

pub fn mark_resident(&mut self, id: usize, frame: u64, bytes: u64)

Report that a dispatched load for item id has completed and the resource is now on the GPU, occupying bytes of GPU memory. The driver knows the exact resident size at completion (decoded pixel bytes, or vertex + index buffer bytes); bytes may be 0 when the size is unknown or nothing was actually uploaded (e.g. a failed fetch left a placeholder).

pub fn set_blocked(&mut self, id: usize, blocked: bool)

Block or unblock item id. A blocked item is never scheduled to load; if resident it is evicted by the next plan call. Out-of-range ids are ignored.

pub fn mark_unloaded(&mut self, id: usize)

Force item id back to Unloaded (e.g. after a failed load that should be retried). Out-of-range ids are ignored. The item’s last-known byte weight is retained as the estimate for a future re-load; it no longer counts toward resident_bytes while Unloaded.

pub fn resident_bytes(&self) -> u64

Total bytes of all currently Resident items, for diagnostics and the byte-budget policy. Pending and Unloaded items are excluded.

pub fn counts(&self) -> (usize, usize, usize)

(resident, pending, unloaded) item counts, for diagnostics.

pub fn plan(&mut self) -> StreamPlan

Decide which items to load and evict this frame.

Unloaded items are considered best-score-first. While the pool has spare capacity – under both the count cap and (when set) the byte budget – they are simply scheduled to load. Once the pool is full a candidate can still load by evicting worst-scored residents, but only ones strictly farther than the candidate, so equal-priority items never churn. A large candidate may evict several small residents to fit under the byte budget. At most load_budget loads are scheduled per call.

With no byte budget set this reduces exactly to the count-only policy.

This method mutates planner state: scheduled items become Pending and evicted items become Unloaded, so a later plan call in the same frame (or the next frame) will not re-pick them.