Document decode_into() usage and update benchmark results (ESP32S3)

[itdogwowo]

Summary

This PR improves the documentation for the new Decoder.decode_into() API and refreshes benchmark results using an ESP32S3 run. The goal is to clarify how decode_into() should be used for framebuffer-oriented rendering, including both FULL and STEP (cooperative) modes.

Changes

• README
  • Added a practical guide for decode_into() :
    • Framebuffer sizing by pixel format (bytes-per-pixel)
    • FULL decode vs STEP decode usage examples
    • Correct STEP loop pattern ( blocks>0 until done=True )
    • Guidance on when to use decode_into() vs decode(block=True)
    • Notes on block-mode limitations and auto-rewind behavior
  • Updated Benchmark section with the latest ESP32S3 results (240×240 image and new result tables)
• Benchmark script
  • Updated the benchmark script to print richer image metadata (width/height, blocks, block height, GC stats if available, and per-format framebuffer size)
  • Keeps a static default image path in the file ( DEFAULT_IMAGE_PATH ) for quick re-runs

Benchmark Environment

• Board: ESP32S3
• JPEG Driver Version: 1.0.0
• Image: 000.jpeg
• Resolution: 240×240
• JPEG size: 32,627 bytes
• Blocks: 30 (block height: 8 )
• NR: 100

Results

Decoder FPS

Format FPS normal decode ( decode , block=False) FPS block decode ( decode , block=True) FPS block decode + write (python slice) FPS decode_into step (blocks=1) FPS decode_into full (blocks=0) RGB565_BE 18.47 24.65 4.82 21.38 21.52 RGB565_LE 18.46 24.65 4.82 21.40 21.52 RGB888 16.49 23.75 3.43 20.19 20.34 CbYCrY 18.92 26.03 4.85 21.99 22.13

Encoder FPS (RGB888)

Quality FPS 100 10.95 90 16.88 80 19.18 70 20.23 60 22.46

Performance Comparison (non-exaggerated)

decode_into() mainly improves the decode + write-to-framebuffer workflow by writing directly into a user-provided buffer and avoiding Python-level slice assembly. The module still supports direct decode() for full-frame output.

A) Full-frame workflow: decode_into(full) vs decode(normal)

This compares “get a full frame result” in one call path.

• RGB565_BE : 18.47 → 21.52 FPS ( +16.5% )
• RGB565_LE : 18.46 → 21.52 FPS ( +16.6% )
• RGB888 : 16.49 → 20.34 FPS ( +23.4% )
• CbYCrY : 18.92 → 22.13 FPS ( +16.9% )

B) Framebuffer assembly path: decode_into(full) vs block decode + Python slice write

This reflects the common UI case where blocks must be placed into a full framebuffer.

• RGB565_BE : 4.82 → 21.52 FPS ( 4.46× )
• RGB565_LE : 4.82 → 21.52 FPS ( 4.46× )
• RGB888 : 3.43 → 20.34 FPS ( 5.93× )
• CbYCrY : 4.85 → 22.13 FPS ( 4.56× )

C) Cooperative scheduling: decode_into(step) vs decode_into(full)

STEP mode shows minimal overhead in this test (typically within ~0.5–1 FPS), making it practical for responsive UI loops.

Notes

• STEP mode ( blocks>0 ) is intended for cooperative decoding; keep calling until done=True .
• In block=True mode: rotation must be 0, and scaling/clipping are not supported.
• The decoder auto-rewinds after completing a full decode round when decode_into() is called again with the same jpeg_data , which is convenient for animation loops.

Testing

• Ran the benchmark on-device (ESP32S3) and captured the results above.

Breaking Changes

• None.