Struct PboTensor 

pub struct PboTensor<T>
where
    T: Num + Clone + Debug + Send + Sync,
{
    pub name: String,
    pub shape: Vec<usize>,
    /* private fields */
}

A tensor backed by an OpenGL Pixel Buffer Object.

Fields

name: String

shape: Vec<usize>

Implementations

impl<T> PboTensor<T>

where T: Num + Clone + Debug + Send + Sync,

pub fn from_pbo( buffer_id: u32, size: usize, shape: &[usize], name: Option<&str>, ops: Arc<dyn PboOps>, ) -> Result<Self>

Create a new PBO tensor from an already-allocated GL buffer.

Called by the image crate after creating the PBO on the GL thread. Users should not call this directly — use ImageProcessor::create_image().

Errors

Returns Error::ShapeMismatch if size does not equal shape.iter().product::<usize>() * std::mem::size_of::<T>(). Returns Error::InvalidSize if size is zero. Returns Error::InvalidShape if that shape footprint overflows usize — refused rather than wrapped to a small byte count an undersized size would then satisfy.

pub fn buffer_id(&self) -> u32

Returns the GL buffer ID for this PBO.

pub fn is_mapped(&self) -> bool

Returns true unless the PBO is fully unmapped.

That covers an exclusive map, one or more read-only holders, AND a map or unmap another thread currently has in flight — during those windows the GL buffer is (or is about to be) mapped, and no other mapping may begin, so reporting false would be misleading. Use it as “is this buffer free for GL operations?”, not as “does a CPU pointer exist right now”.

impl<T> PboTensor<T>

where T: Num + Clone + Debug + Send + Sync,

pub fn into_client_parts(self) -> Result<PboClientParts>

Decompose this tensor into the parts a C entry point takes.

The shape is carried through as-is and is not required to fill the allocation: size is the GL buffer’s full byte count and may exceed the shape’s product by design (a 64-byte-aligned row stride is the usual reason). Only the origin is constrained.

Errors

Error::InvalidOperation for a sub-view (view_offset != 0). A sub-view’s window is not expressible in ef_tensor_wrap_pbo’s argument list, and a wrap that silently dropped it would land the far side at the parent’s origin — issue #162 in reverse. Views are taken on the far side (Tensor::view) once the buffer is wrapped, so nothing needs this.

Trait Implementations

impl<T> Clone for PboTensor<T>

where T: Num + Clone + Debug + Send + Sync,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for PboTensor<T>

where T: Num + Clone + Debug + Send + Sync,

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

Formats the value using the given formatter.

impl<T> Send for PboTensor<T>

where T: Num + Clone + Debug + Send + Sync,

impl<T> Sync for PboTensor<T>

where T: Num + Clone + Debug + Send + Sync,

impl<T> TensorTrait<T> for PboTensor<T>

where T: Num + Clone + Debug + Send + Sync,

fn set_logical_shape(&mut self, shape: &[usize]) -> Result<()>

Capacity-based reconfigure (mirrors Mem/Shm/DMA/IOSurface): allow any shape whose byte size fits the PBO allocation, so an oversized reusable pool can be configure_imaged to a smaller image. Without this PBO fell back to the strict-reshape default and rejected pool reuse.

fn view(&self, offset_bytes: usize, shape: &[usize]) -> Result<Self>

Zero-copy sub-region view sharing this PBO’s GL buffer (via the Arc<PboHandle>) and BufferIdentity, positioned at offset_bytes from this tensor’s own window with logical shape. The GL backend keys the import on the shared identity and addresses the window via glViewport / the staged copy; a CPU map adds view_offset to the mapped base. Mirrors DmaTensor::view.

Errors

• Error::InvalidOperation if offset_bytes is mis-aligned for T.
• Error::InsufficientCapacity if the window exceeds the allocation.

fn new(_shape: &[usize], _name: Option<&str>) -> Result<Self>

Create a new tensor with the given shape and optional name. If no name is given, a random name will be generated.

fn from_fd(_fd: OwnedFd, _shape: &[usize], _name: Option<&str>) -> Result<Self>

Import an existing buffer as a tensor, taking ownership of its file descriptor. The buffer is adopted in place — no bytes are copied.

fn clone_fd(&self) -> Result<OwnedFd>

Clone the file descriptor associated with this tensor.

fn memory(&self) -> TensorMemory

Get the memory type of this tensor.

fn name(&self) -> String

Get the name of this tensor.

fn shape(&self) -> &[usize]

Get the shape of this tensor.

fn reshape(&mut self, shape: &[usize]) -> Result<()>

Reshape this tensor to the given shape. The total number of elements must remain the same.

fn capacity_bytes(&self) -> usize

Bytes of the underlying allocation (>= the current logical size()).

fn map_with<'a>(&self, access: CpuAccess) -> Result<HostView<'a, T>>

where T: 'a,

Map the tensor into memory with the given access direction and return a TensorMap for accessing the data.

fn buffer_identity(&self) -> &BufferIdentity

Get the buffer identity for cache keying and liveness tracking.

fn len(&self) -> usize

Get the number of elements in this tensor.

fn is_empty(&self) -> bool

Check if the tensor is empty.

fn size(&self) -> usize

Get the size in bytes of this tensor.

fn map<'a>(&self) -> Result<HostView<'a, T>>

where T: 'a,

Map the tensor read-write (equivalent to map_with(CpuAccess::ReadWrite)).

fn map_read<'a>(&self) -> Result<HostView<'a, T>>

where T: 'a,

Map the tensor for CPU reading only. The returned map rejects as_mut_slice; on macOS this takes the read-only IOSurface lock (skips the unlock flush), on Linux the dma-buf read-direction sync. Fails with Error::CpuAccessDenied on a Write- or None-declared tensor.

fn map_write<'a>(&self) -> Result<HostView<'a, T>>

where T: 'a,

Map the tensor for CPU writing (fill-only: reading through a write map may see write-combined memory — do not read the slice). Valid only for a pass that overwrites the whole mapping; see write_access. Fails with Error::CpuAccessDenied on a Read- or None-declared tensor.

fn map_mut<'a>(&self) -> Result<HostView<'a, T>>

where T: 'a,

Map the tensor read-write (alias of map with the intent spelled out); refused on the same declarations.

fn cpu_access(&self) -> CpuAccess

The CPU access declared for this tensor (see CpuAccess). A bare backing carries no declaration of its own and reports ReadWrite.

fn view_origin(&self) -> Option<ViewOrigin>

The parent-image snapshot when this tensor is a sub-region of a larger buffer (see ViewOrigin); a bare backing reports None.

fn is_view(&self) -> bool

Whether this tensor addresses part of a larger buffer (see Tensor::is_view); a bare backing reports false.

fn write_access(&self) -> CpuAccess

The direction a CPU pass that overwrites every element of this tensor maps with.

fn map_for_write<'a>(&self) -> Result<HostView<'a, T>>

where T: 'a,

Map for a CPU pass that overwrites every element, in write_access’s direction.

fn map_for_partial_write<'a>(&self) -> Result<HostView<'a, T>>

where T: 'a,

Map for a CPU pass that writes only part of the buffer and keeps the rest (a letterbox border around a device-rendered interior): always ReadWrite, see write_access.

fn try_map_with<'a>(&self, access: CpuAccess) -> Result<HostView<'a, T>>

where T: 'a,

Non-blocking map_with: returns Err(Error::IoError(WouldBlock)) while a GPU copy the map depends on is still in flight, and makes progress on a retry.

fn try_map<'a>(&self) -> Result<HostView<'a, T>>

where T: 'a,

Non-blocking map: read-write, and WouldBlock rather than a stall. See try_map_with.