Struct imgref::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: 'a>(&self, buf: &'a [T]) -> RowsIter<'a, T>

👎 Deprecated:

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

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

pub fn sub_image(
    &self,
    left: usize,
    top: usize,
    width: usize,
    height: usize
) -> Self

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.)

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: Clone> Img<&'a [Pixel]>

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 [Pixel]>

pub fn sub_image(
    &'a mut self,
    left: usize,
    top: usize,
    width: usize,
    height: usize
) -> ImgRef<'a, T>

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

pub fn sub_image_mut(
    &mut self,
    left: usize,
    top: usize,
    width: usize,
    height: usize
) -> ImgRefMut<'_, 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.

pub fn as_ref(&self) -> ImgRef<'_, T>

Make mutable reference immutable

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

pub fn pixels(&self) -> PixelsIter<'_, T>

Iterate width*height pixels in the Img, ignoring padding area

Panics

if width is 0

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

pub fn pixels_ref(&self) -> PixelsRefIter<'_, T>

Iterate width*height pixels in the Img, by reference, ignoring padding area

Panics

if width is 0

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

pub fn pixels(&self) -> PixelsIter<'_, T>

Panics

if width is 0

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

Panics

if width is 0

impl<'a, T: Copy> Img<Vec<Pixel, Global>>

pub fn pixels(&self) -> PixelsIter<'_, T>

Panics

if width is 0

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

Panics

if width is 0

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

pub fn rows(&self) -> RowsIter<'_, T>

Panics

if stride is 0

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

Panics

if stride is 0

impl<T> Img<Vec<Pixel, Global>>

pub fn sub_image_mut(
    &mut self,
    left: usize,
    top: usize,
    width: usize,
    height: usize
) -> ImgRefMut<'_, T>

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

pub fn sub_image(
    &self,
    left: usize,
    top: usize,
    width: usize,
    height: usize
) -> ImgRef<'_, T>

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

pub fn as_ref(&self) -> ImgRef<'_, 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) -> ImgRefMut<'_, 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

pub fn rows(&self) -> RowsIter<'_, T>

Iterate over rows of the image as slices

Each slice is guaranteed to be exactly width pixels wide.

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
) -> Self

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) -> Self

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: Copy> Img<Vec<T>>

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().

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.

impl<T: Clone> Img<Cow<'_, [T]>>

pub fn into_owned(self) -> ImgVec<T>

Convert underlying buffer to owned (e.g. slice to vec)

See also to_contiguous_buf().0.into_owned()

impl<T> Img<T> where
    T: ToOwned, 

pub fn to_owned(&self) -> Img<T::Owned>

Convert underlying buffer to owned (e.g. slice to vec)

See also to_contiguous_buf().0.into_owned()

Trait Implementations

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

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: Debug> Debug for Img<Container>

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

Formats the value using the given formatter.

impl<'a, T: Clone> From<Img<&'a [T]>> for Img<Cow<'a, [T]>>

fn from(img: ImgRef<'a, T>) -> Self

Performs the conversion.

impl<T: Clone> From<Img<Cow<'_, [T]>>> for Img<Vec<T>>

fn from(img: Img<Cow<'_, [T]>>) -> Self

Performs the conversion.

impl<T: Clone> From<Img<Vec<T, Global>>> for Img<Cow<'static, [T]>>

fn from(img: ImgVec<T>) -> Self

Performs the conversion.

impl<Pixel, Container> ImgExt<Pixel> for Img<Container> where
    Container: AsRef<[Pixel]>, 

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.

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 as_ref(&self) -> ImgRef<'_, Pixel>

Borrow the container

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

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

fn as_mut(&mut self) -> ImgRefMut<'_, Pixel>

Borrow the container mutably

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

fn index(&self, index: (u32, u32)) -> &Self::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.

type Output = Pixel

The returned type after indexing.

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

fn index(&self, index: (u32, u32)) -> &Self::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.

type Output = Pixel

The returned type after indexing.

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

fn index(&self, index: (u32, u32)) -> &Self::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.

type Output = Pixel

The returned type after indexing.

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

fn index(&self, index: (usize, usize)) -> &Self::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.

type Output = Pixel

The returned type after indexing.

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

fn index(&self, index: (usize, usize)) -> &Self::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.

type Output = Pixel

The returned type after indexing.

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

fn index(&self, index: (usize, usize)) -> &Self::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.

type Output = Pixel

The returned type after indexing.

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

fn index(&self, row: usize) -> &Self::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.

type Output = [Pixel]

The returned type after indexing.

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

fn index(&self, row: usize) -> &Self::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.

type Output = [Pixel]

The returned type after indexing.

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

fn index(&self, row: usize) -> &Self::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.

type Output = [Pixel]

The returned type after indexing.

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

fn index_mut(&mut self, index: (u32, u32)) -> &mut Self::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: Copy> IndexMut<(u32, u32)> for Img<Vec<Pixel>>

fn index_mut(&mut self, index: (u32, u32)) -> &mut Self::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: Copy> IndexMut<(usize, usize)> for Img<&'a mut [Pixel]>

fn index_mut(&mut self, index: (usize, usize)) -> &mut Self::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: Copy> IndexMut<(usize, usize)> for Img<Vec<Pixel>>

fn index_mut(&mut self, index: (usize, usize)) -> &mut Self::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: Copy> IndexMut<usize> for Img<&'a mut [Pixel]>

fn index_mut(&mut self, row: usize) -> &mut Self::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: Copy> IndexMut<usize> for Img<Vec<Pixel>>

fn index_mut(&mut self, row: usize) -> &mut Self::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, 

Deprecated. Use .rows() or .pixels() iterators which are more predictable

fn into_iter(self) -> Container::IntoIter

Deprecated. Use .rows() or .pixels() iterators which are more predictable

type Item = Container::Item

The type of the elements being iterated over.

type IntoIter = Container::IntoIter

Which kind of iterator are we turning this into?

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

fn eq(&self, other: &ImgRef<'a, U>) -> 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<'a, 'b, T, U> PartialEq<Img<&'b [U]>> for ImgRef<'a, T> where
    T: PartialEq<U>, 

fn eq(&self, other: &ImgRef<'b, U>) -> 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<'a, 'b, T, U> PartialEq<Img<&'b [U]>> for ImgRefMut<'a, T> where
    T: PartialEq<U>, 

fn eq(&self, other: &ImgRef<'b, U>) -> 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<'a, 'b, T, U> PartialEq<Img<&'b mut [U]>> for ImgRefMut<'a, T> where
    T: PartialEq<U>, 

fn eq(&self, other: &ImgRefMut<'b, U>) -> 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<'a, 'b, T, U> PartialEq<Img<&'b mut [U]>> for ImgRef<'a, T> where
    T: PartialEq<U>, 

fn eq(&self, other: &ImgRefMut<'b, U>) -> 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<T, U> PartialEq<Img<Vec<U, Global>>> for ImgVec<T> where
    T: PartialEq<U>, 

fn eq(&self, other: &ImgVec<U>) -> 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<'a, T, U> PartialEq<Img<Vec<U, Global>>> for ImgRef<'a, T> where
    T: PartialEq<U>, 

fn eq(&self, other: &ImgVec<U>) -> 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<Container: Copy> Copy for Img<Container>