pub enum Residency {
Host,
Device,
}Expand description
Where the frame’s pixel data physically resides.
Residency describes storage location, not access semantics.
A host-resident frame stores pixel bytes in CPU-accessible memory.
A device-resident frame stores data on an accelerator (GPU, NPU,
DMA‑buf, etc.) where host-readable bytes are not directly available.
§Access pattern
The canonical way to handle frames in CPU/GPU-mixed pipelines:
match frame.data_access() {
DataAccess::HostReadable => {
let bytes = frame.host_data().unwrap();
}
DataAccess::MappableToHost => {
let pixels = frame.require_host_data()?;
}
DataAccess::Opaque => {
let handle = frame.accelerated_handle::<MyBuffer>().unwrap();
}
_ => {}
}For pure CPU stages, FrameEnvelope::require_host_data() handles
all three cases with a single call.
§Relationship to DataAccess
Residency describes where the data lives. DataAccess describes
what host-access is available:
Residency | DataAccess | Meaning |
|---|---|---|
Host | HostReadable | CPU bytes directly available |
Device | MappableToHost | Device buffer, host-downloadable |
Device | Opaque | Device buffer, no host path |
Use FrameEnvelope::data_access() when you need the finer-grained
access classification.
§Adapter crates
This enum deliberately does not name any vendor or backend. Concrete
buffer types (CUDA buffers, OpenCL images, DMA‑buf fds, …) are defined
by adapter crates and stored behind a type‑erased handle accessible via
FrameEnvelope::accelerated_handle().
Variants§
Host
Pixel data is in CPU-accessible memory.
FrameEnvelope::host_data() returns Some(&[u8]).
Device
Pixel data resides on an accelerator device.
Host-readable bytes may or may not be obtainable —
check FrameEnvelope::data_access() for details.
Use FrameEnvelope::accelerated_handle() to obtain the
type-erased handle.