Struct CellBuffer 

pub struct CellBuffer { /* private fields */ }

Allocates and manages unsynchronized shared bytes.

Provides a utility to allocate a slice of bytes aligned to the maximally required alignment. Since the elements are much larger than single bytes the inner storage will not have exact sizes as one would be used from by using a Vec as an allocator. This is instead more close to a RawVec and most operations have the same drawback as Vec::reserve_exact in not actually being exact.

Since exact length and capacity semantics are hard to guarantee for most operations, no effort is made to uphold them. Instead. keeping track of the exact, wanted logical length of the requested byte slice is the obligation of the user under all circumstances. As a consequence, there are also no operations which explicitely uncouple length and capacity. All operations simply work on best effort of making some number of bytes available.

Implementations

impl CellBuffer

pub fn new(length: usize) -> Self

Allocate a new CellBuffer with a number of bytes.

Panics if the length is too long to find a properly aligned subregion.

pub fn with_buffer(buffer: Buffer) -> Self

Share an existing buffer.

The library will try, to an extent, to avoid an allocation here. However, it can only do so if the capacity of the underlying buffer is the same as the logical length of the shared buffer. Ultimately we rely on the standard libraries guarantees for constructing a reference counted allocation from an owned vector.

pub fn ptr_eq(&self, other: &Self) -> bool

Query if two buffers share the same memory region.

pub fn capacity(&self) -> usize

Retrieve the byte capacity of the allocated storage.

pub fn get_mut(&mut self) -> Option<&mut cell_buf>

Get this buffer if there are now copies.

use image_texel::texels::{AtomicBuffer, U8};

let mut buffer = AtomicBuffer::new(4);
assert!(buffer.get_mut().is_some());
let alias = buffer.clone();
assert!(buffer.get_mut().is_none());

pub fn make_mut(&mut self) -> &mut cell_buf

Ensure this buffer is its own copy.

use image_texel::texels::{AtomicBuffer, U8};

let mut buffer = AtomicBuffer::new(4);
let mut alias = buffer.clone();

U8.store_atomic(buffer.as_texels(U8).index_one(0), 1);
let unshared = buffer.make_mut().as_buf_mut();
let alias = alias.get_mut().expect("Just unaliased");

unshared.as_mut_texels(U8)[0] = 2;
assert_eq!(alias.as_buf_mut().as_mut_texels(U8)[0], 1);

pub fn to_owned(&self) -> Buffer

Copy the data into an owned buffer.

pub fn to_resized(&self, bytes: usize) -> Self

Create an independent copy of the buffer, with a new length.

The prefix contents of the new buffer will be the same as the current buffer. The new buffer will never share memory with the current buffer.

Methods from Deref<Target = cell_buf>

pub fn len(&self) -> usize

Get the length of available memory in bytes.

pub fn truncate(&self, at: usize) -> &Self

Reduce the number of bytes covered by this slice.

pub fn split_at(&self, at: usize) -> (&Self, &Self)

Split into two aligned buffers.

Panics

This panics if the byte offset given by at is not aligned according to max alignment or if the index is out-of-bounds.

pub fn as_texels<P>(&self, texel: Texel<P>) -> &Cell<[P]>

Reinterpret the buffer for the specific texel type.

The alignment of P is already checked to be smaller than MAX_ALIGN through the constructor of Texel. The slice will have the maximum length possible but may leave unused bytes in the end.

pub fn map_within<P, Q>( &self, src: impl RangeBounds<usize>, dest: usize, f: impl Fn(P) -> Q, p: Texel<P>, q: Texel<Q>, )

Apply a mapping function to some elements.

The indices src and dest are indices as if the slice were interpreted as [P] or [Q] respectively.

The types may differ which allows the use of this function to prepare a reinterpretation cast of a typed buffer. This function chooses the order of function applications such that values are not overwritten before they are used, i.e. the function arguments are exactly the previously visible values. This is even less trivial than for copy if the parameter types differ in size.

Panics

This function panics if src or the implied range of dest are out of bounds.

pub const ALIGNMENT: usize = MAX_ALIGN

Trait Implementations

impl Clone for CellBuffer

fn clone(&self) -> CellBuffer

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for CellBuffer

fn default() -> CellBuffer

Returns the “default value” for a type.

impl Deref for CellBuffer

type Target = cell_buf

The resulting type after dereferencing.

fn deref(&self) -> &cell_buf

Dereferences the value.

impl Eq for CellBuffer

impl From<&[u8]> for CellBuffer

fn from(values: &[u8]) -> Self

Converts to this type from the input type.

impl From<Buffer> for CellBuffer

fn from(values: Buffer) -> Self

Converts to this type from the input type.

impl PartialEq for CellBuffer

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.