Struct ravif::Img

pub struct Img<Container> {
    pub buf: Container,
    pub stride: usize,
    pub width: u32,
    pub height: u32,
}

Basic struct used for both owned (alias ImgVec) and borrowed (alias ImgRef) image fragments.

Note: the fields are pub only because of borrow checker limitations. Please consider them as read-only.

Fields

buf: Container

👎 Deprecated:

Don't access struct fields directly. Use buf(), buf_mut() or into_buf()

Storage for the pixels. Usually Vec<Pixel> or &[Pixel]. See ImgVec and ImgRef.

Note that future version will make this field private. Use .rows() and .pixels() iterators where possible, or buf()/buf_mut()/into_buf().

stride: usize

👎 Deprecated:

Don't access struct fields directly. Use stride()

Number of pixels to skip in the container to advance to the next row.

Note: pixels between width and stride may not be usable, and may not even exist in the last row.

width: u32

👎 Deprecated:

Don't access struct fields directly. Use width()

Width of the image in pixels.

Note that this isn't same as the width of the row in the buf, see stride

height: u32

👎 Deprecated:

Don't access struct fields directly. Use height()

Height of the image in pixels.

Implementations

impl<Container> Img<Container>

pub fn width(&self) -> usize

Width of the image in pixels.

Note that this isn't same as the width of the row in image data, see stride()

pub fn height(&self) -> usize

Height of the image in pixels.

pub fn stride(&self) -> usize

Number of pixels to skip in the container to advance to the next row.

Note the last row may have fewer pixels than the stride. Some APIs use number of bytes for a stride. You may need to multiply this one by number of pixels.

pub fn buf(&self) -> &Container

Immutable reference to the pixel storage. Warning: exposes stride. Use pixels() or rows() insetad.

See also into_contiguous_buf().

pub fn buf_mut(&mut self) -> &mut Container

Mutable reference to the pixel storage. Warning: exposes stride. Use pixels_mut() or rows_mut() insetad.

See also into_contiguous_buf().

pub fn into_buf(self) -> Container

Get the pixel storage by consuming the image. Be careful about stride — see into_contiguous_buf() for a safe version.

pub fn rows_buf<'a, T>(&self, buf: &'a [T]) -> RowsIter<'a, T> where
    T: 'a, 

👎 Deprecated:

this was meant to be private, use new_buf() and/or rows()

impl<'a, T> Img<&'a [T]>

#[must_use]pub fn sub_image(
    &self,
    left: usize,
    top: usize,
    width: usize,
    height: usize
) -> Img<&'a [T]>

Make a reference for a part of the image, without copying any pixels.

Panics

It will panic if sub_image is outside of the image area (left + width must be <= container width, etc.)

#[must_use]pub fn rows(&self) -> RowsIter<'_, T>

Iterate over whole rows of pixels as slices

Panics

If stride is 0

See also pixels()

pub fn iter(&self) -> Iter<'_, T>

👎 Deprecated:

Size of this buffer is unpredictable. Use .rows() instead

Deprecated

Note: it iterates all pixels in the underlying buffer, not just limited by width/height.

impl<'a, T> Img<&'a [T]> where
    T: Clone, 

#[must_use]pub fn to_contiguous_buf(&self) -> (Cow<'_, [T]>, usize, usize)

Returns a reference to the buffer, width, height. Guarantees that the buffer is contiguous, i.e. it's width*height elements long, and [x + y*width] addresses each pixel.

It will create a copy if the buffer isn't contiguous (width != stride). For a more efficient version, see into_contiguous_buf()

impl<'a, T> Img<&'a mut [T]>

#[must_use]pub fn sub_image(
    &'a mut self,
    left: usize,
    top: usize,
    width: usize,
    height: usize
) -> Img<&'a [T]>

Turn this into immutable reference, and slice a subregion of it

#[must_use]pub fn sub_image_mut(
    &mut self,
    left: usize,
    top: usize,
    width: usize,
    height: usize
) -> Img<&mut [T]>

Trim this image without copying. Note that mutable borrows are exclusive, so it's not possible to have more than one mutable subimage at a time.

#[must_use]pub fn as_ref(&self) -> Img<&[T]>

Make mutable reference immutable

impl<'a, T> Img<&'a [T]> where
    T: Copy, 

#[must_use]pub fn pixels(&self) -> PixelsIter<'_, T>

Panics

if width is 0

impl<'a, T> Img<&'a mut [T]> where
    T: Copy, 

#[must_use]pub fn pixels(&self) -> PixelsIter<'_, T>

Panics

if width is 0

#[must_use]pub fn pixels_mut(&mut self) -> PixelsIterMut<'_, T>

Panics

if width is 0

impl<'a, T> Img<Vec<T>> where
    T: Copy, 

#[must_use]pub fn pixels(&self) -> PixelsIter<'_, T>

Panics

if width is 0

#[must_use]pub fn pixels_mut(&mut self) -> PixelsIterMut<'_, T>

Panics

if width is 0

impl<'a, T> Img<&'a mut [T]>

#[must_use]pub fn rows(&self) -> RowsIter<'_, T>

Panics

if stride is 0

#[must_use]pub fn rows_mut(&mut self) -> RowsIterMut<'_, T>

Panics

if stride is 0

impl<T> Img<Vec<T>>

#[must_use]pub fn sub_image_mut(
    &mut self,
    left: usize,
    top: usize,
    width: usize,
    height: usize
) -> Img<&mut [T]>

Create a mutable view into a region within the image. See sub_image() for read-only views.

#[must_use]pub fn sub_image(
    &self,
    left: usize,
    top: usize,
    width: usize,
    height: usize
) -> Img<&[T]>

Make a reference for a part of the image, without copying any pixels.

#[must_use]pub fn as_ref(&self) -> Img<&[T]>

Make a reference to this image to pass it to functions without giving up ownership

The reference should be passed by value (ImgRef, not &ImgRef).

If you need a mutable reference, see as_mut() and sub_image_mut()

pub fn as_mut(&mut self) -> Img<&mut [T]>

Make a mutable reference to the entire image

The reference should be passed by value (ImgRefMut, not &mut ImgRefMut).

See also sub_image_mut() and rows_mut()

pub fn iter(&self) -> Iter<'_, T>

👎 Deprecated:

Size of this buffer may be unpredictable. Use .rows() instead

#[must_use]pub fn rows(&self) -> RowsIter<'_, T>

Iterate over rows of the image as slices

Each slice is guaranteed to be exactly width pixels wide.

#[must_use]pub fn rows_mut(&mut self) -> RowsIterMut<'_, T>

Iterate over rows of the image as mutable slices

Each slice is guaranteed to be exactly width pixels wide.

impl<Container> Img<Container>

pub fn new_stride(
    buf: Container,
    width: usize,
    height: usize,
    stride: usize
) -> Img<Container>

Same as new(), except each row is located stride number of pixels after the previous one.

Stride can be equal to width or larger. If it's larger, then pixels between end of previous row and start of the next are considered a padding, and may be ignored.

The Container is usually a Vec or a slice.

pub fn new(buf: Container, width: usize, height: usize) -> Img<Container>

Create new image with Container (which can be Vec, &[] or something else) with given width and height in pixels.

Assumes the pixels in container are contiguous, layed out row by row with width pixels per row and at least height rows.

If the container is larger than width×height pixels, the extra rows are a considered a padding and may be ignored.

impl<T> Img<Vec<T>> where
    T: Copy, 

#[must_use]pub fn into_contiguous_buf(self) -> (Vec<T>, usize, usize)

Returns the buffer, width, height. Guarantees that the buffer is contiguous, i.e. it's width*height elements long, and [x + y*width] addresses each pixel.

Efficiently performs operation in-place. For other containers use pixels().collect().

#[must_use]pub fn as_contiguous_buf(&mut self) -> (&[T], usize, usize)

Returns a reference to the buffer, width, height. Guarantees that the buffer is contiguous, i.e. it's width*height elements long, and [x + y*width] addresses each pixel.

Efficiently performs operation in-place. For other containers use pixels().collect().

impl<OldContainer> Img<OldContainer>

pub fn new_buf<NewContainer, OldPixel, NewPixel>(
    &self,
    new_buf: NewContainer
) -> Img<NewContainer> where
    NewContainer: AsRef<[NewPixel]>,
    OldContainer: AsRef<[OldPixel]>, 

A convenience method for creating an image of the same size and stride, but with a new buffer.

Trait Implementations

impl<Container> Clone for Img<Container> where
    Container: Clone, 

fn clone(&self) -> Img<Container>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Container> Copy for Img<Container> where
    Container: Copy, 

impl<Container> Debug for Img<Container> where
    Container: Debug, 

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

Formats the value using the given formatter.

impl<'a, T> Eq for Img<&'a [T]> where
    T: Eq, 

impl<'a, T> Eq for Img<&'a mut [T]> where
    T: Eq, 

impl<T> Eq for Img<Vec<T>> where
    T: Eq, 

impl<'a, T> Hash for Img<&'a mut [T]> where
    T: Hash, 

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

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<'a, T> Hash for Img<&'a [T]> where
    T: Hash, 

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

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<T> Hash for Img<Vec<T>> where
    T: Hash, 

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

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<Pixel, Container> ImgExt<Pixel> for Img<Container> where
    Container: AsRef<[Pixel]>, 

fn width_padded(&self) -> usize

Maximum possible width of the data, including the stride.

fn height_padded(&self) -> usize

Height in number of full strides. If the underlying buffer is not an even multiple of strides, the last row is ignored.

fn rows_padded(&self) -> Chunks<'_, Pixel>

Iterate over the entire buffer as rows, including all padding

Rows will have up to stride width, but the last row may be shorter.

impl<Pixel, Container> ImgExtMut<Pixel> for Img<Container> where
    Container: AsMut<[Pixel]>, 

#[must_use]fn rows_padded_mut(&mut self) -> ChunksMut<'_, Pixel>

Iterate over the entire buffer as rows, including all padding

Rows will have up to stride width, but the last row may be shorter.

Panics

If stride is 0

impl<'a, Pixel> Index<(u32, u32)> for Img<&'a [Pixel]> where
    Pixel: Copy, 

type Output = Pixel

The returned type after indexing.

fn index(
    &self,
    index: (u32, u32)
) -> &<Img<&'a [Pixel]> as Index<(u32, u32)>>::Output

Read a pixel at (x,y) location (e.g. px = img[(x,y)])

Coordinates may be outside width/height if the buffer has enough padding. The x coordinate can't exceed stride.

impl<'a, Pixel> Index<(u32, u32)> for Img<Vec<Pixel>> where
    Pixel: Copy, 

type Output = Pixel

The returned type after indexing.

fn index(
    &self,
    index: (u32, u32)
) -> &<Img<Vec<Pixel>> as Index<(u32, u32)>>::Output

Read a pixel at (x,y) location (e.g. px = img[(x,y)])

Coordinates may be outside width/height if the buffer has enough padding. The x coordinate can't exceed stride.

impl<'a, Pixel> Index<(u32, u32)> for Img<&'a mut [Pixel]> where
    Pixel: Copy, 

type Output = Pixel

The returned type after indexing.

fn index(
    &self,
    index: (u32, u32)
) -> &<Img<&'a mut [Pixel]> as Index<(u32, u32)>>::Output

Read a pixel at (x,y) location (e.g. px = img[(x,y)])

Coordinates may be outside width/height if the buffer has enough padding. The x coordinate can't exceed stride.

impl<'a, Pixel> Index<(usize, usize)> for Img<&'a [Pixel]> where
    Pixel: Copy, 

type Output = Pixel

The returned type after indexing.

fn index(
    &self,
    index: (usize, usize)
) -> &<Img<&'a [Pixel]> as Index<(usize, usize)>>::Output

Read a pixel at (x,y) location (e.g. px = img[(x,y)])

Coordinates may be outside width/height if the buffer has enough padding. The x coordinate can't exceed stride.

impl<'a, Pixel> Index<(usize, usize)> for Img<&'a mut [Pixel]> where
    Pixel: Copy, 

type Output = Pixel

The returned type after indexing.

fn index(
    &self,
    index: (usize, usize)
) -> &<Img<&'a mut [Pixel]> as Index<(usize, usize)>>::Output

Read a pixel at (x,y) location (e.g. px = img[(x,y)])

Coordinates may be outside width/height if the buffer has enough padding. The x coordinate can't exceed stride.

impl<'a, Pixel> Index<(usize, usize)> for Img<Vec<Pixel>> where
    Pixel: Copy, 

type Output = Pixel

The returned type after indexing.

fn index(
    &self,
    index: (usize, usize)
) -> &<Img<Vec<Pixel>> as Index<(usize, usize)>>::Output

Read a pixel at (x,y) location (e.g. px = img[(x,y)])

Coordinates may be outside width/height if the buffer has enough padding. The x coordinate can't exceed stride.

impl<'a, Pixel> Index<usize> for Img<&'a [Pixel]> where
    Pixel: Copy, 

type Output = [Pixel]

The returned type after indexing.

fn index(&self, row: usize) -> &<Img<&'a [Pixel]> as Index<usize>>::Output

Take n-th row as a slice. Same as .rows().nth(n).unwrap()

Slice length is guaranteed to equal image width. Row must be within image height.

impl<'a, Pixel> Index<usize> for Img<Vec<Pixel>> where
    Pixel: Copy, 

type Output = [Pixel]

The returned type after indexing.

fn index(&self, row: usize) -> &<Img<Vec<Pixel>> as Index<usize>>::Output

Take n-th row as a slice. Same as .rows().nth(n).unwrap()

Slice length is guaranteed to equal image width. Row must be within image height.

impl<'a, Pixel> Index<usize> for Img<&'a mut [Pixel]> where
    Pixel: Copy, 

type Output = [Pixel]

The returned type after indexing.

fn index(&self, row: usize) -> &<Img<&'a mut [Pixel]> as Index<usize>>::Output

Take n-th row as a slice. Same as .rows().nth(n).unwrap()

Slice length is guaranteed to equal image width. Row must be within image height.

impl<'a, Pixel> IndexMut<(u32, u32)> for Img<Vec<Pixel>> where
    Pixel: Copy, 

fn index_mut(
    &mut self,
    index: (u32, u32)
) -> &mut <Img<Vec<Pixel>> as Index<(u32, u32)>>::Output

Write a pixel at (x,y) location (e.g. img[(x,y)] = px)

Coordinates may be outside width/height if the buffer has enough padding. The x coordinate can't exceed stride.

impl<'a, Pixel> IndexMut<(u32, u32)> for Img<&'a mut [Pixel]> where
    Pixel: Copy, 

fn index_mut(
    &mut self,
    index: (u32, u32)
) -> &mut <Img<&'a mut [Pixel]> as Index<(u32, u32)>>::Output

Write a pixel at (x,y) location (e.g. img[(x,y)] = px)

Coordinates may be outside width/height if the buffer has enough padding. The x coordinate can't exceed stride.

impl<'a, Pixel> IndexMut<(usize, usize)> for Img<&'a mut [Pixel]> where
    Pixel: Copy, 

fn index_mut(
    &mut self,
    index: (usize, usize)
) -> &mut <Img<&'a mut [Pixel]> as Index<(usize, usize)>>::Output

Write a pixel at (x,y) location (e.g. img[(x,y)] = px)

Coordinates may be outside width/height if the buffer has enough padding. The x coordinate can't exceed stride.

impl<'a, Pixel> IndexMut<(usize, usize)> for Img<Vec<Pixel>> where
    Pixel: Copy, 

fn index_mut(
    &mut self,
    index: (usize, usize)
) -> &mut <Img<Vec<Pixel>> as Index<(usize, usize)>>::Output

Write a pixel at (x,y) location (e.g. img[(x,y)] = px)

Coordinates may be outside width/height if the buffer has enough padding. The x coordinate can't exceed stride.

impl<'a, Pixel> IndexMut<usize> for Img<Vec<Pixel>> where
    Pixel: Copy, 

fn index_mut(
    &mut self,
    row: usize
) -> &mut <Img<Vec<Pixel>> as Index<usize>>::Output

Take n-th row as a mutable slice. Same as .rows().nth(n).unwrap()

Slice length is guaranteed to equal image width. Row must be within image height.

impl<'a, Pixel> IndexMut<usize> for Img<&'a mut [Pixel]> where
    Pixel: Copy, 

fn index_mut(
    &mut self,
    row: usize
) -> &mut <Img<&'a mut [Pixel]> as Index<usize>>::Output

Take n-th row as a mutable slice. Same as .rows().nth(n).unwrap()

Slice length is guaranteed to equal image width. Row must be within image height.

impl<Container> IntoIterator for Img<Container> where
    Container: IntoIterator, 

type Item = <Container as IntoIterator>::Item

The type of the elements being iterated over.

type IntoIter = <Container as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> <Container as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<'a, T, U> PartialEq<Img<&'a [U]>> for Img<Vec<T>> where
    T: PartialEq<U>, 

fn eq(&self, other: &Img<&'a [U]>) -> bool

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a, 'b, T, U> PartialEq<Img<&'b [U]>> for Img<&'a [T]> where
    T: PartialEq<U>, 

fn eq(&self, other: &Img<&'b [U]>) -> bool

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a, 'b, T, U> PartialEq<Img<&'b [U]>> for Img<&'a mut [T]> where
    T: PartialEq<U>, 

fn eq(&self, other: &Img<&'b [U]>) -> bool

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a, 'b, T, U> PartialEq<Img<&'b mut [U]>> for Img<&'a mut [T]> where
    T: PartialEq<U>, 

fn eq(&self, other: &Img<&'b mut [U]>) -> bool

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a, 'b, T, U> PartialEq<Img<&'b mut [U]>> for Img<&'a [T]> where
    T: PartialEq<U>, 

fn eq(&self, other: &Img<&'b mut [U]>) -> bool

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a, T, U> PartialEq<Img<Vec<U>>> for Img<&'a [T]> where
    T: PartialEq<U>, 

fn eq(&self, other: &Img<Vec<U>>) -> bool

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T, U> PartialEq<Img<Vec<U>>> for Img<Vec<T>> where
    T: PartialEq<U>, 

fn eq(&self, other: &Img<Vec<U>>) -> bool

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.