Struct GpuBufferHandle 

pub struct GpuBufferHandle { /* private fields */ }

Cheaply cloneable handle for a GPU-resident buffer.

The handle records the byte length originally requested by the caller, the backing allocation length, the logical element count, and the actual usage flags used to create the underlying wgpu::Buffer.

Implementations

impl GpuBufferHandle

pub fn upload( device: &Device, queue: &Queue, bytes: &[u8], usage: BufferUsages, ) -> Result<Self, BackendError>

Upload bytes into a new GPU buffer.

The created buffer always includes COPY_DST so the upload is legal.

Errors

Returns a backend error when the requested allocation length cannot fit u64.

pub fn alloc( device: &Device, len: u64, usage: BufferUsages, ) -> Result<Self, BackendError>

Allocate a GPU-resident buffer without uploading host contents.

Errors

Returns a backend error when len cannot be represented as a valid wgpu buffer size.

pub fn readback( &self, device: &Device, queue: &Queue, out: &mut Vec<u8>, ) -> Result<(), BackendError>

Download this GPU buffer into out.

This is intended for terminal output and test assertions, not hot-loop dispatch. The buffer must have COPY_SRC usage.

Errors

Returns a backend error when the handle is not copy-readable or the GPU mapping fails.

pub fn readback_prefix( &self, device: &Device, queue: &Queue, len: u64, out: &mut Vec<u8>, ) -> Result<(), BackendError>

Download the first len logical bytes of this GPU buffer into out.

Hot paths that publish a device-side count should read back only the counted prefix instead of the whole capacity-sized buffer. The copy is rounded up to wgpu’s 4-byte copy granularity internally, then truncated back to exactly len bytes before returning.

Errors

Returns a backend error when the handle is not copy-readable, len exceeds the logical buffer length, or the GPU mapping fails.

pub fn readback_range( &self, device: &Device, queue: &Queue, byte_offset: u64, len: u64, out: &mut Vec<u8>, ) -> Result<(), BackendError>

Download len logical bytes starting at byte_offset into out.

The internal GPU copy is alignment-expanded when necessary, then the returned host slice is trimmed back to exactly the requested range.

Errors

Returns a backend error when the handle is not copy-readable, the range exceeds the logical buffer length, or the GPU mapping fails.

pub fn id(&self) -> u64

Stable process-local handle id used for cache signatures.

pub fn from_resident_id(id: u64) -> Option<Self>

Resolve a process-local resident buffer id back into a live GPU handle.

pub fn buffer(&self) -> &Buffer

Underlying wgpu::Buffer.

pub fn buffer_arc(&self) -> Arc<Buffer>

Clone the internal Arc<wgpu::Buffer> - cheap, reference- count only. Used by the indirect dispatch path (C-B4) which needs to stash the buffer alongside other args.

pub fn byte_len(&self) -> u64

Logical byte length requested by the caller.

pub fn allocation_len(&self) -> u64

Backing allocation length.

pub fn element_count(&self) -> usize

Logical element count. Byte buffers report one element per byte.

pub fn usage(&self) -> BufferUsages

Actual usage flags on the underlying GPU allocation.

Trait Implementations

impl Clone for GpuBufferHandle

fn clone(&self) -> GpuBufferHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GpuBufferHandle

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

Formats the value using the given formatter.

impl From<GpuBufferHandle> for GpuResource

fn from(handle: GpuBufferHandle) -> Self

Converts to this type from the input type.