Enum CowImage

pub enum CowImage<'a, F: PixelFormat> {
    Borrowed(ImageRef<'a, F>),
    Owned(OImage<F>),
}

A Copy-on-Write (CoW) image that can either borrow or own its pixel data.

CowImage provides a flexible way to work with image data that may be either borrowed from an existing source or owned by the container. This is particularly useful in scenarios where you want to avoid unnecessary copying when possible, but still provide owned data when needed.

The enum has two variants:

• Borrowed: Contains an ImageRef that borrows data from elsewhere
• Owned: Contains an OImage that owns its pixel data

Both variants implement the same image traits, allowing them to be used interchangeably in most contexts.

Type Parameters

• F - The pixel format type that implements PixelFormat

Examples

// Create from borrowed data
let data = [128u8; 100];
let borrowed_ref = ImageRef::<Mono8>::new(10, 10, 10, &data).unwrap();
let cow_borrowed = CowImage::from(borrowed_ref);

// Create from owned data
let owned_image = OImage::<Mono8>::new(10, 10, 10, vec![64u8; 100]).unwrap();
let cow_owned = CowImage::from(owned_image);

Variants

Borrowed(ImageRef<'a, F>)

Borrowed image data with a lifetime tied to the source

Owned(OImage<F>)

Owned image data that manages its own memory

Implementations

impl<'a, F: PixelFormat> CowImage<'a, F>

pub fn owned(self) -> OImage<F>

Consumes the image and returns an owned image.

For borrowed images, this copies the data into a new image. For owned images, this moves the existing data without copying.

Examples

let owned_image = OImage::<Mono8>::new(4, 4, 4, vec![255u8; 16]).unwrap();
let cow_image = CowImage::from(owned_image);
let owned = cow_image.owned();

Trait Implementations

impl<'a, F: PixelFormat> From<ImageRef<'a, F>> for CowImage<'a, F>

fn from(frame: ImageRef<'a, F>) -> CowImage<'a, F>

Creates a CowImage::Borrowed from an ImageRef.

Examples

let data = [0u8; 300]; // 10x10 RGB image
let image_ref = ImageRef::<RGB8>::new(10, 10, 30, &data).unwrap();
let cow_image = CowImage::from(image_ref);

impl<'a, F: PixelFormat> From<OImage<F>> for CowImage<'a, F>

fn from(frame: OImage<F>) -> CowImage<'a, F>

Creates a CowImage::Owned from an OImage.

Examples

let owned_image = OImage::<Mono8>::new(20, 15, 20, vec![128u8; 300]).unwrap();
let cow_image = CowImage::from(owned_image);

impl<F: PixelFormat> ImageData<F> for CowImage<'_, F>

fn width(&self) -> u32

Returns the width of the image in pixels.

Examples

let owned_image = OImage::<RGB8>::new(25, 20, 75, vec![0u8; 1500]).unwrap();
let cow_image = CowImage::from(owned_image);
assert_eq!(cow_image.width(), 25);

fn height(&self) -> u32

Returns the height of the image in pixels.

Examples

let data = [0u8; 200];
let image_ref = ImageRef::<Mono8>::new(10, 20, 10, &data).unwrap();
let cow_image = CowImage::from(image_ref);
assert_eq!(cow_image.height(), 20);

fn buffer_ref(&self) -> ImageBufferRef<'_, F>

Returns a reference to the image buffer.

This provides access to the pixel data regardless of whether the image is borrowed or owned.

Examples

let owned_image = OImage::<Mono8>::new(5, 5, 5, vec![42u8; 25]).unwrap();
let cow_image = CowImage::from(owned_image);
let buffer_ref = cow_image.buffer_ref();

fn buffer(self) -> ImageBuffer<F>

Consumes the image and returns the pixel data as an owned buffer.

For borrowed images, this copies the data into a new vector. For owned images, this moves the existing data without copying.

Examples

let owned_image = OImage::<Mono8>::new(4, 4, 4, vec![255u8; 16]).unwrap();
let cow_image = CowImage::from(owned_image);
let buffer = cow_image.buffer();

fn image_data(&self) -> &[u8]

Returns the raw image data as specified by pixel format F.

impl<F: PixelFormat> Stride for CowImage<'_, F>

fn stride(&self) -> usize

Returns the stride (bytes per row) of the image.

Examples

let owned_image = OImage::<Mono8>::new(10, 10, 12, vec![0u8; 120]).unwrap();
let cow_image = CowImage::from(owned_image);
assert_eq!(cow_image.stride(), 12);