Added early abort option to PNGDRAW callback

bitbank2 · bitbank2 · commit db9ce9c2b8c8 · 2025-07-29T22:29:44.000+01:00
diff --git a/MacOS/PNG_Test/PNG_Test.xcodeproj/project.xcworkspace/xcuserdata/laurencebank.xcuserdatad/UserInterfaceState.xcuserstate b/MacOS/PNG_Test/PNG_Test.xcodeproj/project.xcworkspace/xcuserdata/laurencebank.xcuserdatad/UserInterfaceState.xcuserstate
diff --git a/MacOS/PNG_Test/PNG_Test/main.cpp b/MacOS/PNG_Test/PNG_Test/main.cpp
@@ -59,15 +59,17 @@ typedef struct my_private_struct
   int xoff, yoff; // corner offset
 } PRIVATE;
 // Second draw callback for testing conversion to RGB565
-void PNGDraw2(PNGDRAW *pDraw)
+int PNGDraw2(PNGDRAW *pDraw)
 {
 uint16_t usPixels[320];
     png.getLineAsRGB565(pDraw, usPixels, ucPixelType, u32BG);
     if (pDraw->y == 0) { // get first pixel of first line for testing
         u16Out = usPixels[0];
     }
+    return 1;
 } /* PNGDraw2() */
-void PNGDraw(PNGDRAW *pDraw)
+
+int PNGDraw(PNGDRAW *pDraw)
 {
 PRIVATE *pPriv = (PRIVATE *)pDraw->pUser;
     
@@ -83,8 +85,13 @@ PRIVATE *pPriv = (PRIVATE *)pDraw->pUser;
     iBpp = pDraw->iBpp;
     iWidth = pDraw->iWidth;
     iLines++;
+    return 1;
 } /* PNGDraw() */
 
+int PNGDraw3(PNGDRAW *pDraw)
+{
+    return 0; // abort the decode immediately
+}
 //
 // Simple logging print
 //
@@ -296,6 +303,23 @@ int main(int argc, const char * argv[]) {
         iTotalFail++;
         PNGLOG(__LINE__, szTestName, " - FAILED");
     }
+    // Test 10 - check the decoding can be aborted when the PNGDraw callback returns 0
+    ucPixelType = PNG_RGB565_BIG_ENDIAN;
+    szTestName = (char *)"PNG decode aborted early";
+    iTotal++;
+    PNGLOG(__LINE__, szTestName, szStart);
+    u16Out = 0xffff;
+    png.openFLASH((uint8_t *)octocat_8bpp, sizeof(octocat_8bpp), PNGDraw3);
+    png.setBuffer(NULL);
+    rc = png.decode(NULL, 0);
+    png.close();
+    if (rc == PNG_QUIT_EARLY) { // check transparnet pixel (0,0) to see if it matches the 32-bit BG color we asked for
+        iTotalPass++;
+        PNGLOG(__LINE__, szTestName, " - PASSED");
+    } else {
+        iTotalFail++;
+        PNGLOG(__LINE__, szTestName, " - FAILED");
+    }
 
     // FUZZ testing
     // Randomize the input data (file header and compressed data) and confirm that the library returns an error code
diff --git a/examples/1bpp_transparent_oled/1bpp_transparent_oled.ino b/examples/1bpp_transparent_oled/1bpp_transparent_oled.ino
@@ -47,13 +47,14 @@ uint8_t *d, ucPix, ucAlpha, ucMask;
   } // for each group of 8 pixels
 } /* DrawPixelsMasked() */
 
-void PNGDraw(PNGDRAW *pDraw)
+int PNGDraw(PNGDRAW *pDraw)
 {
 uint8_t ucMask[32];
 
   if (png.getAlphaMask(pDraw, ucMask, 255)) { // if any pixels are opaque, draw them
     DrawPixelsMasked(pDraw->y, pDraw->pPixels, ucMask, pDraw->iWidth);
   }
+  return 1;
 } /* PNGDraw() */
 
 void setup() {
diff --git a/examples/dma_perf_boost/dma_perf_boost.ino b/examples/dma_perf_boost/dma_perf_boost.ino
@@ -19,7 +19,7 @@ static uint16_t usPixels[320]; // make sure there is enough room for the full im
 // Called with a full row of pixels
 // for every row in the image
 //
-void PNGDraw(PNGDRAW *pDraw)
+int PNGDraw(PNGDRAW *pDraw)
 {
     if (pDraw->y == 0) {
       // set the address window when we get the first line
@@ -35,6 +35,7 @@ void PNGDraw(PNGDRAW *pDraw)
     } else {
       lcd.pushPixels(usPixels, pDraw->iWidth);
     }
+    return 1;
 } /* PNGDraw() */
 
 void setup()
@@ -75,4 +76,4 @@ void setup()
 void loop()
 {
 
-}
+}
diff --git a/examples/m5stickc_plus_test/m5logosmall.h b/examples/m5stickc_plus_test/m5logosmall.h
diff --git a/examples/png_benchmark/png_benchmark.ino b/examples/png_benchmark/png_benchmark.ino
@@ -17,13 +17,14 @@ typedef struct myprivate
   bool bConvert;
 } PRIVATE;
 
-void PNGDraw(PNGDRAW *pDraw)
+int PNGDraw(PNGDRAW *pDraw)
 {
 PRIVATE *pPriv = (PRIVATE *)pDraw->pUser;
 uint16_t usPixels[320];
 
   if (pPriv->bConvert)
      png.getLineAsRGB565(pDraw, usPixels, PNG_RGB565_LITTLE_ENDIAN, 0xffffffff); // don't do alpha color blending
+  return 1;
 } /* PNGDraw() */
 
 void setup() {
diff --git a/examples/png_comparison/png_comparison.ino b/examples/png_comparison/png_comparison.ino
@@ -75,7 +75,7 @@ void DecodeTest(int bLode, const uint8_t *pData, size_t data_size, const char *s
     }
 } /* DecodeTest() */
 
-void PNGDraw(PNGDRAW *pDraw)
+int PNGDraw(PNGDRAW *pDraw)
 {
   if (bDisplay) {
     if (pDraw->y == 0) {
@@ -84,6 +84,7 @@ void PNGDraw(PNGDRAW *pDraw)
     png->getLineAsRGB565(pDraw, usPixels, PNG_RGB565_BIG_ENDIAN, 0xffffffff);
     lcd.pushPixels(usPixels, pDraw->iWidth, DRAW_TO_LCD | DRAW_WITH_DMA);
   }
+  return 1;
 } /* PNGDraw() */
 
 void setup() {
diff --git a/examples/png_transparency/png_transparency.ino b/examples/png_transparency/png_transparency.ino
@@ -30,7 +30,7 @@ typedef struct my_private_struct
   int xoff, yoff; // corner offset
 } PRIVATE;
 
-void PNGDraw(PNGDRAW *pDraw)
+int PNGDraw(PNGDRAW *pDraw)
 {
 uint16_t usPixels[320];
 uint8_t ucMask[40];
@@ -40,6 +40,7 @@ PRIVATE *pPriv = (PRIVATE *)pDraw->pUser;
   if (png.getAlphaMask(pDraw, ucMask, 255)) { // if any pixels are opaque, draw them
     spilcdWritePixelsMasked(&lcd, pPriv->xoff, pPriv->yoff + pDraw->y, (uint8_t *)usPixels, ucMask, pDraw->iWidth, DRAW_TO_LCD);
   }
+  return 1;
 } /* PNGDraw() */
 
 void setup() {
diff --git a/examples/sdcard_slideshow/sdcard_slideshow.ino b/examples/sdcard_slideshow/sdcard_slideshow.ino
@@ -59,11 +59,12 @@ int32_t mySeek(PNGFILE *handle, int32_t position) {
 }
 
 // Function to draw pixels to the display
-void PNGDraw(PNGDRAW *pDraw) {
+int PNGDraw(PNGDRAW *pDraw) {
 uint16_t usPixels[320];
 
   png.getLineAsRGB565(pDraw, usPixels, PNG_RGB565_LITTLE_ENDIAN, 0xffffffff);
   tft.writeRect(0, pDraw->y + 24, pDraw->iWidth, 1, usPixels);
+  return 1;
 }
 
 // Main loop, scan for all .PNG files on the card and display them
diff --git a/library.properties b/library.properties
@@ -1,5 +1,5 @@
 name=PNGdec
-version=1.1.3
+version=1.1.4
 author=Larry Bank
 maintainer=Larry Bank
 sentence=Universal PNG decoder for MCUs with at least 48K of RAM.
diff --git a/src/PNGDisplay.inl b/src/PNGDisplay.inl
@@ -20,7 +20,7 @@
 #define __PNGDISPLAY_IMPL__
 #include "PNGDisplay.h"
 
-static void PNGDraw(PNGDRAW *pDraw)
+static int PNGDraw(PNGDRAW *pDraw)
 {
 int *pInfo = (int *)pDraw->pUser;
 uint16_t *p16;
@@ -32,6 +32,7 @@ PNG *pPNG;
     p16 = (uint16_t *)&pInfo[3]; // start of temporary pixel space
     pPNG->getLineAsRGB565(pDraw, p16, PNG_RGB565_BIG_ENDIAN, (uint32_t)pInfo[2]);
     pLCD->pushPixels(p16, pDraw->iWidth);
+    return 1;
 } /* PNGDraw() */
 
 // Functions to access a file on the SD card
diff --git a/src/PNGdec.h b/src/PNGdec.h
@@ -95,7 +95,8 @@ enum {
     PNG_NO_BUFFER,
     PNG_UNSUPPORTED_FEATURE,
     PNG_INVALID_FILE,
-    PNG_TOO_BIG
+    PNG_TOO_BIG,
+    PNG_QUIT_EARLY
 };
 
 typedef struct png_draw_tag
@@ -124,7 +125,7 @@ typedef struct png_file_tag
 typedef int32_t (PNG_READ_CALLBACK)(PNGFILE *pFile, uint8_t *pBuf, int32_t iLen);
 typedef int32_t (PNG_SEEK_CALLBACK)(PNGFILE *pFile, int32_t iPosition);
 typedef void * (PNG_OPEN_CALLBACK)(const char *szFilename, int32_t *pFileSize);
-typedef void (PNG_DRAW_CALLBACK)(PNGDRAW *);
+typedef int (PNG_DRAW_CALLBACK)(PNGDRAW *);
 typedef void (PNG_CLOSE_CALLBACK)(void *pHandle);
 
 //
diff --git a/src/png.inl b/src/png.inl
@@ -931,7 +931,10 @@ PNG_STATIC int DecodePNG(PNGIMAGE *pPage, void *pUser, int iOptions)
                                 pngd.iHasAlpha = pPage->iHasAlpha;
                                 pngd.iBpp = pPage->ucBpp;
                                 pngd.y = y;
-                                (*pPage->pfnDraw)(&pngd);
+                                if (!(*pPage->pfnDraw)(&pngd)) { // user code returned 0 from PNGDraw
+                                    pPage->iError = PNG_QUIT_EARLY;
+                                    return pPage->iError;
+                                }
                             } else {
                                 // copy to destination bitmap
                                 memcpy(&pPage->pImage[y * pPage->iPitch], &pCurr[1], pPage->iPitch);

Original file line number	Diff line number	Diff line change
`@@ -47,13 +47,14 @@ uint8_t *d, ucPix, ucAlpha, ucMask;`
`47`	`47`	`} // for each group of 8 pixels`
`48`	`48`	`} /* DrawPixelsMasked() */`
`49`	`49`
`50`		`-void PNGDraw(PNGDRAW *pDraw)`
	`50`	`+int PNGDraw(PNGDRAW *pDraw)`
`51`	`51`	`{`
`52`	`52`	`uint8_t ucMask[32];`
`53`	`53`
`54`	`54`	`if (png.getAlphaMask(pDraw, ucMask, 255)) { // if any pixels are opaque, draw them`
`55`	`55`	`DrawPixelsMasked(pDraw->y, pDraw->pPixels, ucMask, pDraw->iWidth);`
`56`	`56`	`}`
	`57`	`+ return 1;`
`57`	`58`	`} /* PNGDraw() */`
`58`	`59`
`59`	`60`	`void setup() {`
Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@ static uint16_t usPixels[320]; // make sure there is enough room for the full im`
`19`	`19`	`// Called with a full row of pixels`
`20`	`20`	`// for every row in the image`
`21`	`21`	`//`
`22`		`-void PNGDraw(PNGDRAW *pDraw)`
	`22`	`+int PNGDraw(PNGDRAW *pDraw)`
`23`	`23`	`{`
`24`	`24`	`if (pDraw->y == 0) {`
`25`	`25`	`// set the address window when we get the first line`
`@@ -35,6 +35,7 @@ void PNGDraw(PNGDRAW *pDraw)`
`35`	`35`	`} else {`
`36`	`36`	`lcd.pushPixels(usPixels, pDraw->iWidth);`
`37`	`37`	`}`
	`38`	`+ return 1;`
`38`	`39`	`} /* PNGDraw() */`
`39`	`40`
`40`	`41`	`void setup()`
`@@ -75,4 +76,4 @@ void setup()`
`75`	`76`	`void loop()`
`76`	`77`	`{`
`77`	`78`
`78`		`-}`
	`79`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,7 @@ void DecodeTest(int bLode, const uint8_t pData, size_t data_size, const char s`
`75`	`75`	`}`
`76`	`76`	`} /* DecodeTest() */`
`77`	`77`
`78`		`-void PNGDraw(PNGDRAW *pDraw)`
	`78`	`+int PNGDraw(PNGDRAW *pDraw)`
`79`	`79`	`{`
`80`	`80`	`if (bDisplay) {`
`81`	`81`	`if (pDraw->y == 0) {`
`@@ -84,6 +84,7 @@ void PNGDraw(PNGDRAW *pDraw)`
`84`	`84`	`png->getLineAsRGB565(pDraw, usPixels, PNG_RGB565_BIG_ENDIAN, 0xffffffff);`
`85`	`85`	`lcd.pushPixels(usPixels, pDraw->iWidth, DRAW_TO_LCD \| DRAW_WITH_DMA);`
`86`	`86`	`}`
	`87`	`+ return 1;`
`87`	`88`	`} /* PNGDraw() */`
`88`	`89`
`89`	`90`	`void setup() {`
Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,7 @@ typedef struct my_private_struct`
`30`	`30`	`int xoff, yoff; // corner offset`
`31`	`31`	`} PRIVATE;`
`32`	`32`
`33`		`-void PNGDraw(PNGDRAW *pDraw)`
	`33`	`+int PNGDraw(PNGDRAW *pDraw)`
`34`	`34`	`{`
`35`	`35`	`uint16_t usPixels[320];`
`36`	`36`	`uint8_t ucMask[40];`
`@@ -40,6 +40,7 @@ PRIVATE pPriv = (PRIVATE )pDraw->pUser;`
`40`	`40`	`if (png.getAlphaMask(pDraw, ucMask, 255)) { // if any pixels are opaque, draw them`
`41`	`41`	`spilcdWritePixelsMasked(&lcd, pPriv->xoff, pPriv->yoff + pDraw->y, (uint8_t *)usPixels, ucMask, pDraw->iWidth, DRAW_TO_LCD);`
`42`	`42`	`}`
	`43`	`+ return 1;`
`43`	`44`	`} /* PNGDraw() */`
`44`	`45`
`45`	`46`	`void setup() {`
Original file line number	Diff line number	Diff line change
`@@ -59,11 +59,12 @@ int32_t mySeek(PNGFILE *handle, int32_t position) {`
`59`	`59`	`}`
`60`	`60`
`61`	`61`	`// Function to draw pixels to the display`
`62`		`-void PNGDraw(PNGDRAW *pDraw) {`
	`62`	`+int PNGDraw(PNGDRAW *pDraw) {`
`63`	`63`	`uint16_t usPixels[320];`
`64`	`64`
`65`	`65`	`png.getLineAsRGB565(pDraw, usPixels, PNG_RGB565_LITTLE_ENDIAN, 0xffffffff);`
`66`	`66`	`tft.writeRect(0, pDraw->y + 24, pDraw->iWidth, 1, usPixels);`
	`67`	`+ return 1;`
`67`	`68`	`}`
`68`	`69`
`69`	`70`	`// Main loop, scan for all .PNG files on the card and display them`