Struct image_texel::Texel

pub struct Texel<P: ?Sized>(_);

Marker struct to denote a texel type.

Can be constructed only for types that have expected alignment and no byte invariants. It always implements Copy and Clone, regardless of the underlying type and is zero-sized.

This is the central encapsulation of unsafety in this crate. It utilizes bytemuck for a safe interface but permits other types with an unsafe interface, and offers the cast operations without a bound on the Pod trait. Note that Pod is a pure marker trait; its properties must hold even if it is not explicitly mentioned. If all constructors (safely or unsafely) ensure that its properties hold we can use Texel as a witness type for the bound and subsequently write interfaces to take an instance instead of having a static type bound. This achieves two effects:

• Firstly, it makes the interface independent of the chosen transmutation crate. Potentially we will have a method to construct the Texel via a core trait.
• Secondly, it allows creating texel of third-party types for which the bound can not be implemented. Crucially, this includes SIMD representations that would be a burden to support directly. And conversely you can also deal with arbitrary existing texel without a bound in your own interfaces!

Implementations

impl<P: Pod> Texel<P>

pub const fn for_type() -> Option<Self>

Try to construct an instance of the marker.

If successful, you can freely use it to access the image buffers. This requires:

• The type must have an alignment of at most MAX_ALIGN.
• The type must not be a ZST.
• The type must not have any Drop-glue (no drop, any contain not part that is Drop).

impl<P> Texel<P>

pub const unsafe fn new_unchecked() -> Self

Create a witness certifying P as a texel without checks.

Safety

The type P must not:

• have any validity invariants, i.e. is mustn’t contain any padding.
• have any safety invariants. This implies it can be copied.
• have an alignment larger than MaxAligned.
• be a zero-size type.

Furthermore, tentatively, the type must not have any drop glue. That is its members are all simple types without Drop implementations. This requirement exists mainly to avoid code accidentally leaking instances, and ensures that copies created from their byte representation—which is safe according to the other invairants— do not cause unexpected effects.

pub const fn align(self) -> usize

Proxy of core::mem::align_of.

pub const fn size(self) -> usize

Proxy of core::mem::size_of.

pub const fn size_nz(self) -> NonZeroUsize

Publicly visible function to use the guarantee of non-ZST.

pub const fn array<const N: usize>(self) -> Texel<[P; N]>

Construct a texel as an array of no elements.

Panics

This function panics when called with N equal to 0.

pub const fn transparent_wrap<O>(
    self,
    _: IsTransparentWrapper<P, O>
) -> Texel<O>

Construct a texel by wrapping into a transparent wrapper.

TODO: a constructor for Texel based on proof of transmutation from &mut P to &mut O, based on the standard transmutation RFC. This is more flexible than bytemuck’s TransparentWrapper trait.

pub const fn transparent_unwrap<O>(
    self,
    _: IsTransparentWrapper<O, P>
) -> Texel<O>

Construct a texel by unwrapping a transparent wrapper.

pub const fn num_wrapping(self) -> Texel<Wrapping<P>>

Construct a texel that contains a number in the standard Wrapping type.

impl<T, const N: usize> Texel<[T; N]>

pub const fn array_element(self) -> Texel<T>

Construct a texel, from an array of elements.

impl<P> Texel<P>

Operations that can be performed based on the evidence of Texel.

pub fn copy_val(self, val: &P) -> P

Copy a texel.

Note that this does not require Copy because that requirement was part of the requirements of constructing this Texel witness.

pub fn to_slice<'buf>(self, buffer: &'buf [MaxAligned]) -> &'buf [P]

Reinterpret a slice of aligned bytes as a slice of the texel.

Note that the size (in bytes) of the slice will be shortened if the size of P is not a divisor of the input slice’s size.

pub fn to_mut_slice<'buf>(self, buffer: &'buf mut [MaxAligned]) -> &'buf mut [P]

Reinterpret a slice of aligned bytes as a mutable slice of the texel.

Note that the size (in bytes) of the slice will be shortened if the size of P is not a divisor of the input slice’s size.

pub fn try_to_slice<'buf>(self, bytes: &'buf [u8]) -> Option<&'buf [P]>

Try to reinterpret a slice of bytes as a slice of the texel.

This returns Some if the buffer is suitably aligned, and None otherwise.

pub fn try_to_slice_mut<'buf>(
    self,
    bytes: &'buf mut [u8]
) -> Option<&'buf mut [P]>

Try to reinterpret a slice of bytes as a slice of the texel.

This returns Some if the buffer is suitably aligned, and None otherwise.

pub fn to_bytes<'buf>(self, texel: &'buf [P]) -> &'buf [u8]

Reinterpret a slice of texel as memory.

Note that you can convert a reference to a single value by core::slice::from_ref.

pub fn to_mut_bytes<'buf>(self, texel: &'buf mut [P]) -> &'buf mut [u8]

Reinterpret a mutable slice of texel as memory.

Note that you can convert a reference to a single value by core::slice::from_mut.

Trait Implementations

impl<P> Clone for Texel<P>

This is a pure marker type.

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<P> Debug for Texel<P>

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

Formats the value using the given formatter.

impl<P> From<Texel<P>> for TexelLayout

Convert a pixel to an element, discarding the exact type information.

fn from(pix: Texel<P>) -> Self

Converts to this type from the input type.

impl<P> Hash for Texel<P>

fn hash<H: Hasher>(&self, _: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<P> Ord for Texel<P>

fn cmp(&self, _: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<P> PartialEq<Texel<P>> for Texel<P>

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<P> PartialOrd<Texel<P>> for Texel<P>

fn partial_cmp(&self, _: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<P> TryMend<MatrixBytes> for Texel<P>

Try to use the matrix with a specific pixel type.

type Into = Matrix<P>

type Err = MismatchedPixelError

fn try_mend(self, matrix: &MatrixBytes) -> Result<Matrix<P>, Self::Err>

impl<P> TryMend<StridedBytes> for Texel<P>

Try to use the matrix with a specific pixel type.

type Into = Strides<P>

type Err = MismatchedPixelError

fn try_mend(self, matrix: &StridedBytes) -> Result<Strides<P>, Self::Err>

impl<P> Copy for Texel<P>

This is a pure marker type.

impl<P> Eq for Texel<P>