Add support for RLE encoded bitmaps. (#41)

* Add experimental support for RLE8 encoded bitmaps.

* Update CHANGELOG and README.

* Now you can display RLE8 bitmaps.

Also adds tests and benchmarks.

* Add RLE4 support.

The count is of nibbles, but the padding only applies when there's an odd number of bytes. And the sequences alternate between nibbles. But otherwise it's similar to RLE8.

* Increase MSRV to 1.71

* Applying review comments.

* Faster RLE rendering.

We can't render a whole frame as a contiguous block, we but we can render each line contiguously - we just have to start at the bottom line and work up.

---------

Co-authored-by: Ralf Fuest <[email protected]>

Author: thejpster

.circleci/config.yml

@@ -1,7 +1,7 @@
 # Check that everything (tests, benches, etc) builds in std environments
 precheck_steps: &precheck_steps
   docker: &docker
-    - image: jamwaffles/circleci-embedded-graphics:1.61.0-0
+    - image: jamwaffles/circleci-embedded-graphics:1.71.1-0
       auth:
         username: jamwaffles
         password: $DOCKERHUB_PASSWORD

CHANGELOG.md

@@ -6,6 +6,14 @@
 
 ## [Unreleased] - ReleaseDate
 
+### Added
+
+- [#41](https://github.com/embedded-graphics/tinybmp/pull/41) Added support for RLE8 and RLE4 encoded bitmaps
+
+### Changed
+
+- **(breaking)** [#41](https://github.com/embedded-graphics/tinybmp/pull/41) Use 1.71 as the MSRV.
+
 ## [0.5.0] - 2023-05-17
 
 ### Changed

README.md

@@ -79,6 +79,10 @@ let pixel = bmp.pixel(Point::new(3, 2));
 assert_eq!(pixel, Some(Rgb888::WHITE));
 ```
 
+Note that you currently cannot access invidual pixels when working with RLE4
+or RLE8 compressed indexed bitmaps. With these formats the `pixel()`
+function will always return `None`.
+
 ### Accessing the raw image data
 
 For most applications the higher level access provided by [`Bmp`] is sufficient. But in case
@@ -92,7 +96,7 @@ Similar to [`Bmp::pixel`], [`RawBmp::pixel`] can be used to get raw pixel color
 
 ```rust
 use embedded_graphics::prelude::*;
-use tinybmp::{RawBmp, Bpp, Header, RawPixel, RowOrder};
+use tinybmp::{RawBmp, Bpp, Header, RawPixel, RowOrder, CompressionMethod};
 
 let bmp = RawBmp::from_slice(include_bytes!("../tests/chessboard-8px-24bit.bmp"))
     .expect("Failed to parse BMP image");
@@ -108,6 +112,7 @@ assert_eq!(
         image_data_len: 192,
         channel_masks: None,
         row_order: RowOrder::BottomUp,
+        compression_method: CompressionMethod::Rgb,
     }
 );
 
@@ -126,7 +131,7 @@ assert_eq!(pixel, Some(0xFFFFFFu32));
 
 ## Minimum supported Rust version
 
-The minimum supported Rust version for tinybmp is `1.61` or greater. Ensure you have the correct
+The minimum supported Rust version for tinybmp is `1.71` or greater. Ensure you have the correct
 version of Rust installed, preferably through <https://rustup.rs>.
 
 [`Bmp`]: https://docs.rs/tinybmp/latest/tinybmp/struct.Bmp.html

benches/draw.rs

@@ -98,6 +98,16 @@ fn parser_benchmarks(c: &mut Criterion) {
         })
     });
 
+    c.bench_function("draw indexed 4BPP RLE4", |b| {
+        let mut fb = Framebuffer::<Rgb888>::new();
+        b.iter(|| {
+            let bmp =
+                Bmp::<Rgb888>::from_slice(include_bytes!("../tests/logo-indexed-4bpp-rle4.bmp"))
+                    .unwrap();
+            Image::new(&bmp, Point::zero()).draw(&mut fb).unwrap();
+        })
+    });
+
     c.bench_function("draw indexed 8BPP", |b| {
         let mut fb = Framebuffer::<Rgb888>::new();
         b.iter(|| {
@@ -107,6 +117,16 @@ fn parser_benchmarks(c: &mut Criterion) {
         })
     });
 
+    c.bench_function("draw indexed 8BPP RLE8", |b| {
+        let mut fb = Framebuffer::<Rgb888>::new();
+        b.iter(|| {
+            let bmp =
+                Bmp::<Rgb888>::from_slice(include_bytes!("../tests/logo-indexed-8bpp-rle8.bmp"))
+                    .unwrap();
+            Image::new(&bmp, Point::zero()).draw(&mut fb).unwrap();
+        })
+    });
+
     c.bench_function("draw dynamic RGB565 to RGB888", |b| {
         let mut fb = Framebuffer::<Rgb888>::new();
         b.iter(|| {

src/header/mod.rs

@@ -104,6 +104,9 @@ pub struct Header {
 
     /// Row order of the image data within the file
     pub row_order: RowOrder,
+
+    /// The compression method
+    pub compression_method: CompressionMethod,
 }
 
 impl Header {
@@ -144,6 +147,7 @@ impl Header {
                     bpp: dib_header.bpp,
                     channel_masks: dib_header.channel_masks,
                     row_order: dib_header.row_order,
+                    compression_method: dib_header.compression,
                 },
                 color_table,
             ),
@@ -199,16 +203,29 @@ impl ChannelMasks {
     };
 }
 
+/// Describes how the BMP file is compressed.
 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
 pub enum CompressionMethod {
+    /// The bitmap is in uncompressed RGB and doesn't use color masks
     Rgb,
+    /// The bitmap is in uncompressed RGB, using color masks
     Bitfields,
+    /// The bitmap is compressed using run-length encoding (RLE) compression,
+    /// with 8 bits per pixel. The compression uses a 2-byte format consisting
+    /// of a count byte followed by a byte containing a color index.
+    Rle8,
+    /// The bitmap is compressed using run-length encoding (RLE) compression,
+    /// with 4 bits per pixel. The compression uses a 2-byte format consisting
+    /// of a count byte followed by two word-length color indexes.
+    Rle4,
 }
 
 impl CompressionMethod {
     const fn new(value: u32) -> Result<Self, ParseError> {
         Ok(match value {
             0 => Self::Rgb,
+            1 => Self::Rle8,
+            2 => Self::Rle4,
             3 => Self::Bitfields,
             _ => return Err(ParseError::UnsupportedCompressionMethod(value)),
         })

src/lib.rs

@@ -79,6 +79,10 @@
 //! # Ok::<(), core::convert::Infallible>(()) }
 //! ```
 //!
+//! Note that you currently cannot access invidual pixels when working with RLE4
+//! or RLE8 compressed indexed bitmaps. With these formats the `pixel()`
+//! function will always return `None`.
+//!
 //! ## Accessing the raw image data
 //!
 //! For most applications the higher level access provided by [`Bmp`] is sufficient. But in case
@@ -92,7 +96,7 @@
 //!
 //! ```
 //! use embedded_graphics::prelude::*;
-//! use tinybmp::{RawBmp, Bpp, Header, RawPixel, RowOrder};
+//! use tinybmp::{RawBmp, Bpp, Header, RawPixel, RowOrder, CompressionMethod};
 //!
 //! let bmp = RawBmp::from_slice(include_bytes!("../tests/chessboard-8px-24bit.bmp"))
 //!     .expect("Failed to parse BMP image");
@@ -108,6 +112,7 @@
 //!         image_data_len: 192,
 //!         channel_masks: None,
 //!         row_order: RowOrder::BottomUp,
+//!         compression_method: CompressionMethod::Rgb,
 //!     }
 //! );
 //!
@@ -128,7 +133,7 @@
 //!
 //! # Minimum supported Rust version
 //!
-//! The minimum supported Rust version for tinybmp is `1.61` or greater. Ensure you have the correct
+//! The minimum supported Rust version for tinybmp is `1.71` or greater. Ensure you have the correct
 //! version of Rust installed, preferably through <https://rustup.rs>.
 //!
 //! <!-- README-LINKS
@@ -188,9 +193,10 @@ mod raw_bmp;
 mod raw_iter;
 
 use raw_bmp::ColorType;
-use raw_iter::RawColors;
+use raw_iter::{RawColors, Rle4Pixels, Rle8Pixels};
 
 pub use color_table::ColorTable;
+pub use header::CompressionMethod;
 pub use header::{Bpp, ChannelMasks, Header, RowOrder};
 pub use iter::Pixels;
 pub use raw_bmp::RawBmp;
@@ -249,6 +255,7 @@ where
         D: DrawTarget<Color = C>,
     {
         let area = self.bounding_box();
+        let slice_size = Size::new(area.size.width, 1);
 
         match self.raw_bmp.color_type {
             ColorType::Index1 => {
@@ -271,33 +278,69 @@ where
                 }
             }
             ColorType::Index4 => {
+                let header = self.raw_bmp.header();
+                let fallback_color = C::from(Rgb888::BLACK);
                 if let Some(color_table) = self.raw_bmp.color_table() {
-                    let fallback_color = C::from(Rgb888::BLACK);
-
-                    let colors = RawColors::<RawU4>::new(&self.raw_bmp).map(|index| {
-                        color_table
-                            .get(u32::from(index.into_inner()))
-                            .map(Into::into)
-                            .unwrap_or(fallback_color)
-                    });
-
-                    target.fill_contiguous(&area, colors)
+                    if header.compression_method == CompressionMethod::Rle4 {
+                        let mut colors = Rle4Pixels::new(&self.raw_bmp).map(|raw_pixel| {
+                            color_table
+                                .get(raw_pixel.color)
+                                .map(Into::into)
+                                .unwrap_or(fallback_color)
+                        });
+                        // RLE produces pixels in bottom-up order, so we draw them line by line rather than the entire bitmap at once.
+                        for y in (0..area.size.height).rev() {
+                            let row = Rectangle::new(Point::new(0, y as i32), slice_size);
+                            target.fill_contiguous(
+                                &row,
+                                colors.by_ref().take(area.size.width as usize),
+                            )?;
+                        }
+                        Ok(())
+                    } else {
+                        // If we didn't detect a supported compression method, just intepret it as raw indexed nibbles.
+                        let colors = RawColors::<RawU4>::new(&self.raw_bmp).map(|index| {
+                            color_table
+                                .get(u32::from(index.into_inner()))
+                                .map(Into::into)
+                                .unwrap_or(fallback_color)
+                        });
+                        target.fill_contiguous(&area, colors)
+                    }
                 } else {
                     Ok(())
                 }
             }
             ColorType::Index8 => {
+                let header = self.raw_bmp.header();
+                let fallback_color = C::from(Rgb888::BLACK);
                 if let Some(color_table) = self.raw_bmp.color_table() {
-                    let fallback_color = C::from(Rgb888::BLACK);
-
-                    let colors = RawColors::<RawU8>::new(&self.raw_bmp).map(|index| {
-                        color_table
-                            .get(u32::from(index.into_inner()))
-                            .map(Into::into)
-                            .unwrap_or(fallback_color)
-                    });
-
-                    target.fill_contiguous(&area, colors)
+                    if header.compression_method == CompressionMethod::Rle8 {
+                        let mut colors = Rle8Pixels::new(&self.raw_bmp).map(|raw_pixel| {
+                            color_table
+                                .get(raw_pixel.color)
+                                .map(Into::into)
+                                .unwrap_or(fallback_color)
+                        });
+                        // RLE produces pixels in bottom-up order, so we draw them line by line rather than the entire bitmap at once.
+                        for y in (0..area.size.height).rev() {
+                            let row = Rectangle::new(Point::new(0, y as i32), slice_size);
+                            target.fill_contiguous(
+                                &row,
+                                colors.by_ref().take(area.size.width as usize),
+                            )?;
+                        }
+                        Ok(())
+                    } else {
+                        // If we didn't detect a supported compression method, just intepret it as raw indexed bytes.
+                        let colors = RawColors::<RawU8>::new(&self.raw_bmp).map(|index| {
+                            color_table
+                                .get(u32::from(index.into_inner()))
+                                .map(Into::into)
+                                .unwrap_or(fallback_color)
+                        });
+                        target.fill_contiguous(&area, colors)
+                    }
                 } else {
                     Ok(())
                 }

src/raw_bmp.rs

@@ -44,21 +44,14 @@ impl<'a> RawBmp<'a> {
 
         let color_type = ColorType::from_header(&header)?;
 
-        let height = header
-            .image_size
-            .height
-            .try_into()
-            .map_err(|_| ParseError::InvalidImageDimensions)?;
-
-        let data_length = header
-            .bytes_per_row()
-            .checked_mul(height)
-            .ok_or(ParseError::InvalidImageDimensions)?;
+        // Believe what the bitmap tells us rather than multiplying width by
+        // height by bits-per-pixel, because the image data might be compressed.
+        let compressed_data_length = header.image_data_len as usize;
 
         // The `get` is split into two calls to prevent an possible integer overflow.
         let image_data = &bytes
             .get(header.image_data_start..)
-            .and_then(|bytes| bytes.get(..data_length))
+            .and_then(|bytes| bytes.get(..compressed_data_length))
             .ok_or(ParseError::UnexpectedEndOfFile)?;
 
         Ok(Self {
@@ -97,7 +90,19 @@ impl<'a> RawBmp<'a> {
     ///
     /// Returns `None` if `p` is outside the image bounding box. Note that this function doesn't
     /// apply a color map, if the image contains one.
+    ///
+    /// This routine always returns `None` if the bitmap is RLE compressed, as RLE compressed
+    /// bitmaps don't easily allow direct access to any given pixel.
     pub fn pixel(&self, p: Point) -> Option<u32> {
+        if matches!(
+            self.header.compression_method,
+            crate::header::CompressionMethod::Rle8 | crate::header::CompressionMethod::Rle4
+        ) {
+            // TODO implement direct access by counting `0x00, 0x00` pairs,
+            // which uniquely mark the end of a line.
+            return None;
+        }
+
         let width = self.header.image_size.width as i32;
         let height = self.header.image_size.height as i32;