Merge pull request #299 from SolderedElectronics/dev-image-dither-fix

Dev image dither fix

Author: JosipKuci

src/graphics/Image/Image.cpp

@@ -25,40 +25,51 @@
 Image *_imagePtrJpeg = nullptr;
 Image *_imagePtrPng = nullptr;
 
-// uint8_t (*Image::ditherBuffer)[E_INK_WIDTH + 20] = nullptr;
-__attribute__((section(".ext_ram.bss"))) uint8_t Image::ditherBuffer[2][E_INK_WIDTH + 20];
-__attribute__((section(".ext_ram.bss"))) uint8_t Image::jpegDitherBuffer[18][18];
-// uint8_t (*Image::jpegDitherBuffer)[18] = nullptr;
+int16_t (*Image::ditherBuffer)[E_INK_WIDTH + 20] = nullptr;
 uint8_t *Image::pixelBuffer = nullptr;
 uint32_t *Image::ditherPalette = nullptr;
 uint8_t *Image::palette = nullptr;
 
+/**
+ * @brief       begin initialises the Image subsystem.
+ *              Must be called once before any draw functions are used.
+ *
+ *              Stores the Inkplate pointer, registers the JPEG/PNG callback
+ *              pointers, allocates all PSRAM buffers needed for dithering and
+ *              pixel staging, and sets the default dither kernel.
+ *
+ * @param       Inkplate *inkplateptr
+ *              Pointer to the parent Inkplate instance.
+ */
 void Image::begin(Inkplate *inkplateptr)
 {
     _inkplate = inkplateptr;
+
+    // Register this instance as the target for JPEG and PNG decode callbacks.
     _imagePtrJpeg = this;
     _imagePtrPng = this;
 
-
-    // jpegDitherBuffer = (uint8_t (*)[18])heap_caps_calloc(18, 18, MALLOC_CAP_SPIRAM);
-
-
-    // ditherBuffer = (uint8_t (*)[E_INK_WIDTH + 20])heap_caps_calloc(2, (E_INK_WIDTH + 20), MALLOC_CAP_SPIRAM);
-
-
+    // Allocate PSRAM buffers. All four are required; a NULL result is reported
+    // via Serial and the caller should not attempt to draw images.
+    ditherBuffer = (int16_t(*)[E_INK_WIDTH + 20]) heap_caps_calloc(1, ditherBufferSizeBytes, MALLOC_CAP_SPIRAM);
     pixelBuffer = (uint8_t *)heap_caps_calloc(1, (E_INK_WIDTH * 4 + 5), MALLOC_CAP_SPIRAM);
-
-
     ditherPalette = (uint32_t *)heap_caps_calloc(256, sizeof(uint32_t), MALLOC_CAP_SPIRAM);
-
-
     palette = (uint8_t *)heap_caps_calloc(128, sizeof(uint8_t), MALLOC_CAP_SPIRAM);
 
-
-    if (!jpegDitherBuffer || !ditherBuffer || !pixelBuffer || !ditherPalette || !palette)
+    if (!ditherBuffer || !pixelBuffer || !ditherPalette || !palette)
     {
         Serial.println(" Failed to allocate one or more buffers (SRAM/PSRAM)");
     }
+
+    setDitherKernel(FloydSteinberg);
+}
+
+void Image::setDitherKernel(const DitherKernel kernel)
+{
+    const uint8_t kernelIndex = static_cast<uint8_t>(kernel);
+    if (kernelIndex >= DITHER_KERNEL_COUNT)
+        return;
+    currentKernel = &DITHER_KERNELS[kernelIndex];
 }
 
 /**

src/graphics/Image/Image.h

@@ -20,6 +20,7 @@
 #define __IMAGE_H__
 #if !defined(ARDUINO_INKPLATECOLOR) && !defined(ARDUINO_INKPLATE2) && !defined(ARDUINO_INKPLATE13SPECTRA)
 #include "../../features/SdFat/SdFat.h"
+#include "ImageDitherKernels.h"
 #include "WiFi.h"
 
 class Inkplate;
@@ -64,6 +65,17 @@ class Image
         _npos
     } Position;
 
+    typedef enum
+    {
+        FloydSteinberg = 0,
+        JarvisJudiceNinke,
+        Atkinson,
+        Burkes,
+        Stucki,
+        SierraLite,
+        ReducedDiffusion
+    } DitherKernel;
+
 
     Inkplate *_inkplate = NULL;
 
@@ -105,33 +117,41 @@ class Image
     bool drawPngFromWeb(const char *url, int x, int y, bool dither = 0, bool invert = 0);
     bool drawPngFromWeb(WiFiClient *s, int x, int y, int32_t len, bool dither = 0, bool invert = 0);
 
-    // Should be private, but needed in a png callback :(
-    void ditherSwap(int w);
     uint8_t ditherGetPixelBmp(uint32_t px, int i, int j, int w, bool paletted);
 
+    void setDitherKernel(const DitherKernel kernel);
+
     void getPointsForPosition(const Position &position, const uint16_t imageWidth, const uint16_t imageHeight,
                               const uint16_t screenWidth, const uint16_t screenHeight, uint16_t *posX, uint16_t *posY);
-    uint8_t findClosestPalette(int16_t r, int16_t g, int16_t b);
 
 
   private:
     static uint8_t *pixelBuffer;
-    static uint8_t jpegDitherBuffer[18][18];
-    static uint8_t ditherBuffer[2][E_INK_WIDTH + 20];
+    static const uint8_t ditherRowCount = 4;
+    static const uint8_t ditherRowMask = ditherRowCount - 1;
+    static int16_t (*ditherBuffer)[E_INK_WIDTH + 20];
+    static constexpr size_t ditherBufferSizeBytes = ditherRowCount * (E_INK_WIDTH + 20) * sizeof(int16_t);
     static uint32_t *ditherPalette; // 8 bit colors, in color, 3x8 bit colors
     static uint8_t *palette;        // 2 3 bit colors per byte, _###_###
 
+    const DitherKernelDef *currentKernel = &DITHER_KERNELS[0];
+
     uint16_t _lastTileRowY = -1;
 
     static bool drawJpegChunk(int16_t x, int16_t y, uint16_t w, uint16_t h, uint16_t *bitmap, bool dither, bool invert);
 
     int16_t blockW = 0, blockH = 0;
     int16_t lastY = -1;
 
+    uint16_t *jpegRowBuffer = nullptr;
+    uint16_t jpegImageWidth = 0;
+    uint8_t jpegMcuH = 0;
+    int jpegDrawX = 0, jpegDrawY = 0;
+    bool jpegDither = false, jpegInvert = false;
+
     bool legalBmp(bitmapHeader *bmpHeader);
 
-    uint8_t ditherGetPixelJpeg(uint8_t px, int i, int j, int x, int y, int w, int h);
-    void ditherSwapBlockJpeg(int x);
+    void flushJpegRow(int rowY);
 
     void readBmpHeader(uint8_t *buf, bitmapHeader *_h);
     void readBmpHeaderSd(SdFile *_f, bitmapHeader *_h);

src/graphics/Image/ImageDither.cpp

@@ -21,127 +21,59 @@
 
 
 /**
- * @brief       ditherGetPixelBmp calculates dither for given pixel in bmp
- * images
+ * @brief       ditherGetPixelBmp calculates dither for given pixel using the
+ *              currently selected kernel. The dither buffer is a circular
+ *              buffer indexed by j & ditherRowMask so error propagates
+ *              naturally across row and block boundaries without any swap step.
  *
  * @param       uint32_t px
- *              pixel value with color information
+ *              pixel value (8-bit grayscale or palette index)
  * @param       int i
- *              ditherBuffer width plane position
+ *              absolute column position
+ * @param       int j
+ *              absolute row position
  * @param       int w
- *              image width
+ *              image width (used for error-diffusion boundary clamping)
  * @param       bool paletted
- *              1 if paletted image, 0 if not
+ *              true if px is a palette index that should be looked up first
  *
- * @return      new pixel value (dithered pixel)
+ * @return      new dithered pixel value (3-bit grayscale, 0-7)
  */
 uint8_t Image::ditherGetPixelBmp(uint32_t px, int i, int j, int w, bool paletted)
 {
     if (paletted)
         px = ditherPalette[px];
 
-    if (_inkplate->getDisplayMode() == INKPLATE_1BIT)
-        px = (uint16_t)px >> 1;
+    const int rowIdx = j & ditherRowMask;
+    int16_t *row = ditherBuffer[rowIdx];
 
-    uint8_t oldPixel = min((uint16_t)0xFF, (uint16_t)((uint16_t)ditherBuffer[0][i] + px));
+    int16_t oldPixel = (int16_t)px + row[i];
+    row[i] = 0; // clear after reading
 
-    uint8_t newPixel = oldPixel & (_inkplate->getDisplayMode() == INKPLATE_1BIT ? B10000000 : B11100000);
-    uint8_t quantError = oldPixel - newPixel;
+    oldPixel = max((int16_t)0, min((int16_t)255, oldPixel));
 
-    ditherBuffer[1][i + 0] += (quantError * 5) >> 4;
-    if (i != w - 1)
-    {
-        ditherBuffer[0][i + 1] += (quantError * 7) >> 4;
-        ditherBuffer[1][i + 1] += (quantError * 1) >> 4;
-    }
-    if (i != 0)
-        ditherBuffer[1][i - 1] += (quantError * 3) >> 4;
+    // 1-bit: snap to 0x00 or 0xFF so that >>5 produces 0 or 7 (full display range).
+    // 3-bit: quantise to the top 3 bits; >>5 produces 0-7.
+    uint8_t newPixel = (_inkplate->getDisplayMode() == INKPLATE_1BIT) ? ((oldPixel >= 128) ? 0xFF : 0x00)
+                                                                      : ((uint8_t)oldPixel & B11100000);
+    int16_t quantError = oldPixel - newPixel;
 
-    return newPixel >> 5;
-}
+    const int minOffset = max(-currentKernel->x, -i);
+    const int maxOffset = min(currentKernel->width - currentKernel->x - 1, w - 1 - i);
 
-/**
- * @brief       ditherGetPixelJpeg calculates dither for given pixel in jpeg
- * images
- *
- * @param       uint8_t px
- *              pixel value with color information
- * @param       int i
- *              ditherBuffer width plane position
- * @param       int j
- *              ditherBuffer height plane position
- * @param       int x
- *              x image starting position
- * @param       int y
- *              y image starting position
- * @param       int w
- *              image width
- * @param       int h
- *              image height
- *
- * @return      new pixel value (dithered pixel)
- */
-uint8_t Image::ditherGetPixelJpeg(uint8_t px, int i, int j, int x, int y, int w, int h)
-{
-    if (blockW == -1)
+    for (int k = 0; k < currentKernel->height; ++k)
     {
-        blockW = w;
-        blockH = h;
+        int16_t *nextRow = ditherBuffer[(rowIdx + k) & ditherRowMask];
+        for (int l = minOffset; l <= maxOffset; ++l)
+        {
+            const int weight = currentKernel->data[k * currentKernel->width + (l + currentKernel->x)];
+            if (!weight)
+                continue;
+            nextRow[i + l] += (weight * quantError) / currentKernel->coef;
+        }
     }
 
-    if (_inkplate->getDisplayMode() == INKPLATE_1BIT)
-        px = (uint16_t)px >> 1;
-
-    uint16_t oldPixel = min((uint16_t)0xFF, (uint16_t)((uint16_t)px + (uint16_t)jpegDitherBuffer[j + 1][i + 1] +
-                                                       (j ? (uint16_t)0 : (uint16_t)ditherBuffer[0][x + i])));
-
-    uint8_t newPixel = oldPixel & (_inkplate->getDisplayMode() == INKPLATE_1BIT ? B10000000 : B11100000);
-    uint8_t quantError = oldPixel - newPixel;
-
-    jpegDitherBuffer[j + 1 + 1][i + 0 + 1] += (quantError * 5) >> 4;
-
-    jpegDitherBuffer[j + 0 + 1][i + 1 + 1] += (quantError * 7) >> 4;
-    jpegDitherBuffer[j + 1 + 1][i + 1 + 1] += (quantError * 1) >> 4;
-
-    jpegDitherBuffer[j + 1 + 1][i - 1 + 1] += (quantError * 3) >> 4;
-
     return newPixel >> 5;
 }
 
-/**
- * @brief       ditherSwap swaps ditherBuffer values
- *
- * @param       int w
- *              screen width
- */
-void Image::ditherSwap(int w)
-{
-    for (int i = 0; i < w; ++i)
-    {
-        ditherBuffer[0][i] = ditherBuffer[1][i];
-        ditherBuffer[1][i] = 0;
-    }
-}
-
-/**
- * @brief       ditherSwapBlockJpeg swaps ditherBuffer values
- *
- * @param       int x
- *              x plane image starting point
- */
-void Image::ditherSwapBlockJpeg(int x)
-{
-    for (int i = 0; i < 18; ++i)
-    {
-        if (x + i)
-            ditherBuffer[1][x + i - 1] += jpegDitherBuffer[blockH - 1 + 2][i];
-        jpegDitherBuffer[i][0 + 1] = jpegDitherBuffer[i][blockW - 1 + 2];
-    }
-    for (int j = 0; j < 18; ++j)
-        for (int i = 0; i < 18; ++i)
-            if (i != 1)
-                jpegDitherBuffer[j][i] = 0;
-
-    jpegDitherBuffer[17][1] = 0;
-}
-#endif
+#endif

src/graphics/Image/ImageDitherKernels.h

@@ -0,0 +1,73 @@
+/**
+ **************************************************
+ * @file        ImageDitherKernels.h
+ * @brief       Dither kernel definitions for grayscale images
+ *
+ *              https://github.com/e-radionicacom/Inkplate-Arduino-library
+ *              For support, please reach over forums: forum.e-radionica.com/en
+ *              For more info about the product, please check: www.inkplate.io
+ *
+ *              This code is released under the GNU Lesser General Public
+ *License v3.0: https://www.gnu.org/licenses/lgpl-3.0.en.html Please review the
+ *LICENSE file included with this example. If you have any questions about
+ *licensing, please contact techsupport@e-radionica.com Distributed as-is; no
+ *warranty is given.
+ *
+ * @authors     Soldered
+ ***************************************************/
+#pragma once
+#if !defined(ARDUINO_INKPLATECOLOR) && !defined(ARDUINO_INKPLATE2) && !defined(ARDUINO_INKPLATE13SPECTRA)
+
+struct DitherKernelDef
+{
+    uint8_t width;
+    uint8_t height;
+    uint8_t x;
+    uint16_t coef;
+    const unsigned char *data;
+};
+
+// Floyd Steinberg
+static const unsigned char _kernelFloydSteinberg[] = {
+    0, 0, 7, 3, 5, 1,
+};
+
+// J F Jarvis, C N Judice, and W H Ninke "Minimized Average Error"
+static const unsigned char _kernelJarvisJudiceNinke[] = {
+    0, 0, 0, 7, 5, 3, 5, 7, 5, 3, 1, 3, 5, 3, 1,
+};
+
+// Atkinson
+static const unsigned char _kernelAtkinson[] = {
+    0, 0, 1, 1, 1, 1, 1, 0, 0, 1, 0, 0,
+};
+
+// Burkes
+static const unsigned char _kernelBurkes[] = {
+    0, 0, 0, 8, 4, 2, 4, 8, 4, 2, 0, 0, 0, 0, 0,
+};
+
+// Stucki
+static const unsigned char _kernelStucki[] = {
+    0, 0, 0, 8, 4, 2, 4, 8, 4, 2, 1, 2, 4, 2, 1,
+};
+
+// Sierra lite
+static const unsigned char _kernelSierraLite[] = {
+    0, 0, 2, 1, 1, 0, 0, 0, 0,
+};
+
+static const unsigned char _kernelReducedDiffusion[] = {
+    0, 0, 5, 2, 3, 1,
+};
+
+static const DitherKernelDef DITHER_KERNELS[] = {
+    {3, 2, 1, 16, _kernelFloydSteinberg},   {5, 3, 2, 48, _kernelJarvisJudiceNinke},
+    {4, 3, 1, 8, _kernelAtkinson},          {5, 3, 2, 32, _kernelBurkes},
+    {5, 3, 2, 42, _kernelStucki},           {3, 3, 1, 4, _kernelSierraLite},
+    {3, 2, 1, 26, _kernelReducedDiffusion},
+};
+
+static const uint8_t DITHER_KERNEL_COUNT = sizeof DITHER_KERNELS / sizeof DITHER_KERNELS[0];
+
+#endif