### Example PNG_OPEN_CALLBACK Implementation

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/types.md

An example implementation of the PNG_OPEN_CALLBACK function. It opens a file using SD.open, retrieves its size, and returns a file handle.

```cpp
void * myOpen(const char *szFilename, int32_t *pFileSize) {
    File f = SD.open(szFilename);
    if (f) {
        *pFileSize = f.size();
        return (void *)&f;
    }
    return NULL;
}
```

--------------------------------

### Example Draw Callback Implementation

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/draw-callback-guide.md

An example of how to implement a draw callback function. It shows how to access the PNGDRAW structure and return a status code.

```c
int myDrawCallback(PNGDRAW *pDraw) {
    // Process pixel data in pDraw->pPixels
    // Access metadata via pDraw-> fields
    return 1; // Return 1 to continue, 0 to stop
}
```

--------------------------------

### Example Usage of PNGDISPLAY_CENTER

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-pngdisplay-class.md

Demonstrates how to use the PNGDISPLAY_CENTER constant to load a PNG image centered on the display.

```cpp
pngDisplay.loadPNG(&lcd, PNGDISPLAY_CENTER, PNGDISPLAY_CENTER, data, size);
```

--------------------------------

### Example PNG_READ_CALLBACK Implementation

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/types.md

An example implementation of the PNG_READ_CALLBACK function. This function reads data from a file handle and returns the number of bytes read.

```cpp
int32_t myRead(PNGFILE *pFile, uint8_t *pBuf, int32_t iLen) {
    File *f = (File *)pFile->fHandle;
    return f->read(pBuf, iLen);
}
```

--------------------------------

### Example PNG_DRAW_CALLBACK Implementation

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/types.md

An example implementation of the PNG_DRAW_CALLBACK function. It demonstrates how to process scanline data and includes logic to stop decoding after a certain line.

```cpp
int PNGDraw(PNGDRAW *pDraw) {
    if (pDraw->y > 100) return 0; // Stop after line 100
    // Process pDraw->pPixels
    return 1;
}
```

--------------------------------

### 2-Pixel Truecolor Line Example

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/draw-callback-guide.md

Demonstrates the byte storage for a 2-pixel truecolor line (red, blue) in R-G-B order.

```text
pPixels[0]:    0xFF (R of pixel 0)
pPixels[1]:    0x00 (G of pixel 0)
pPixels[2]:    0x00 (B of pixel 0)
pPixels[3]:    0x00 (R of pixel 1)
pPixels[4]:    0x00 (G of pixel 1)
pPixels[5]:    0xFF (B of pixel 1)
```

--------------------------------

### Example PNG_CLOSE_CALLBACK Implementation

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/types.md

An example implementation of the PNG_CLOSE_CALLBACK function. It casts the void pointer back to a file handle and closes the file.

```cpp
void myClose(void *pHandle) {
    File *f = (File *)pHandle;
    if (f) f->close();
}
```

--------------------------------

### 8-bpp Grayscale Pixel Data Example

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/draw-callback-guide.md

Shows the byte values for an 8-bpp grayscale line with 3 gray levels.

```text
Gray levels:   [0, 128, 255]
pPixels[0]:    0x00
pPixels[1]:    0x80
pPixels[2]:    0xFF
```

--------------------------------

### 1-bpp Grayscale Pixel Data Example

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/draw-callback-guide.md

Illustrates the byte value for a 1-bpp grayscale line with 3 pixels (black, white, black). MSB is the first pixel.

```text
Pixels:        [black, white, black, -, -, -, -, -]
Byte value:    0b10100000 = 0xA0
pPixels[0]:    0xA0
```

--------------------------------

### 1-Pixel Grayscale with Alpha Line Example

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/draw-callback-guide.md

Shows the byte storage for a 1-pixel grayscale with alpha line, where the first byte is gray level and the second is alpha.

```text
pPixels[0]:    0x80 (Gray level)
pPixels[1]:    0xC8 (Alpha, 200)
```

--------------------------------

### 1-Pixel Truecolor with Alpha Line Example

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/draw-callback-guide.md

Illustrates the byte storage for a 1-pixel truecolor with alpha line (red, alpha=200) in R-G-B-A order.

```text
pPixels[0]:    0xFF (Red)
pPixels[1]:    0x00 (Green)
pPixels[2]:    0x00 (Blue)
pPixels[3]:    0xC8 (Alpha, 200)
```

--------------------------------

### Load PNG from SD Card

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/quick-start.md

This example shows how to load and decode a PNG image from an SD card. It includes custom file I/O callbacks required by the PNGdec library. Ensure the SD card is initialized and the image file exists on the card.

```cpp
#include <SD.h>
#include <PNGdec.h>

PNG png;

int PNGDraw(PNGDRAW *pDraw) {
    // Process line
    return 1;
}

// File I/O callbacks
void * pngOpen(const char *filename, int32_t *size) {
    static File f;
    f = SD.open(filename);
    *size = f.size();
    return (void *)&f;
}

void pngClose(void *handle) {
    File *f = (File *)handle;
    if (f) f->close();
}

int32_t pngRead(PNGFILE *handle, uint8_t *buffer, int32_t length) {
    File *f = (File *)handle->fHandle;
    return f->read(buffer, length);
}

int32_t pngSeek(PNGFILE *handle, int32_t position) {
    File *f = (File *)handle->fHandle;
    return f->seek(position);
}

void setup() {
    Serial.begin(115200);
    SD.begin(10); // CS pin 10
}

void loop() {
    int rc = png.open("image.png", pngOpen, pngClose, pngRead, pngSeek, PNGDraw);
    if (rc == PNG_SUCCESS) {
        rc = png.decode(NULL, 0);
        png.close();
    }
    delay(5000);
}
```

--------------------------------

### PNGDRAW Callback Example

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/types.md

An example of a draw callback function that receives a PNGDRAW structure. It logs information about the decoded line and returns a status to continue decoding.

```cpp
int PNGDraw(PNGDRAW *pDraw) {
    printf("Line %d: %d pixels, type=%d, bpp=%d\n",
           pDraw->y, pDraw->iWidth, pDraw->iPixelType, pDraw->iBpp);
    // Process pDraw->pPixels
    return 1; // Continue decoding
}
```

--------------------------------

### Convert PNG to RGB565 and Display on LCD

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/quick-start.md

This example shows how to convert a decoded PNG image line by line into RGB565 format and then display it on an SPI LCD. It requires the `bb_spi_lcd.h` library and assumes `pngData` contains the PNG bytes.

```cpp
#include <PNGdec.h>
#include <bb_spi_lcd.h>

BB_SPI_LCD lcd;
PNG png;

int PNGDraw(PNGDRAW *pDraw) {
    uint16_t usPixels[320];
    
    // Convert line to RGB565
    png.getLineAsRGB565(pDraw, usPixels, PNG_RGB565_LITTLE_ENDIAN, 0xFFFFFF);
    
    // Display on LCD
    lcd.pushPixels(usPixels, pDraw->iWidth);
    
    return 1;
}

void setup() {
    lcd.init(/* ... */);
}

void loop() {
    // Assuming pngData contains PNG bytes
    png.openRAM((uint8_t *)pngData, sizeof(pngData), PNGDraw);
    png.decode(NULL, PNG_FAST_PALETTE);
}
```

--------------------------------

### Complete C Program for PNG Decoding

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-c-interface.md

This example demonstrates how to open a PNG from a memory buffer, decode it, and handle potential errors using the C API. It requires the PNGdec.h header and defines a callback function PNGDraw for image data processing.

```c
#define __LINUX__
#include "PNGdec.h"

int PNGDraw(PNGDRAW *pDraw) {
    printf("Line %d: %d pixels\n", pDraw->y, pDraw->iWidth);
    return 1; // Continue
}

int main() {
    PNGIMAGE png;
    memset(&png, 0, sizeof(PNGIMAGE));
    
    // Open from memory buffer
    uint8_t pngData[] = { /* PNG file bytes */ };
    int rc = PNG_openRAM(&png, pngData, sizeof(pngData), PNGDraw);
    
    if (rc == PNG_SUCCESS) {
        printf("Image: %d x %d, %d bpp\n", 
               PNG_getWidth(&png),
               PNG_getHeight(&png),
               PNG_getBpp(&png));
        
        rc = PNG_decode(&png, NULL, PNG_FAST_PALETTE);
        if (rc != PNG_SUCCESS) {
            printf("Decode error: %d\n", PNG_getLastError(&png));
        }
    } else {
        printf("Open error: %d\n", PNG_getLastError(&png));
    }
    
    PNG_close(&png);
    return rc;
}
```

--------------------------------

### PNGdec Library Project Structure

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/README.md

Overview of the file and directory structure for the PNGdec library, including source files, examples, and documentation.

```text
pngdec/
├── src/
│   ├── PNGdec.h           — Main C++ class header
│   ├── PNGdec.cpp         — C++ class implementation
│   ├── PNGDisplay.h       — LCD helper class header
│   ├── PNGDisplay.inl     — LCD helper class implementation
│   ├── png.inl            — Core PNG decoder (C implementation)
│   ├── inflate.c/h        — zlib decompressor
│   ├── adler32.c          — Adler-32 checksum
│   └── crc32.c/h          — CRC-32 checksum
├── examples/              — Arduino sketch examples
├── library.properties     — Arduino library metadata
└── README.md              — Project README

This documentation:
├── api-reference-png-class.md        — PNG class methods
├── api-reference-pngdisplay-class.md — PNGDisplay class methods
├── api-reference-c-interface.md      — C language API
├── types.md                          — Type definitions
├── errors.md                         — Error codes
├── configuration.md                  — Compile-time settings
├── draw-callback-guide.md            — Pixel data & callbacks
├── quick-start.md                    — Getting started
└── README.md                         — This file
```

--------------------------------

### PNGDisplay Class API Reference

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/DELIVERABLES.txt

Documentation for the C++ PNGDisplay helper class, outlining its 7 public methods. This includes information on method signatures, parameters, return types, and examples.

```APIDOC
## PNGDisplay Class Public Methods

### Description
This section details the public methods of the C++ PNGDisplay helper class, designed to assist with displaying PNG images.

### Methods
- (7 methods documented)

### Parameters
(Details for each method's parameters are provided in the full documentation.)

### Return Types
(Details for each method's return type are provided in the full documentation.)

### Request Example
```cpp
// Example usage of PNGDisplay class methods
PNGDisplay display;
// ... use display methods ...
```

### Response
(Details on success and error responses for each method are provided in the full documentation.)
```

--------------------------------

### Install PNGdec via PlatformIO

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/quick-start.md

Add the PNGdec library to your PlatformIO project by including it in the library dependencies. This is a common method for managing project libraries in embedded systems.

```ini
[env:myboard]
lib_deps = bitbank2/PNGdec
```

--------------------------------

### Arduino SD Library File Close Callback Implementation

Source: https://github.com/bitbank2/pngdec/wiki/Home

Example implementation of the PNG_CLOSE_CALLBACK for the Arduino SD library, demonstrating how to cast a void pointer back to a File object and close it.

```c++
void PNGCloseFile(void *pHandle)
{
  File *f = static_cast<File *>(pHandle);
  if (f != NULL)
    f->close();
}
```

--------------------------------

### First PNG Decode Example (C++)

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/00_START_HERE.txt

This snippet demonstrates how to decode a PNG image from RAM using the PNGdec C++ library. It includes setting up the PNG object, defining a draw callback function for scanlines, and initiating the decode process. Ensure the PNGDraw function is implemented to handle decoded pixels.

```cpp
#include <PNGdec.h>

PNG png;

int PNGDraw(PNGDRAW *pDraw) {
    // Called once per scanline
    // pDraw->pPixels = decoded pixels
    // pDraw->y = scanline number
    return 1; // Continue
}

void setup() {
    Serial.begin(115200);
}

void loop() {
    uint8_t pngData[] = { /* PNG bytes */ };
    
    int rc = png.openRAM(pngData, sizeof(pngData), PNGDraw);
    if (rc == PNG_SUCCESS) {
        rc = png.decode(NULL, PNG_FAST_PALETTE);
    }
}
```

--------------------------------

### Minimal PNG Decode from Memory

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/quick-start.md

This example demonstrates how to decode a PNG image embedded as a C array in memory. It includes the necessary headers, sets up a callback function for scanline drawing, and initializes the serial communication.

```cpp
#include <PNGdec.h>

// Include a PNG image as a C array
#include "my_image.h"  // uint8_t myImage[] = { ... }

PNG png;

int PNGDraw(PNGDRAW *pDraw) {
    // Called once per scanline
    // pDraw->pPixels contains decoded pixels for this line
    // pDraw->y is the scanline number (0 to height-1)
    Serial.print("Line: "); Serial.println(pDraw->y);
    return 1; // Return 1 to continue, 0 to stop
}

void setup() {
    Serial.begin(115200);
}

void loop() {
    int rc = png.openRAM((uint8_t *)myImage, sizeof(myImage), PNGDraw);
    if (rc == PNG_SUCCESS) {
        Serial.print("Image: ");
        Serial.print(png.getWidth());
        Serial.print("x");
        Serial.println(png.getHeight());
        
        rc = png.decode(NULL, PNG_FAST_PALETTE);
        if (rc == PNG_SUCCESS) {
            Serial.println("Decode complete!");
        } else {
            Serial.print("Decode error: ");
            Serial.println(rc);
        }
    }
    delay(5000);
}
```

--------------------------------

### Handling Invalid File Errors

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/errors.md

Provides an example of detecting and handling `PNG_INVALID_FILE` errors during PNG initialization. This error indicates that the file header does not match the PNG signature or critical chunks are missing.

```cpp
int rc = png.openRAM(pData, size, callback);
if (rc == PNG_INVALID_FILE) {
    printf("Not a valid PNG file\n");
    // Verify file path or data source
}
```

--------------------------------

### PNG Class API Reference

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/DELIVERABLES.txt

Documentation for the C++ PNG class, detailing its public methods such as openRAM, decode, and others. It covers method signatures, parameters, return types, and usage examples.

```APIDOC
## PNG Class Public Methods

### Description
This section details the public methods available for the C++ PNG class, which is used for interacting with PNG image data.

### Methods
- `openRAM(const char* filename)`
- `decode()`
- ... (16 additional methods)

### Parameters
(Details for each method's parameters, including type, name, and description, are provided in the full documentation.)

### Return Types
(Details for each method's return type are provided in the full documentation.)

### Request Example
```cpp
// Example usage of PNG class methods
PNG png;
if (png.openRAM("image.png")) {
    // Image opened successfully
    if (png.decode()) {
        // Image decoded successfully
    }
}
```

### Response
(Details on success and error responses for each method are provided in the full documentation.)
```

--------------------------------

### C Interface API Reference

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/DELIVERABLES.txt

Documentation for the C language API provided by PNGdec, comprising 15 functions. This covers function signatures, parameters, return types, and usage examples, mirroring C++ functionality.

```APIDOC
## C Language API Functions

### Description
This section details the functions available in the pure C API for the PNGdec library, which provides access to core PNG decoding functionalities.

### Functions
- (15 functions documented)

### Parameters
(Details for each function's parameters are provided in the full documentation.)

### Return Types
(Details for each function's return type are provided in the full documentation.)

### Request Example
```c
// Example usage of C API functions
// ... call C API functions ...
```

### Response
(Details on success and error responses for each function are provided in the full documentation.)
```

--------------------------------

### Handle PNG_QUIT_EARLY Error

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/errors.md

This example shows how to handle the PNG_QUIT_EARLY error during PNG decoding. It includes a sample draw callback that stops decoding after 100 scanlines and checks the return code of the decode function.

```cpp
int PNGDraw(PNGDRAW *pDraw) {
    if (pDraw->y >= 100) return 0; // Stop after 100 scanlines
    // Process pixel data
    return 1; // Continue
}

int rc = png.decode(NULL, 0);
if (rc == PNG_QUIT_EARLY) {
    printf("Decode stopped by callback\n");
}
```

--------------------------------

### Get PNG Info from SD Card File

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-pngdisplay-class.md

Queries PNG metadata (width, height, bits per pixel) from a PNG file located on an SD card. Returns success or failure status.

```cpp
int w, h, bpp;
if (pngDisplay.getPNGInfo(&w, &h, &bpp, "test.png") == 1) {
    printf("Image dimensions: %d x %d\n", w, h);
}
```

--------------------------------

### PNG Class Methods

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/REFERENCE_INDEX.md

The PNG class provides methods for opening PNG files from different memory locations, decoding image data, and retrieving image properties. It supports opening from RAM, program memory, and files with custom I/O callbacks. Methods are available to get dimensions, bits per pixel, color type, alpha channel information, and error codes.

```APIDOC
## PNG Class Methods

### Description
Provides methods for opening PNG files from various memory locations (RAM, program memory, file with custom I/O), decoding image data line by line, and retrieving image properties such as dimensions, color depth, and error status.

### Methods

- **`openRAM(data, size)`**: Opens a PNG from a memory buffer.
- **`openFLASH(flash_ptr, size)`**: Opens a PNG from program memory (Harvard architecture).
- **`open(reader, size)`**: Opens a PNG from a file using custom I/O callbacks.
- **`decode(callback)`**: Decodes the image and invokes a callback function for each decoded line.
- **`close()`**: Closes the opened PNG file handle.
- **`getWidth()`**: Returns the width of the PNG image in pixels.
- **`getHeight()`**: Returns the height of the PNG image in pixels.
- **`getBpp()`**: Returns the bits per color stimulus (1, 2, 4, 8).
- **`getPixelType()`**: Returns the color model of the image.
- **`hasAlpha()`**: Returns true if the PNG has an alpha channel.
- **`getTransparentColor()`**: Returns the transparent color value.
- **`isInterlaced()`**: Returns true if the PNG is interlaced (unsupported).
- **`getPalette()`**: Returns the color palette for indexed images.
- **`getLastError()`**: Returns the last error code encountered.
- **`setBuffer(buffer)`**: Sets a buffer for full-image output.
- **`getBuffer()`**: Returns the previously set output buffer.
- **`getBufferSize()`**: Returns the required buffer size for the entire image.
- **`getLineAsRGB565()`**: Converts a scanline to RGB565 format.
- **`getAlphaMask()`**: Creates a binary mask from the alpha channel.
```

--------------------------------

### Get PNG Image Width

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Retrieves the width of the PNG image in pixels. This can be called after any `open*` method without starting the decoding process.

```cpp
PNG png;
png.openRAM(pngData, sizeof(pngData), NULL);
int width = png.getWidth(); // e.g., 240
```

--------------------------------

### Use PNGDisplay Helper (Simplest)

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/quick-start.md

This snippet demonstrates the simplest way to display a PNG image loaded from memory using the PNGDisplay helper class. Ensure your compatible display (bb_spi_lcd, bb_epaper, or FastEPD) is initialized before calling this function.

```cpp
#include <PNGDisplay.h>

PNGDisplay pngDisplay;

void setup() {
    // Initialize your display first
    lcd.init(/* ... */);
}

void loop() {
    // Load PNG from memory
    uint8_t pngData[] = { /* PNG bytes */ };
    
    int rc = pngDisplay.loadPNG(&lcd, 0, 0, pngData, sizeof(pngData));
    if (rc == 1) {
        Serial.println("Image displayed!");
    } else {
        Serial.print("Load error: ");
        Serial.println(pngDisplay.getLastError());
    }
}
```

--------------------------------

### Initialize PNGDisplay Object

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-pngdisplay-class.md

Initializes an empty PNGDisplay object. No state is allocated; methods are stateless wrappers.

```cpp
PNGDisplay();
```

--------------------------------

### Get PNG Image Height

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-c-interface.md

Retrieves the height of the PNG image in pixels.

```c
int PNG_getHeight(PNGIMAGE *pPNG);
```

```c
int h = PNG_getHeight(&png); // e.g., 200
```

--------------------------------

### Get PNG Image Width

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-c-interface.md

Retrieves the width of the PNG image in pixels.

```c
int PNG_getWidth(PNGIMAGE *pPNG);
```

```c
int w = PNG_getWidth(&png); // e.g., 240
```

--------------------------------

### Get Last PNG Error

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-c-interface.md

Retrieves the error code from the last operation performed on the PNGIMAGE structure.

```c
int PNG_getLastError(PNGIMAGE *pPNG);
```

```c
if (PNG_decode(&png, NULL, 0) != PNG_SUCCESS) {
    printf("Error: %d\n", PNG_getLastError(&png));
}
```

--------------------------------

### getWidth

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Returns the width of the image in pixels. Valid after calling any `open*` method. Does not require decoding to have started.

```APIDOC
## getWidth

### Description
Returns the width of the image in pixels. Valid after calling any `open*` method. Does not require decoding to have started.

### Method
```cpp
int getWidth()
```

### Parameters
None

### Return
Image width in pixels

### Example
```cpp
PNG png;
png.openRAM(pngData, sizeof(pngData), NULL);
int width = png.getWidth(); // e.g., 240
```
```

--------------------------------

### loadPNG (from file)

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-pngdisplay-class.md

Loads a PNG image from an SD card file and displays it. The file is automatically opened, decoded, and closed. Returns 1 on success, 0 on failure.

```APIDOC
## loadPNG (from file)

### Description
Loads a PNG image from an SD card file and displays it.

### Method
`int loadPNG(BB_SPI_LCD *pDisplay, int x, int y, const char *fname, uint32_t bgColor = 0xffffffff);`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `pDisplay` | `BB_SPI_LCD*` | Yes | — | Pointer to initialized display object |
| `x` | `int` | Yes | — | X coordinate; use `PNGDISPLAY_CENTER` (-2) to center |
| `y` | `int` | Yes | — | Y coordinate; use `PNGDISPLAY_CENTER` (-2) to center |
| `fname` | `const char*` | Yes | — | Path to PNG file on SD card |
| `bgColor` | `uint32_t` | No | `0xffffffff` | Background color for alpha blending (0x00BBGGRR) |

### Request Example
```cpp
#include <SD.h>
#include <bb_spi_lcd.h>
#include <PNGDisplay.h>

PNGDisplay pngDisplay;

if (SD.begin(10)) { // Chip select on pin 10
    int rc = pngDisplay.loadPNG(&lcd, 10, 20, "image.png", 0x000000); // Black background
}
```

### Response
#### Success Response (1)
Returns 1 on success.

#### Error Response (0)
Returns 0 on failure.

#### Response Example
`1` (on success)
```

--------------------------------

### Get PNG Image Height

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Retrieves the height of the PNG image in pixels. This information is available after opening the image.

```cpp
int height = png.getHeight(); // e.g., 200
```

--------------------------------

### open

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Opens a PNG image from a file using custom callback functions for file I/O. Supports decoding from any storage medium.

```APIDOC
## open

### Description
Enables decoding PNG files from any storage medium (SD card, flash filesystem, etc.) by providing custom I/O callbacks. The `pfnOpen` callback is invoked immediately; if it returns NULL, `open()` returns 0 and sets no error code (check file handle separately).

### Method
`int open(const char *szFilename, PNG_OPEN_CALLBACK *pfnOpen, PNG_CLOSE_CALLBACK *pfnClose, PNG_READ_CALLBACK *pfnRead, PNG_SEEK_CALLBACK *pfnSeek, PNG_DRAW_CALLBACK *pfnDraw)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **szFilename** (`const char*`) - Yes - Path to PNG file
- **pfnOpen** (`PNG_OPEN_CALLBACK*`) - Yes - Callback to open file; returns void pointer to file handle, sets file size
- **pfnClose** (`PNG_CLOSE_CALLBACK*`) - Yes - Callback to close file handle
- **pfnRead** (`PNG_READ_CALLBACK*`) - Yes - Callback to read bytes from file
- **pfnSeek** (`PNG_SEEK_CALLBACK*`) - Yes - Callback to seek to file position
- **pfnDraw** (`PNG_DRAW_CALLBACK*`) - Yes - Callback invoked per decoded line; NULL disables callback

### Request Example
```cpp
void * myOpen(const char *szFilename, int32_t *pFileSize) {
    File f = SD.open(szFilename);
    *pFileSize = f.size();
    return (void *)&f;
}
int32_t myRead(PNGFILE *pFile, uint8_t *pBuf, int32_t iLen) {
    File *f = (File *)pFile->fHandle;
    return f->read(pBuf, iLen);
}
// ... similar for mySeek and myClose

PNG png;
int rc = png.open("image.png", myOpen, myClose, myRead, mySeek, PNGDraw);
```

### Response
#### Success Response (0)
`PNG_SUCCESS` (0) on success if file opens

#### Response Example
`0`
```

--------------------------------

### Support Larger Images in Arduino IDE

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/configuration.md

Configure the Arduino IDE's build process by adding a preprocessor flag to platform.local.txt to support decoding larger image widths.

```properties
compiler.cpp.extra_flags=-DPNG_MAX_BUFFERED_PIXELS=6400
```

--------------------------------

### Open PNG from File (Linux)

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-c-interface.md

Linux-only variant for opening a PNG image from a file. Uses standard file I/O functions. Requires a PNGIMAGE structure, the file path, and an optional draw callback.

```c
int PNG_openFile(PNGIMAGE *pPNG, const char *szFilename, PNG_DRAW_CALLBACK *pfnDraw);
```

```c
PNGIMAGE png;
memset(&png, 0, sizeof(PNGIMAGE));
int rc = PNG_openFile(&png, "/path/to/image.png", PNGDraw);
if (rc == PNG_SUCCESS) {
    PNG_decode(&png, NULL, 0);
    PNG_close(&png);
}
```

--------------------------------

### getLastError

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Gets the last error code encountered during the PNG decoding process. This is useful for diagnosing issues after a decode operation fails.

```APIDOC
## getLastError

### Description
Returns the last error code encountered during decoding.

### Method
```cpp
int getLastError();
```

### Return
Error code (see errors.md).
```

--------------------------------

### loadPNG (from memory)

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-pngdisplay-class.md

Loads a PNG image from a memory buffer and displays it on the specified display. Supports alpha blending with a background color. Returns 1 on success, 0 on failure.

```APIDOC
## loadPNG (from memory)

### Description
Loads a PNG image from a memory buffer and displays it.

### Method
`int loadPNG(BB_SPI_LCD *pDisplay, int x, int y, const void *pData, int iDataSize, uint32_t bgColor = 0xffffffff);`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `pDisplay` | `BB_SPI_LCD*` | Yes | — | Pointer to initialized display object |
| `x` | `int` | Yes | — | X coordinate to draw at; use `PNGDISPLAY_CENTER` (-2) to center horizontally |
| `y` | `int` | Yes | — | Y coordinate to draw at; use `PNGDISPLAY_CENTER` (-2) to center vertically |
| `pData` | `const void*` | Yes | — | Pointer to PNG image data in memory |
| `iDataSize` | `int` | Yes | — | Size of PNG data in bytes |
| `bgColor` | `uint32_t` | No | `0xffffffff` (white) | Background color for alpha blending; format 0x00BBGGRR |

### Request Example
```cpp
#include <bb_spi_lcd.h> 
#include <PNGDisplay.h> 
#include "my_image.h" // Contains uint8_t pngData[] 

BB_SPI_LCD lcd;
PNGDisplay pngDisplay;

lcd.init(/* ... */);

int rc = pngDisplay.loadPNG(&lcd, PNGDISPLAY_CENTER, PNGDISPLAY_CENTER, pngData, sizeof(pngData));
if (rc != 1) {
    printf("Load failed: %d\n", pngDisplay.getLastError());
}
```

### Response
#### Success Response (1)
Returns 1 on success.

#### Error Response (0)
Returns 0 on failure. Check `getLastError()` for details.

#### Response Example
`1` (on success)
```

--------------------------------

### Load PNG from File

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-pngdisplay-class.md

Loads and displays a PNG image from an SD card file. Requires the SD library to be initialized. The file is automatically opened, decoded, and closed.

```cpp
#include <SD.h>
#include <bb_spi_lcd.h>
#include <PNGDisplay.h>

PNGDisplay pngDisplay;

if (SD.begin(10)) { // Chip select on pin 10
    int rc = pngDisplay.loadPNG(&lcd, 10, 20, "image.png", 0x000000); // Black background
}
```

--------------------------------

### Get PNG Pixel Type

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Retrieves the pixel type of the PNG image, such as grayscale, truecolor, or indexed. This helps in understanding how pixel data is represented.

```cpp
int type = png.getPixelType();
if (type == PNG_PIXEL_INDEXED) {
    // Palette-based image
}
```

--------------------------------

### Get Last PNG Error

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-pngdisplay-class.md

Retrieves the error code from the most recent PNG operation (loadPNG or getPNGInfo). Use after a failed call to diagnose the issue.

```cpp
int rc = pngDisplay.loadPNG(&lcd, 0, 0, data, size);
if (rc != 1) {
    int err = pngDisplay.getLastError();
    printf("PNG error: %d\n", err);
}
```

--------------------------------

### Override PNG_MAX_BUFFERED_PIXELS in Platform.local.txt

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/configuration.md

Configure PNG_MAX_BUFFERED_PIXELS by adding this line to your Arduino Platform.local.txt file. This sets a project-wide default for the maximum buffered pixels.

```text
compiler.cpp.extra_flags=-DPNG_MAX_BUFFERED_PIXELS=4096
```

--------------------------------

### Get Previously Set Image Buffer

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Retrieve the pointer to the user-allocated buffer set via `setBuffer()` using `getBuffer()`. Returns NULL if no buffer was set.

```cpp
uint8_t * getBuffer();
```

```cpp
uint8_t *buf = png.getBuffer();
if (buf) {
    // User buffer is in use
}
```

--------------------------------

### Open PNG with Custom File I/O

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Opens a PNG image from a file using custom callback functions for opening, closing, reading, and seeking. This allows decoding from any storage medium.

```cpp
int open(const char *szFilename, 
         PNG_OPEN_CALLBACK *pfnOpen, 
         PNG_CLOSE_CALLBACK *pfnClose, 
         PNG_READ_CALLBACK *pfnRead, 
         PNG_SEEK_CALLBACK *pfnSeek, 
         PNG_DRAW_CALLBACK *pfnDraw);
```

```cpp
void * myOpen(const char *szFilename, int32_t *pFileSize) {
    File f = SD.open(szFilename);
    *pFileSize = f.size();
    return (void *)&f;
}
int32_t myRead(PNGFILE *pFile, uint8_t *pBuf, int32_t iLen) {
    File *f = (File *)pFile->fHandle;
    return f->read(pBuf, iLen);
}
// ... similar for mySeek and myClose

PNG png;
int rc = png.open("image.png", myOpen, myClose, myRead, mySeek, PNGDraw);
```

--------------------------------

### Get Output Buffer Pointer

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-c-interface.md

Retrieves the pointer to the user-allocated buffer previously set using `PNG_setBuffer`. This buffer is used for storing the decoded image data.

```c
uint8_t *PNG_getBuffer(PNGIMAGE *pPNG);
```

```c
uint8_t *buf = PNG_getBuffer(&png);
if (buf) {
    // Buffer is in use
}
```

--------------------------------

### Get Last Error Code

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Use `getLastError()` to retrieve the error code from the last decoding operation. This is useful for diagnosing issues when `decode()` returns a non-success status.

```cpp
int getLastError();
```

```cpp
int rc = png.decode(NULL, 0);
if (rc != PNG_SUCCESS) {
    printf("Error: %d\n", png.getLastError());
}
```

--------------------------------

### Open PNG from RAM

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-c-interface.md

Initializes a PNGIMAGE structure for decoding from RAM or FLASH memory. After calling, image metadata is available via PNG_getWidth(), PNG_getHeight(), etc. Requires a PNGIMAGE structure, PNG data, its size, and an optional draw callback.

```c
int PNG_openRAM(PNGIMAGE *pPNG, uint8_t *pData, int iDataSize, PNG_DRAW_CALLBACK *pfnDraw);
```

```c
PNGIMAGE png;
uint8_t pngData[] = { /* PNG bytes */ };

memset(&png, 0, sizeof(PNGIMAGE)); // Clear structure
int rc = PNG_openRAM(&png, pngData, sizeof(pngData), PNGDraw);
if (rc == PNG_SUCCESS) {
    int width = PNG_getWidth(&png);
    int height = PNG_getHeight(&png);
}
```

--------------------------------

### Get PNG Pixel Type

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-c-interface.md

Returns an integer constant representing the pixel format of the PNG image. Use this to determine if the image is indexed, RGB, RGBA, etc.

```c
int PNG_getPixelType(PNGIMAGE *pPNG);
```

```c
int type = PNG_getPixelType(&png);
if (type == PNG_PIXEL_INDEXED) {
    // Palette-based image
}
```

--------------------------------

### Get Bits Per Pixel (Bpp)

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-c-interface.md

Retrieves the number of bits used per color stimulus for the PNG image. This value indicates the color depth of the image.

```c
int PNG_getBpp(PNGIMAGE *pPNG);
```

```c
int bpp = PNG_getBpp(&png);
```

--------------------------------

### Load PNG from LittleFS

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-pngdisplay-class.md

Loads a PNG image from the LittleFS filesystem and displays it on the screen. Requires LittleFS to be initialized. Not available on nRF52 architecture.

```cpp
#include <LittleFS.h>
#include <bb_spi_lcd.h>
#include <PNGDisplay.h>

PNGDisplay pngDisplay;

if (LittleFS.begin()) {
    int rc = pngDisplay.loadPNG_LFS(&lcd, 0, 0, "/images/icon.png");
}
```

--------------------------------

### Get RGB from 8-bpp Indexed Palette

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/draw-callback-guide.md

C code snippet to retrieve the actual RGB color of a pixel from an 8-bpp indexed PNG image using its palette.

```c
int PNGDraw(PNGDRAW *pDraw) {
    if (pDraw->iPixelType == PNG_PIXEL_INDEXED && pDraw->iBpp == 8) {
        uint8_t paletteIndex = pDraw->pPixels[0]; // First pixel
        uint8_t r = pDraw->pPalette[paletteIndex * 3];
        uint8_t g = pDraw->pPalette[paletteIndex * 3 + 1];
        uint8_t b = pDraw->pPalette[paletteIndex * 3 + 2];
        // Now have actual RGB for this pixel
    }
    return 1;
}
```

--------------------------------

### Get PNG Palette

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Retrieve the image palette using `getPalette()` for indexed PNGs. The palette is a 1024-byte buffer containing RGB triplets and optional per-color alpha values.

```cpp
uint8_t * getPalette();
```

```cpp
uint8_t *palette = png.getPalette();
uint8_t r = palette[0];     // Red of color 0
uint8_t g = palette[1];     // Green of color 0
uint8_t b = palette[2];     // Blue of color 0
uint8_t *alphas = &palette[768]; // Palette alpha values (if present)
```

--------------------------------

### PNG Class Constructor

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Initializes an empty PNG object. The internal PNGIMAGE structure is zeroed upon calling any `open*` method.

```APIDOC
## PNG()

### Description
Initializes an empty PNG object. The internal PNGIMAGE structure is zeroed upon calling any `open*` method.

### Method
Constructor

### Parameters
None
```

--------------------------------

### Get PNG Bits Per Pixel (Color Depth)

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Returns the color depth of the image, indicating the number of bits used for each color component. This is independent of the pixel type.

```cpp
int bpp = png.getBpp(); // e.g., 8
```

--------------------------------

### Support Larger Images with Direct Compilation

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/configuration.md

Compile source files directly using gcc and specify the PNG_MAX_BUFFERED_PIXELS preprocessor macro to support larger image widths.

```bash
gcc -DPNG_MAX_BUFFERED_PIXELS=6400 mysketch.cpp
```

--------------------------------

### Get Required Image Buffer Size

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Determine the necessary buffer size in bytes for the complete decoded image using `getBufferSize()`. This is calculated as `height * pitch` and is valid after opening an image.

```cpp
int getBufferSize();
```

```cpp
PNG png;
png.openRAM(pngData, sizeof(pngData), NULL);
int bufSize = png.getBufferSize(); // e.g., 320 * 240 * 4 = 307,200 bytes
uint8_t *buf = new uint8_t[bufSize];
png.setBuffer(buf);
png.decode(NULL, 0);
```

--------------------------------

### Support Larger Images in PlatformIO

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/configuration.md

Configure PlatformIO's build flags in platformio.ini to enable support for decoding larger image widths.

```ini
[env:myboard]
build_flags = -DPNG_MAX_BUFFERED_PIXELS=6400
```

--------------------------------

### Grayscale 4-bpp Pixel Packing

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/draw-callback-guide.md

Demonstrates packing two 4-bpp grayscale pixels into a byte and extracting them. The upper nibble holds the first pixel, and the lower nibble holds the second.

```c
Image pixels:  [5, 10]
Byte:          0x5A  (5 in upper nibble, 10 in lower)
pPixels[0]:    0x5A

To extract:
  int pixel0 = (pPixels[0] >> 4) & 0xF;  // = 5
  int pixel1 = pPixels[0] & 0xF;         // = 10
```

--------------------------------

### Get Decoded Image Buffer Size

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-c-interface.md

Calculates and returns the total size in bytes required to hold the fully decoded PNG image. This is essential for allocating memory for the output buffer.

```c
int PNG_getBufferSize(PNGIMAGE *pPNG);
```

```c
int bufSize = PNG_getBufferSize(&png);
uint8_t *buf = malloc(bufSize);
PNG_setBuffer(&png, buf);
PNG_decode(&png, NULL, 0);
```

--------------------------------

### getPNGInfo (from file)

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-pngdisplay-class.md

Queries PNG metadata (width, height, bits per pixel) directly from a PNG file located on an SD card. This allows checking image properties before loading.

```APIDOC
## getPNGInfo (from file)

Queries PNG metadata from an SD card file.

### Function Signature
```cpp
int getPNGInfo(int *width, int *height, int *bpp, const char *fname);
```

### Parameters
#### Path Parameters
- `width` (int*) - Yes - Output: image width in pixels
- `height` (int*) - Yes - Output: image height in pixels
- `bpp` (int*) - Yes - Output: bits per color stimulus
- `fname` (const char*) - Yes - Path to PNG file on SD card

### Return Value
- `1` on success
- `0` on failure

### Example
```cpp
int w, h, bpp;
if (pngDisplay.getPNGInfo(&w, &h, &bpp, "test.png") == 1) {
    printf("Image dimensions: %d x %d\n", w, h);
}
```
```

--------------------------------

### Get Actual RGB from Indexed Image

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/quick-start.md

Extract RGB color values from an indexed PNG image. This involves iterating through pixels and using the palette to determine the actual color for each index.

```cpp
int PNGDraw(PNGDRAW *pDraw) {
    if (pDraw->iPixelType == PNG_PIXEL_INDEXED) {
        uint8_t *pal = pDraw->pPalette;
        
        for (int i = 0; i < pDraw->iWidth; i++) {
            uint8_t index = pDraw->pPixels[i];
            uint8_t r = pal[index * 3 + 0];
            uint8_t g = pal[index * 3 + 1];
            uint8_t b = pal[index * 3 + 2];
            // Use RGB values
        }
    }
    return 1;
}
```

--------------------------------

### openFLASH

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Opens a PNG image stored in program memory (FLASH/ROM) on Harvard architecture MCUs. Uses the `readFLASH` callback to read from program memory.

```APIDOC
## openFLASH

### Description
Opens a PNG image stored in program memory (FLASH/ROM) on Harvard architecture MCUs (e.g., Arduino AVR). Uses the `readFLASH` callback to read from program memory. Required for Harvard architecture systems where data and program memory are separate address spaces. On non-Harvard systems, this behaves identically to `openRAM`.

### Method
`int openFLASH(uint8_t *pData, int iDataSize, PNG_DRAW_CALLBACK *pfnDraw)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **pData** (`uint8_t*`) - Yes - Pointer to PNG image data in FLASH memory
- **iDataSize** (`int`) - Yes - Size of the PNG data in bytes
- **pfnDraw** (`PNG_DRAW_CALLBACK*`) - Yes - Pointer to callback function; NULL disables callback

### Request Example
```cpp
#include "my_png_image.h" // Contains uint8_t octocat_png[] PROGMEM

PNG png;
int rc = png.openFLASH(octocat_png, sizeof(octocat_png), PNGDraw);
if (rc == PNG_SUCCESS) {
    // Image opened successfully
}
```

### Response
#### Success Response (0)
`PNG_SUCCESS` (0) on success

#### Response Example
`0`
```

--------------------------------

### Compile PNGdec for Linux/macOS Testing

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/configuration.md

Compile the PNGdec library for Linux or macOS by defining __LINUX__ and specifying include paths, enabling the use of standard C file I/O.

```bash
gcc -D__LINUX__ -I/path/to/pngdec/src pngdec_test.c -o pngdec_test
```

--------------------------------

### Get Transparent Color Value

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-png-class.md

Retrieves the transparent color value, which is either a palette index for indexed images or an RGB value for truecolor images. Returns 0 if no transparent color is defined.

```cpp
uint32_t transparentColor = png.getTransparentColor();
printf("Transparent color: 0x%06x\n", transparentColor);
```

--------------------------------

### Get PNG Info from LittleFS File

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/api-reference-pngdisplay-class.md

Queries PNG metadata (width, height, bits per pixel) from a PNG file stored in the LittleFS filesystem. Returns success or failure status.

```cpp
int w, h, bpp;
if (pngDisplay.getPNGInfo_LFS(&w, &h, &bpp, "/assets/logo.png") == 1) {
    printf("Logo is %d x %d\n", w, h);
}
```

--------------------------------

### PNGDisplay Class Methods

Source: https://github.com/bitbank2/pngdec/blob/master/_autodocs/REFERENCE_INDEX.md

The PNGDisplay class offers methods to load PNG images directly onto a display device. It supports loading from memory buffers, SD card files, and LittleFS storage. It also provides functions to query PNG metadata without loading the entire image.

```APIDOC
## PNGDisplay Class Methods

### Description
Provides methods for loading PNG images onto a display and querying PNG metadata. Supports loading from memory, SD card, and LittleFS, with overloaded methods for different display types (BB_SPI_LCD, BBEPAPER, FASTEPD).

### Methods

- **`loadPNG(display, x, y, pData, iDataSize, bgColor)`**: Loads a PNG from a memory buffer to the specified display coordinates.
- **`loadPNG(display, x, y, fname, bgColor)`**: Loads a PNG from an SD card file to the specified display coordinates.
- **`loadPNG_LFS(display, x, y, fname, bgColor)`**: Loads a PNG from a LittleFS file to the specified display coordinates.
- **`getPNGInfo(width, height, bpp, pData, iDataSize)`**: Queries PNG metadata (width, height, bpp) from a memory buffer.
- **`getPNGInfo(width, height, bpp, fname)`**: Queries PNG metadata (width, height, bpp) from an SD card file.
- **`getPNGInfo_LFS(width, height, bpp, fname)`**: Queries PNG metadata (width, height, bpp) from a LittleFS file.
- **`getLastError()`**: Returns the last error code encountered.
```