Struct GpuBufferHandle

Source

pub struct GpuBufferHandle { /* private fields */ }

Expand description

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§

Source §

impl GpuBufferHandle

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn id(&self) -> u64

Stable process-local handle id used for cache signatures.

Source

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

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

Source

pub fn resident_handle(&self) -> Result<ResidentHandle, BackendError>

Resident handle naming this buffer, owner included.

§Errors

Returns a backend error when this process could not mint an identity for the WGPU resident namespace.

Source

pub fn from_resident_handle( handle: ResidentHandle, context: &str, ) -> Result<Option<Self>, BackendError>

Resolve a resident handle back into a live GPU handle.

Ok(None) means the handle named a WGPU buffer that is no longer live.

§Errors

Returns a backend error when handle was minted by a different backend instance, which is refused rather than resolved: its id would name an unrelated buffer here.

Source

pub fn buffer(&self) -> &Buffer

Underlying wgpu::Buffer.

Source

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.

Source