Debian Codegraph @

.cargo/vendor/imgref/src/lib.rs

raw
1 //! In graphics code it's very common to pass `width` and `height` along with a `Vec` of pixels,
2 //! all as separate arguments. This is tedious, and can lead to errors.
3 //!
4 //! This crate is a simple struct that adds dimensions to the underlying buffer. This makes it easier to correctly keep track
5 //! of the image size and allows passing images with just one function argument instead three or four.
6 //!
7 //! Additionally, it has a concept of a `stride`, which allows defining sub-regions of images without copying,
8 //! as well as handling padding (e.g. buffers for video frames may require to be a multiple of 8, regardless of logical image size).
9 //!
10 //! For convenience, there are iterators over rows or all pixels of a (sub)image and
11 //! pixel-based indexing directly with `img[(x,y)]` (where `x`/`y` can be `u32` as well as `usize`).
12 //!
13 //! `Img<Container>` type has aliases for common uses:
14 //!
15 //! * Owned: `ImgVec<T>` → `Img<Vec<T>>` (use it in `struct`s and return types)
16 //! * Reference: `ImgRef<T>` → `Img<&[T]>` (use it in function arguments)
17 //! * Mutable reference: `ImgRefMut<T>` → `Img<&mut [T]>`
18 //!
19 //! It is assumed that the container is [one element per pixel](https://crates.io/crates/rgb/), e.g. `Vec<RGBA>`,
20 //! and _not_ a `Vec<u8>` where 4 `u8` elements are interpreted as one pixel.
21 //!
22 //!
23 //! ```rust
24 //! use imgref::*;
25 //! # fn some_image_processing_function(img: ImgRef<u8>) -> ImgVec<u8> { img.new_buf(img.buf().to_vec()) }
26 //!
27 //! fn main() {
28 //! let img = Img::new(vec![0; 1000], 50, 20); // 1000 pixels of a 50×20 image
29 //!
30 //! let new_image = some_image_processing_function(img.as_ref()); // Use imgvec.as_ref() instead of &imgvec for better efficiency
31 //!
32 //! println!("New size is {}×{}", new_image.width(), new_image.height());
33 //! println!("And the top left pixel is {:?}", new_image[(0u32,0u32)]);
34 //!
35 //! let first_row_slice = &new_image[0];
36 //!
37 //! for row in new_image.rows() {
38 //! // …
39 //! }
40 //! for px in new_image.pixels() {
41 //! // …
42 //! }
43 //!
44 //! // slice (x, y, width, height) by reference - no copy!
45 //! let fragment = img.sub_image(5, 5, 15, 15);
46 //!
47 //! //
48 //! let (vec, width, height) = fragment.to_contiguous_buf();
49 //! }
50 //! ```
51
52 #![no_std]
53
54 extern crate alloc;
55 #[cfg(test)]
56 extern crate std;
57
58 use alloc::borrow::{Cow, ToOwned};
59 use alloc::vec::Vec;
60 use core::slice;
61
62 mod traits;
63
64 mod iter;
65 mod ops;
66 pub use iter::*;
67
68 /// Image owning its pixels.
69 ///
70 /// A 2D array of pixels. The pixels are oriented top-left first and rows are `stride` pixels wide.
71 ///
72 /// If size of the `buf` is larger than `width`*`height`, then any excess space is a padding (see `width_padded()`/`height_padded()`).
73 pub type ImgVec<Pixel> = Img<Vec<Pixel>>;
74
75 /// Reference to pixels inside another image.
76 /// Pass this structure by value (i.e. `ImgRef`, not `&ImgRef`).
77 ///
78 /// Only `width` of pixels of every `stride` can be modified. The `buf` may be longer than `height`*`stride`, but the extra space should be ignored.
79 pub type ImgRef<'slice, Pixel> = Img<&'slice [Pixel]>;
80
81 /// Same as `ImgRef`, but mutable
82 /// Pass this structure by value (i.e. `ImgRef`, not `&ImgRef`).
83 ///
84 pub type ImgRefMut<'slice, Pixel> = Img<&'slice mut [Pixel]>;
85
86 /// Additional methods that depend on buffer size
87 ///
88 /// To use these methods you need:
89 ///
90 /// ```rust
91 /// use imgref::*;
92 /// ```
93 pub trait ImgExt<Pixel> {
94 /// Maximum possible width of the data, including the stride.
95 ///
96 /// # Panics
97 ///
98 /// This method may panic if the underlying buffer is not at least `height()*stride()` pixels large.
99 #[cfg(feature = "deprecated")]
100 fn width_padded(&self) -> usize;
101
102 /// Height in number of full strides.
103 /// If the underlying buffer is not an even multiple of strides, the last row is ignored.
104 ///
105 /// # Panics
106 ///
107 /// This method may panic if the underlying buffer is not at least `height()*stride()` pixels large.
108 #[cfg(feature = "deprecated")]
109 fn height_padded(&self) -> usize;
110
111 /// Iterate over the entire buffer as rows, including all padding
112 ///
113 /// Rows will have up to `stride` width, but the last row may be shorter.
114 #[cfg(feature = "deprecated")]
115 fn rows_padded(&self) -> slice::Chunks<'_, Pixel>;
116
117 /// Borrow the container
118 fn as_ref(&self) -> ImgRef<'_, Pixel>;
119 }
120
121 /// Additional methods that depend on buffer size
122 ///
123 /// To use these methods you need:
124 ///
125 /// ```rust
126 /// use imgref::*;
127 /// ```
128 pub trait ImgExtMut<Pixel> {
129 /// Iterate over the entire buffer as rows, including all padding
130 ///
131 /// Rows will have up to `stride` width, but the last row may be shorter.
132 #[cfg(feature = "deprecated")]
133 fn rows_padded_mut(&mut self) -> slice::ChunksMut<'_, Pixel>;
134
135 /// Borrow the container mutably
136 fn as_mut(&mut self) -> ImgRefMut<'_, Pixel>;
137 }
138
139 /// Basic struct used for both owned (alias `ImgVec`) and borrowed (alias `ImgRef`) image fragments.
140 ///
141 /// Note: the fields are `pub` only because of borrow checker limitations. Please consider them as read-only.
142 #[derive(Debug, Copy, Clone)]
143 pub struct Img<Container> {
144 /// Storage for the pixels. Usually `Vec<Pixel>` or `&[Pixel]`. See `ImgVec` and `ImgRef`.
145 ///
146 /// Note that future version will make this field private. Use `.rows()` and `.pixels()` iterators where possible, or `buf()`/`buf_mut()`/`into_buf()`.
147 #[deprecated(note = "Don't access struct fields directly. Use buf(), buf_mut() or into_buf()")]
148 #[cfg(feature = "deprecated")]
149 pub buf: Container,
150
151 #[cfg(not(feature = "deprecated"))]
152 buf: Container,
153
154 /// Number of pixels to skip in the container to advance to the next row.
155 ///
156 /// Note: pixels between `width` and `stride` may not be usable, and may not even exist in the last row.
157 #[deprecated(note = "Don't access struct fields directly. Use stride()")]
158 #[cfg(feature = "deprecated")]
159 pub stride: usize,
160
161 #[cfg(not(feature = "deprecated"))]
162 stride: usize,
163
164 /// Width of the image in pixels.
165 ///
166 /// Note that this isn't same as the width of the row in the `buf`, see `stride`
167 #[deprecated(note = "Don't access struct fields directly. Use width()")]
168 #[cfg(feature = "deprecated")]
169 pub width: u32,
170
171 #[cfg(not(feature = "deprecated"))]
172 width: u32,
173
174 /// Height of the image in pixels.
175 #[deprecated(note = "Don't access struct fields directly. Use height()")]
176 #[cfg(feature = "deprecated")]
177 pub height: u32,
178
179 #[cfg(not(feature = "deprecated"))]
180 height: u32,
181 }
182
183 impl<Container> Img<Container> {
184 /// Width of the image in pixels.
185 ///
186 /// Note that this isn't same as the width of the row in image data, see `stride()`
187 #[inline(always)]
188 #[allow(deprecated)]
189 pub const fn width(&self) -> usize { self.width as usize }
190
191 /// Height of the image in pixels.
192 #[inline(always)]
193 #[allow(deprecated)]
194 pub const fn height(&self) -> usize { self.height as usize }
195
196 /// Number of _pixels_ to skip in the container to advance to the next row.
197 ///
198 /// Note the last row may have fewer pixels than the stride.
199 /// Some APIs use number of *bytes* for a stride. You may need to multiply this one by number of pixels.
200 #[inline(always)]
201 #[allow(deprecated)]
202 pub const fn stride(&self) -> usize { self.stride }
203
204 /// Immutable reference to the pixel storage. Warning: exposes stride. Use `pixels()` or `rows()` instead.
205 ///
206 /// See also `into_contiguous_buf()`.
207 #[inline(always)]
208 #[allow(deprecated)]
209 pub const fn buf(&self) -> &Container { &self.buf }
210
211 /// Mutable reference to the pixel storage. Warning: exposes stride. Use `pixels_mut()` or `rows_mut()` instead.
212 ///
213 /// See also `into_contiguous_buf()`.
214 #[inline(always)]
215 #[allow(deprecated)]
216 pub fn buf_mut(&mut self) -> &mut Container { &mut self.buf }
217
218 /// Get the pixel storage by consuming the image. Be careful about stride — see `into_contiguous_buf()` for a safe version.
219 #[inline(always)]
220 #[allow(deprecated)]
221 pub fn into_buf(self) -> Container { self.buf }
222
223 #[deprecated(note = "this was meant to be private, use new_buf() and/or rows()")]
224 #[cfg(feature = "deprecated")]
225 #[doc(hidden)]
226 pub fn rows_buf<'buf, T: 'buf>(&self, buf: &'buf [T]) -> RowsIter<'buf, T> {
227 self.rows_buf_internal(buf)
228 }
229
230 #[inline]
231 #[track_caller]
232 fn rows_buf_internal<'buf, T: 'buf>(&self, buf: &'buf [T]) -> RowsIter<'buf, T> {
233 let stride = self.stride();
234 debug_assert!(self.width() <= self.stride());
235 debug_assert!(buf.len() >= self.width() * self.height());
236 assert!(stride > 0);
237 let non_padded = &buf[0..stride * self.height() + self.width() - stride];
238 RowsIter {
239 width: self.width(),
240 inner: non_padded.chunks(stride),
241 }
242 }
243 }
244
245 impl<Pixel,Container> ImgExt<Pixel> for Img<Container> where Container: AsRef<[Pixel]> {
246 #[inline(always)]
247 #[cfg(feature = "deprecated")]
248 fn width_padded(&self) -> usize {
249 self.stride()
250 }
251
252 #[inline(always)]
253 #[cfg(feature = "deprecated")]
254 fn height_padded(&self) -> usize {
255 let len = self.buf().as_ref().len();
256 assert_eq!(0, len % self.stride());
257 len / self.stride()
258 }
259
260 /// Iterate over the entire buffer as rows, including all padding
261 ///
262 /// Rows will have up to `stride` width, but the last row may be shorter.
263 #[inline(always)]
264 #[cfg(feature = "deprecated")]
265 fn rows_padded(&self) -> slice::Chunks<'_, Pixel> {
266 self.buf().as_ref().chunks(self.stride())
267 }
268
269 #[inline(always)]
270 #[allow(deprecated)]
271 fn as_ref(&self) -> ImgRef<'_, Pixel> {
272 Img {
273 buf: self.buf.as_ref(),
274 width: self.width,
275 height: self.height,
276 stride: self.stride,
277 }
278 }
279 }
280
281 impl<Pixel,Container> ImgExtMut<Pixel> for Img<Container> where Container: AsMut<[Pixel]> {
282 /// Iterate over the entire buffer as rows, including all padding
283 ///
284 /// Rows will have up to `stride` width, but the last row may be shorter.
285 ///
286 /// # Panics
287 ///
288 /// If stride is 0
289 #[cfg(feature = "deprecated")]
290 fn rows_padded_mut(&mut self) -> slice::ChunksMut<'_, Pixel> {
291 let stride = self.stride();
292 self.buf_mut().as_mut().chunks_mut(stride)
293 }
294
295 #[inline(always)]
296 #[allow(deprecated)]
297 fn as_mut(&mut self) -> ImgRefMut<'_, Pixel> {
298 Img {
299 buf: self.buf.as_mut(),
300 width: self.width,
301 height: self.height,
302 stride: self.stride,
303 }
304 }
305 }
306
307 #[inline]
308 fn sub_image(left: usize, top: usize, width: usize, height: usize, stride: usize, buf_len: usize) -> (usize, usize, usize) {
309 let start = stride * top + left;
310 let full_strides_end = start + stride * height;
311 // when left > 0 and height is full, the last line is shorter than the stride
312 let end = if buf_len >= full_strides_end {
313 full_strides_end
314 } else {
315 debug_assert!(height > 0);
316 let min_strides_len = full_strides_end + width - stride;
317 debug_assert!(buf_len >= min_strides_len, "the buffer is too small to fit the subimage");
318 // if can't use full buffer, then shrink to min required (last line having exact width)
319 min_strides_len
320 };
321 (start, end, stride)
322 }
323
324 impl<'slice, T> ImgRef<'slice, T> {
325 /// Make a reference for a part of the image, without copying any pixels.
326 ///
327 /// # Panics
328 ///
329 /// It will panic if `sub_image` is outside of the image area
330 /// (left + width must be <= container width, etc.)
331 #[inline]
332 #[must_use]
333 #[track_caller]
334 pub fn sub_image(&self, left: usize, top: usize, width: usize, height: usize) -> Self {
335 assert!(top + height <= self.height());
336 assert!(left + width <= self.width());
337 let (start, end, stride) = sub_image(left, top, width, height, self.stride(), self.buf().len());
338 let buf = &self.buf()[start..end];
339 Self::new_stride(buf, width, height, stride)
340 }
341
342 #[inline]
343 /// Iterate over whole rows of pixels as slices
344 ///
345 /// # Panics
346 ///
347 /// If stride is 0
348 ///
349 /// See also `pixels()`
350 pub fn rows(&self) -> RowsIter<'slice, T> {
351 self.rows_buf_internal(self.buf())
352 }
353
354 /// Deprecated
355 ///
356 /// Note: it iterates **all** pixels in the underlying buffer, not just limited by width/height.
357 #[deprecated(note = "Size of this buffer is unpredictable. Use .rows() instead")]
358 #[cfg(feature = "deprecated")]
359 #[doc(hidden)]
360 pub fn iter(&self) -> slice::Iter<'slice, T> {
361 self.buf().iter()
362 }
363 }
364
365 impl<'a, T: Clone> ImgRef<'a, T> {
366 /// Returns a reference to the buffer, width, height. Guarantees that the buffer is contiguous,
367 /// i.e. it's `width*height` elements long, and `[x + y*width]` addresses each pixel.
368 ///
369 /// It will create a copy if the buffer isn't contiguous (width != stride).
370 /// For a more efficient version, see `into_contiguous_buf()`
371 #[allow(deprecated)]
372 #[must_use]
373 pub fn to_contiguous_buf(&self) -> (Cow<'a, [T]>, usize, usize) {
374 let width = self.width();
375 let height = self.height();
376 let stride = self.stride();
377 if width == stride {
378 return (Cow::Borrowed(self.buf), width, height);
379 }
380 let mut buf = Vec::with_capacity(width * height);
381 for row in self.rows() {
382 buf.extend_from_slice(row);
383 }
384 (Cow::Owned(buf), width, height)
385 }
386 }
387
388 impl<'slice, T> ImgRefMut<'slice, T> {
389 /// Turn this into immutable reference, and slice a subregion of it
390 #[inline]
391 #[allow(deprecated)]
392 #[must_use]
393 pub fn sub_image(&'slice self, left: usize, top: usize, width: usize, height: usize) -> ImgRef<'slice, T> {
394 self.as_ref().sub_image(left, top, width, height)
395 }
396
397 /// Slices this image reference to produce another reference to a subregion of it.
398 ///
399 /// Note that mutable borrows are exclusive, so it's not possible to have more than
400 /// one mutable subimage at a time.
401 ///
402 /// ## Panics
403 ///
404 /// If the coordinates are out of bounds
405 #[inline]
406 #[allow(deprecated)]
407 #[must_use]
408 #[track_caller]
409 pub fn sub_image_mut(&mut self, left: usize, top: usize, width: usize, height: usize) -> ImgRefMut<'_, T> {
410 assert!(top + height <= self.height());
411 assert!(left + width <= self.width());
412 let (start, end, stride) = sub_image(left, top, width, height, self.stride(), self.buf.len());
413 let buf = &mut self.buf[start..end];
414 ImgRefMut::new_stride(buf, width, height, stride)
415 }
416
417 /// Transforms this image reference to refer to a subregion.
418 ///
419 /// This is identical in behavior to [`ImgRefMut::sub_image_mut()`], except that it returns an
420 /// [`ImgRefMut`] with the same lifetime, rather than a reborrow with a shorter lifetime.
421 ///
422 /// ## Panics
423 ///
424 /// If the coordinates are out of bounds
425 #[allow(deprecated)]
426 #[must_use]
427 #[track_caller]
428 pub fn into_sub_image_mut(self, left: usize, top: usize, width: usize, height: usize) -> Self {
429 assert!(top + height <= self.height());
430 assert!(left + width <= self.width());
431 let (start, end, stride) = sub_image(left, top, width, height, self.stride(), self.buf.len());
432 let buf = &mut self.buf[start..end];
433 ImgRefMut::new_stride(buf, width, height, stride)
434 }
435
436 /// Make mutable reference immutable
437 #[inline]
438 #[must_use]
439 pub fn as_ref(&self) -> ImgRef<'_, T> {
440 self.new_buf(self.buf().as_ref())
441 }
442 }
443
444 impl<'slice, T: Copy> ImgRef<'slice, T> {
445 /// Iterate `width*height` pixels in the `Img`, ignoring padding area
446 ///
447 /// If you want to iterate in parallel, parallelize `rows()` instead.
448 ///
449 /// # Panics
450 ///
451 /// if width is 0
452 #[inline]
453 #[track_caller]
454 pub fn pixels(&self) -> PixelsIter<'slice, T> {
455 PixelsIter::new(*self)
456 }
457 }
458
459 impl<'slice, T> ImgRef<'slice, T> {
460 /// Iterate `width*height` pixels in the `Img`, by reference, ignoring padding area
461 ///
462 /// If you want to iterate in parallel, parallelize `rows()` instead.
463 ///
464 /// # Panics
465 ///
466 /// if width is 0
467 #[inline]
468 pub fn pixels_ref(&self) -> PixelsRefIter<'slice, T> {
469 PixelsRefIter::new(*self)
470 }
471 }
472
473 impl<T: Copy> ImgRefMut<'_, T> {
474 /// # Panics
475 ///
476 /// If you want to iterate in parallel, parallelize `rows()` instead.
477 ///
478 /// if width is 0
479 #[inline]
480 pub fn pixels(&self) -> PixelsIter<'_, T> {
481 PixelsIter::new(self.as_ref())
482 }
483 }
484
485 impl<T> ImgRefMut<'_, T> {
486 /// If you want to iterate in parallel, parallelize `rows()` instead.
487 /// # Panics
488 ///
489 /// if width is 0
490 #[inline]
491 pub fn pixels_mut(&mut self) -> PixelsIterMut<'_, T> {
492 PixelsIterMut::new(self)
493 }
494 }
495
496 impl<T: Copy> ImgVec<T> {
497 /// If you want to iterate in parallel, parallelize `rows()` instead.
498 /// # Panics
499 ///
500 /// if width is 0
501 #[inline]
502 pub fn pixels(&self) -> PixelsIter<'_, T> {
503 PixelsIter::new(self.as_ref())
504 }
505 }
506
507 impl<T> ImgVec<T> {
508 /// If you want to iterate in parallel, parallelize `rows()` instead.
509 /// # Panics
510 ///
511 /// if width is 0
512 #[inline]
513 pub fn pixels_mut(&mut self) -> PixelsIterMut<'_, T> {
514 PixelsIterMut::new(&mut self.as_mut())
515 }
516 }
517
518 impl<T> ImgRefMut<'_, T> {
519 /// Iterate over whole rows as slices
520 ///
521 /// # Panics
522 ///
523 /// if stride is 0
524 #[inline]
525 pub fn rows(&self) -> RowsIter<'_, T> {
526 self.rows_buf_internal(&self.buf()[..])
527 }
528
529 /// Iterate over whole rows as slices
530 ///
531 /// # Panics
532 ///
533 /// if stride is 0
534 #[inline]
535 #[allow(deprecated)]
536 pub fn rows_mut(&mut self) -> RowsIterMut<'_, T> {
537 let stride = self.stride();
538 let width = self.width();
539 let height = self.height();
540 let non_padded = &mut self.buf[0..stride * height + width - stride];
541 RowsIterMut {
542 width,
543 inner: non_padded.chunks_mut(stride),
544 }
545 }
546 }
547
548 /// Deprecated. Use .`rows()` or .`pixels()` iterators which are more predictable
549 #[cfg(feature = "deprecated")]
550 impl<Container> IntoIterator for Img<Container> where Container: IntoIterator {
551 type Item = Container::Item;
552 type IntoIter = Container::IntoIter;
553 /// Deprecated. Use .`rows()` or .`pixels()` iterators which are more predictable
554 fn into_iter(self) -> Container::IntoIter {
555 self.into_buf().into_iter()
556 }
557 }
558
559 impl<T> ImgVec<T> {
560 /// Create a mutable view into a region within the image. See `sub_image()` for read-only views.
561 ///
562 /// ## Panics
563 ///
564 /// If the coordinates are out of bounds
565 #[allow(deprecated)]
566 #[must_use]
567 #[track_caller]
568 pub fn sub_image_mut(&mut self, left: usize, top: usize, width: usize, height: usize) -> ImgRefMut<'_, T> {
569 assert!(top + height <= self.height());
570 assert!(left + width <= self.width());
571 let start = self.stride * top + left;
572 let min_buf_size = if self.height > 0 { self.stride * height + width - self.stride } else {0};
573 let buf = &mut self.buf[start .. start + min_buf_size];
574 Img::new_stride(buf, width, height, self.stride)
575 }
576
577 #[inline]
578 #[must_use]
579 /// Make a reference for a part of the image, without copying any pixels.
580 pub fn sub_image(&self, left: usize, top: usize, width: usize, height: usize) -> ImgRef<'_, T> {
581 self.as_ref().sub_image(left, top, width, height)
582 }
583
584 /// Make a reference to this image to pass it to functions without giving up ownership
585 ///
586 /// The reference should be passed by value (`ImgRef`, not `&ImgRef`).
587 ///
588 /// If you need a mutable reference, see `as_mut()` and `sub_image_mut()`
589 #[inline]
590 #[must_use]
591 pub fn as_ref(&self) -> ImgRef<'_, T> {
592 self.new_buf(self.buf().as_ref())
593 }
594
595 /// Make a mutable reference to the entire image
596 ///
597 /// The reference should be passed by value (`ImgRefMut`, not `&mut ImgRefMut`).
598 ///
599 /// See also `sub_image_mut()` and `rows_mut()`
600 #[inline]
601 pub fn as_mut(&mut self) -> ImgRefMut<'_, T> {
602 let width = self.width();
603 let height = self.height();
604 let stride = self.stride();
605 Img::new_stride(self.buf_mut().as_mut(), width, height, stride)
606 }
607
608 #[deprecated(note = "Size of this buffer may be unpredictable. Use .rows() instead")]
609 #[cfg(feature = "deprecated")]
610 #[doc(hidden)]
611 pub fn iter(&self) -> slice::Iter<'_, T> {
612 self.buf().iter()
613 }
614
615 /// Iterate over rows of the image as slices
616 ///
617 /// Each slice is guaranteed to be exactly `width` pixels wide.
618 ///
619 /// This iterator is a good candidate for parallelization (e.g. rayon's `par_bridge()`)
620 #[inline]
621 pub fn rows(&self) -> RowsIter<'_, T> {
622 self.rows_buf_internal(self.buf())
623 }
624
625 /// Iterate over rows of the image as mutable slices
626 ///
627 /// Each slice is guaranteed to be exactly `width` pixels wide.
628 ///
629 /// This iterator is a good candidate for parallelization (e.g. rayon's `par_bridge()`)
630 #[inline]
631 #[allow(deprecated)]
632 pub fn rows_mut(&mut self) -> RowsIterMut<'_, T> {
633 let stride = self.stride();
634 let width = self.width();
635 let height = self.height();
636 let non_padded = &mut self.buf[0..stride * height + width - stride];
637 RowsIterMut {
638 width,
639 inner: non_padded.chunks_mut(stride),
640 }
641 }
642 }
643
644 impl<Container> Img<Container> {
645 /// Same as `new()`, except each row is located `stride` number of pixels after the previous one.
646 ///
647 /// 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.
648 ///
649 /// The `Container` is usually a `Vec` or a slice.
650 ///
651 /// ## Panics
652 ///
653 /// If stride is 0.
654 #[inline]
655 #[allow(deprecated)]
656 #[track_caller]
657 pub fn new_stride(buf: Container, width: usize, height: usize, stride: usize) -> Self {
658 assert!(stride > 0);
659 assert!(stride >= width);
660 debug_assert!(height < u32::MAX as usize);
661 debug_assert!(width < u32::MAX as usize);
662 Self {
663 buf,
664 width: width as u32,
665 height: height as u32,
666 stride,
667 }
668 }
669
670 /// Create new image with `Container` (which can be `Vec`, `&[]` or something else) with given `width` and `height` in pixels.
671 ///
672 /// Assumes the pixels in container are contiguous, layed out row by row with `width` pixels per row and at least `height` rows.
673 ///
674 /// If the container is larger than `width`×`height` pixels, the extra rows are a considered a padding and may be ignored.
675 #[inline]
676 pub fn new(buf: Container, width: usize, height: usize) -> Self {
677 Self::new_stride(buf, width, height, width)
678 }
679 }
680
681 impl<T: Copy> Img<Vec<T>> {
682 /// Returns the buffer, width, height. Guarantees that the buffer is contiguous,
683 /// i.e. it's `width*height` elements long, and `[x + y*width]` addresses each pixel.
684 ///
685 /// Efficiently performs operation in-place. For other containers use `pixels().collect()`.
686 #[allow(deprecated)]
687 #[must_use]
688 pub fn into_contiguous_buf(mut self) -> (Vec<T>, usize, usize) {
689 let (_, w, h) = self.as_contiguous_buf();
690 (self.buf, w, h)
691 }
692
693 /// Returns a reference to the buffer, width, height. Guarantees that the buffer is contiguous,
694 /// i.e. it's `width*height` elements long, and `[x + y*width]` addresses each pixel.
695 ///
696 /// Efficiently performs operation in-place. For other containers use `pixels().collect()`.
697 #[allow(deprecated)]
698 #[must_use]
699 pub fn as_contiguous_buf(&mut self) -> (&[T], usize, usize) {
700 let width = self.width();
701 let height = self.height();
702 let stride = self.stride();
703 if width != stride {
704 for row in 1..height {
705 self.buf.copy_within(row * stride .. row * stride + width, row * width);
706 }
707 }
708 self.buf.truncate(width * height);
709 (&mut self.buf, width, height)
710 }
711 }
712
713 impl<OldContainer> Img<OldContainer> {
714 /// A convenience method for creating an image of the same size and stride, but with a new buffer.
715 #[inline]
716 #[track_caller]
717 pub fn map_buf<NewContainer, OldPixel, NewPixel, F>(self, callback: F) -> Img<NewContainer>
718 where NewContainer: AsRef<[NewPixel]>, OldContainer: AsRef<[OldPixel]>, F: FnOnce(OldContainer) -> NewContainer {
719 let width = self.width();
720 let height = self.height();
721 let stride = self.stride();
722 let old_buf_len = self.buf().as_ref().len();
723 #[allow(deprecated)]
724 let new_buf = callback(self.buf);
725 assert_eq!(old_buf_len, new_buf.as_ref().len());
726 Img::new_stride(new_buf, width, height, stride)
727 }
728
729 /// A convenience method for creating an image of the same size and stride, but with a new buffer.
730 #[inline]
731 #[track_caller]
732 pub fn new_buf<NewContainer, OldPixel, NewPixel>(&self, new_buf: NewContainer) -> Img<NewContainer>
733 where NewContainer: AsRef<[NewPixel]>, OldContainer: AsRef<[OldPixel]> {
734 assert_eq!(self.buf().as_ref().len(), new_buf.as_ref().len());
735 Img::new_stride(new_buf, self.width(), self.height(), self.stride())
736 }
737 }
738
739 impl<T: Clone> From<Img<Cow<'_, [T]>>> for Img<Vec<T>> {
740 #[allow(deprecated)]
741 fn from(img: Img<Cow<'_, [T]>>) -> Self {
742 Self {
743 width: img.width,
744 height: img.height,
745 stride: img.stride,
746 buf: img.buf.into_owned(),
747 }
748 }
749 }
750
751 impl<T: Clone> From<ImgVec<T>> for Img<Cow<'static, [T]>> {
752 #[allow(deprecated)]
753 fn from(img: ImgVec<T>) -> Self {
754 Img {
755 width: img.width,
756 height: img.height,
757 stride: img.stride,
758 buf: img.buf.into(),
759 }
760 }
761 }
762
763 impl<'a, T: Clone> From<ImgRef<'a, T>> for Img<Cow<'a, [T]>> {
764 #[allow(deprecated)]
765 fn from(img: ImgRef<'a, T>) -> Self {
766 Img {
767 buf: img.buf.into(),
768 width: img.width,
769 height: img.height,
770 stride: img.stride,
771 }
772 }
773 }
774
775 impl<T: Clone> Img<Cow<'_, [T]>> {
776 /// Convert underlying buffer to owned (e.g. slice to vec)
777 ///
778 /// See also `to_contiguous_buf().0.into_owned()`
779 #[allow(deprecated)]
780 #[must_use]
781 pub fn into_owned(self) -> ImgVec<T> {
782 match self.buf {
783 Cow::Borrowed(_) => {
784 let tmp = self.as_ref();
785 let (buf, w, h) = tmp.to_contiguous_buf();
786 ImgVec::new(buf.into_owned(), w, h)
787 },
788 Cow::Owned(buf) => Img {
789 buf,
790 width: self.width,
791 height: self.height,
792 stride: self.stride,
793 },
794 }
795 }
796 }
797
798 impl<T> Img<T> where T: ToOwned {
799 /// Convert underlying buffer to owned (e.g. slice to vec)
800 ///
801 /// See also `to_contiguous_buf().0.into_owned()`
802 #[allow(deprecated)]
803 pub fn to_owned(&self) -> Img<T::Owned> {
804 Img {
805 buf: self.buf.to_owned(),
806 width: self.width,
807 height: self.height,
808 stride: self.stride,
809 }
810 }
811 }
812
813 #[cfg(test)]
814 mod tests {
815 use super::*;
816 use alloc::vec;
817
818 mod with_opinionated_container {
819 use super::*;
820
821 struct IDontDeriveAnything;
822
823 #[test]
824 fn compiles() {
825 let _ = Img::new(IDontDeriveAnything, 1, 1);
826 }
827 }
828
829 #[test]
830 fn with_vec() {
831 let bytes = vec![0u8;20];
832 let old = Img::new_stride(bytes, 10,2,10);
833 let _ = old.new_buf(vec![6u16;20]);
834 }
835
836 #[test]
837 fn zero() {
838 let bytes = vec![0u8];
839 let mut img = Img::new_stride(bytes,0,0,1);
840 let _ = img.sub_image(0,0,0,0);
841 let _ = img.sub_image_mut(0,0,0,0);
842 let _ = img.as_ref();
843 }
844
845 #[test]
846 fn zero_width() {
847 let bytes = vec![0u8];
848 let mut img = Img::new_stride(bytes,0,1,1);
849 let _ = img.sub_image(0,1,0,0);
850 let _ = img.sub_image_mut(0,0,0,1);
851 }
852
853 #[test]
854 fn zero_height() {
855 let bytes = vec![0u8];
856 let mut img = Img::new_stride(bytes,1,0,1);
857 assert_eq!(0, img.rows().count());
858 let _ = img.sub_image(1,0,0,0);
859 let _ = img.sub_image_mut(0,0,1,0);
860 }
861
862 #[test]
863 #[allow(deprecated)]
864 fn with_slice() {
865 let bytes = vec![0u8;20];
866 let _ = Img::new_stride(bytes.as_slice(), 10,2,10);
867 let vec = ImgVec::new_stride(bytes, 10,2,10);
868
869 #[cfg(feature = "deprecated")]
870 for _ in vec.iter() {}
871
872 assert_eq!(2, vec.rows().count());
873 for _ in *vec.as_ref().buf() {}
874
875 #[cfg(feature = "deprecated")]
876 for _ in vec {}
877 }
878
879 #[test]
880 fn sub() {
881 let img = Img::new_stride(vec![1,2,3,4,
882 5,6,7,8,
883 9], 3, 2, 4);
884 assert_eq!(img.buf()[img.stride()], 5);
885 assert_eq!(img.buf()[img.stride() + img.width()-1], 7);
886
887 assert_eq!(img.pixels().count(), img.width() * img.height());
888 assert_eq!(img.pixels().sum::<i32>(), 24);
889
890 {
891 let refimg = img.as_ref();
892 let refimg2 = refimg; // Test is Copy
893
894 // sub-image with stride hits end of the buffer
895 let s1 = refimg.sub_image(1, 0, refimg.width()-1, refimg.height());
896 let _ = s1.sub_image(1, 0, s1.width()-1, s1.height());
897
898 let subimg = refimg.sub_image(1, 1, 2, 1);
899 assert_eq!(subimg.pixels().count(), subimg.width() * subimg.height());
900
901 assert_eq!(subimg.buf()[0], 6);
902 assert_eq!(subimg.stride(), refimg2.stride());
903 assert!(subimg.stride() * subimg.height() + subimg.width() - subimg.stride() <= subimg.buf().len());
904 assert_eq!(refimg.buf()[0], 1);
905 assert_eq!(1, subimg.rows().count());
906 }
907
908 // 3 different methods for constructing mutable sub-images
909 let mut img_for_mut_1 = img.clone();
910 let mut img_for_mut_2 = img.clone();
911 let mut img_for_mut_3 = img;
912 for mut subimg in [
913 img_for_mut_1.sub_image_mut(1, 1, 2, 1),
914 img_for_mut_2.as_mut().sub_image_mut(1, 1, 2, 1),
915 img_for_mut_3.as_mut().into_sub_image_mut(1, 1, 2, 1),
916 ] {
917 assert_eq!(1, subimg.rows().count());
918 assert_eq!(1, subimg.rows_mut().count());
919 assert_eq!(1, subimg.rows_mut().rev().count());
920 assert_eq!(1, subimg.rows_mut().fuse().rev().count());
921 assert_eq!(subimg.buf()[0], 6);
922 }
923 }
924
925 #[test]
926 fn rows() {
927 let img = ImgVec::new_stride(vec![0u8; 10000], 10, 15, 100);
928 assert_eq!(img.height(), img.rows().count());
929 assert_eq!(img.height(), img.rows().rev().count());
930 assert_eq!(img.height(), img.rows().fuse().rev().count());
931 }
932
933 #[test]
934 fn mut_pixels() {
935 for y in 1..15 {
936 for x in 1..10 {
937 let mut img = ImgVec::new_stride(vec![0u8; 10000], x, y, 100);
938 assert_eq!(x*y, img.pixels_mut().count());
939 assert_eq!(x*y, img.as_mut().pixels().count());
940 assert_eq!(x*y, img.as_mut().pixels_mut().count());
941 assert_eq!(x*y, img.as_mut().as_ref().pixels().count());
942 }
943 }
944 }
945
946 #[test]
947 fn into_contiguous_buf() {
948 for in_h in [1, 2, 3, 38, 39, 40, 41].iter().copied() {
949 for in_w in [1, 2, 3, 120, 121].iter().copied() {
950 for stride in [in_w, 121, 122, 166, 242, 243].iter().copied() {
951 let img = ImgVec::new_stride((0..10000).map(|x| x as u8).collect(), in_w, in_h, stride)
952 .map_buf(|x| x);
953 let pixels: Vec<_> = img.pixels().collect();
954 let (buf, w, h) = img.into_contiguous_buf();
955 assert_eq!(pixels, buf);
956 assert_eq!(in_w*in_h, buf.len());
957 assert_eq!(10000, buf.capacity());
958 assert_eq!(in_w, w);
959 assert_eq!(in_h, h);
960 }
961 }
962 }
963
964 let img = ImgVec::new((0..55*33).map(|x| x as u8).collect(), 55, 33);
965 let pixels: Vec<_> = img.pixels().collect();
966 let tmp = img.as_ref();
967 let (buf, ..) = tmp.to_contiguous_buf();
968 assert_eq!(&pixels[..], &buf[..]);
969 let (buf, ..) = img.into_contiguous_buf();
970 assert_eq!(pixels, buf);
971 }
972 }