Skip to main content

DeferredGeometry

Struct DeferredGeometry 

Source
pub struct DeferredGeometry<K> { /* private fields */ }
Expand description

Several Readbacks in flight at once, keyed by what they are read-backs of, collected in submission order.

§Why this exists, and why it is not a fallback

This crate ships two extraction contracts and this is the third. They differ in what they guarantee, not in how hard they try:

A caller picks by requirement: a test wants the first, a renderer that only draws wants the second, and a collider consumer under a frame budget wants this. None substitutes for another when it fails.

§Why keyed, rather than a fixed-depth ring

P-71’s first arm was a depth-2 ring over one stream of read-backs, and a ring cannot represent what isomesh::DirtySet::mesh_within_budget does: it meshes many chunks in one frame, a count that changes with the budget and with how much of the world is dirty. A slot per read-back with the chunk’s own id attached is what lets a frame submit five and collect three, and it is what makes the collected bytes attributable — geometry that comes back without saying which chunk it belongs to is geometry a caller cannot install.

K is the caller’s key type; isomesh::ChunkId is the intended one and nothing here depends on it.

Implementations§

Source§

impl<K> DeferredGeometry<K>

Source

pub fn new(capacity: usize) -> Result<Self>

A queue holding at most capacity read-backs in flight.

capacity is the collision-latency knob: at 1 a submitted chunk must be collected before the next can be submitted, at n a burst of n chunks can be in flight and the last of them is n collections away.

§Errors

Error::DeferredQueueFull with capacity: 0. A zero-capacity queue is full the moment it exists — every DeferredGeometry::submit would refuse — so it is refused at construction where the caller can see it, rather than becoming a scheduler that silently meshes nothing.

Source

pub fn has_room(&self) -> bool

Whether another DeferredGeometry::submit would be accepted.

Source

pub fn submit(&mut self, key: K, readback: Readback) -> Result<()>

Record a read-back that has already been submitted, under key.

§Errors

Error::DeferredQueueFull when !has_room(). The read-back is returned to the caller as part of nothing — it is dropped, which unmaps and frees its staging buffer — so a caller that ignores this error has lost that chunk’s geometry. Ask DeferredGeometry::has_room before paying for the extraction.

Source

pub fn drain_ready(&mut self, device: &Device) -> Result<Vec<(K, Vec<Vec<u8>>)>>

Every read-back that has completed, in submission order. Call once a frame.

A slot that is not ready stays in flight and is offered again next call, which is what makes this safe to call unconditionally: the return is the frame’s harvest and an empty Vec means “nothing yet”, never “nothing ever”. Each entry’s inner Vec<Vec<u8>> is that read-back’s requests in the order they were asked for, exactly as Readback::take returns them.

Submission order is preserved because slots are filled at the lowest free index and scanned in index order, and a slot is only freed by a collection — so a chunk submitted before another is never collected after it within one frame. Across frames the order is the order they became ready, which is the driver’s.

§Errors

Whatever Readback::take returns: Error::MapFailed if a map was refused. The failing read-back has already been removed from the queue, so a retry is the caller re-extracting that chunk rather than asking again — there is nothing left here to ask.

Source

pub fn in_flight(&self) -> usize

Read-backs submitted and not yet collected.

Source

pub fn capacity(&self) -> usize

The capacity this was built with.

Trait Implementations§

Source§

impl<K: Debug> Debug for DeferredGeometry<K>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<K> !RefUnwindSafe for DeferredGeometry<K>

§

impl<K> !UnwindSafe for DeferredGeometry<K>

§

impl<K> Forget for DeferredGeometry<K>

§

impl<K> Freeze for DeferredGeometry<K>
where Vec<Option<(K, Readback)>>: Freeze,

§

impl<K> Send for DeferredGeometry<K>
where Vec<Option<(K, Readback)>>: Send,

§

impl<K> Sync for DeferredGeometry<K>
where Vec<Option<(K, Readback)>>: Sync,

§

impl<K> Unpin for DeferredGeometry<K>
where Vec<Option<(K, Readback)>>: Unpin,

§

impl<K> UnsafeUnpin for DeferredGeometry<K>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WasmNotSend for T
where T: Send,

Source§

impl<T> WasmNotSendSync for T

Source§

impl<T> WasmNotSync for T
where T: Sync,