51 lines
3.5 KiB
Markdown
51 lines
3.5 KiB
Markdown
|
# Placeholder Cover Generation for Books Without Covers
|
||
|
|
|
||
|
|
## Task
|
||
|
|
Implement placeholder cover BMP generation for books that have no embedded cover image (or have covers in unsupported formats). Previously, these books showed empty rectangles on the home screen and fell back to the default sleep screen.
|
||
|
|
|
||
|
|
## Root Cause
|
||
|
|
Cover generation failed silently in three cases:
|
||
|
|
- **EPUB**: No `coverItemHref` in metadata, or cover is non-JPG format (PNG/SVG/GIF)
|
||
|
|
- **TXT**: No matching image file on the SD card
|
||
|
|
- **XTC**: First-page render failure (rare)
|
||
|
|
|
||
|
|
When `generateCoverBmp()` returned `false`, no BMP was created, and no fallback was attempted.
|
||
|
|
|
||
|
|
## Changes Made
|
||
|
|
|
||
|
|
### New Files
|
||
|
|
- `lib/PlaceholderCover/PlaceholderCoverGenerator.h` - Header for the placeholder generator
|
||
|
|
- `lib/PlaceholderCover/PlaceholderCoverGenerator.cpp` - Implementation: allocates a 1-bit pixel buffer, renders title/author text using EpdFont glyph data (ported from GfxRenderer::renderChar), writes a 1-bit BMP file with word-wrapped centered text, border, and separator line
|
||
|
|
|
||
|
|
### Modified Files
|
||
|
|
- `src/activities/reader/EpubReaderActivity.cpp` - Added placeholder fallback after `generateCoverBmp()` and `generateThumbBmp()` fail during first-open prerender
|
||
|
|
- `src/activities/reader/TxtReaderActivity.cpp` - Added placeholder fallback, added thumbnail generation (previously TXT had none), now passes thumb path to RECENT_BOOKS.addBook() instead of empty string
|
||
|
|
- `src/activities/reader/XtcReaderActivity.cpp` - Added placeholder fallback after cover/thumb generation fail (rare case)
|
||
|
|
- `src/activities/boot_sleep/SleepActivity.cpp` - Added placeholder generation before falling back to default sleep screen (handles books opened before this feature was added)
|
||
|
|
- `lib/Txt/Txt.h` - Added `getThumbBmpPath()` and `getThumbBmpPath(int height)` methods
|
||
|
|
- `lib/Txt/Txt.cpp` - Implemented the new thumb path methods
|
||
|
|
|
||
|
|
### Architecture
|
||
|
|
- Option B approach: shared `PlaceholderCoverGenerator` utility called from reader activities
|
||
|
|
- Generator is independent of `GfxRenderer` (no display framebuffer dependency)
|
||
|
|
- Includes Ubuntu 10 Regular and Ubuntu 12 Bold font data directly for self-contained rendering
|
||
|
|
- Memory: 48KB for full cover (480x800), 4-12KB for thumbnails; allocated and freed per call
|
||
|
|
|
||
|
|
## Flash Impact
|
||
|
|
- Before: 96.4% flash usage (6,317,250 bytes)
|
||
|
|
- After: 97.3% flash usage (6,374,546 bytes)
|
||
|
|
- Delta: ~57KB (mostly from duplicate font bitmap data included in the generator)
|
||
|
|
|
||
|
|
## Layout Revision (traditional book cover style)
|
||
|
|
- Border: moved inward with proportional edge padding (~10px at full size) and thickened to ~5px, keeping it visible within the device bezel
|
||
|
|
- Title: 2x integer-scaled Ubuntu 12 Bold (effectively ~24pt) for full-size covers, positioned in the top 2/3 zone, max 5 lines
|
||
|
|
- Author: positioned in the bottom 1/3 zone, max 3 lines with word wrapping
|
||
|
|
- Book icon: 48x48 1-bit bitmap (generated by `scripts/generate_book_icon.py`), displayed at 2x for full covers, 1x for medium thumbnails, omitted for small thumbnails
|
||
|
|
- Separator line between title and author zones
|
||
|
|
- All dimensions scale proportionally for thumbnails
|
||
|
|
|
||
|
|
## Follow-up Items
|
||
|
|
- Books opened before this feature was added won't get home screen thumbnails until re-opened (SleepActivity handles the sleep cover case by generating on demand)
|
||
|
|
- Font data duplication adds ~57KB flash; could be reduced by exposing shared font references instead of including headers directly
|
||
|
|
- Preview scripts in `scripts/` can regenerate the icon and layout previews: `generate_book_icon.py`, `preview_placeholder_cover.py`
|