Merge pull request #241 from jpirnay/feat-large-image-placeholder

feat: Render larger images on demand not by default
2026-05-19 13:28:53 +02:00
parent 0e0b729158 98bc29f41a
commit 78a6b2e215
11 changed files with 183 additions and 32 deletions
@@ -11,7 +11,7 @@
 #include "FsHelpers.h"

 namespace {
-constexpr uint8_t BOOK_CACHE_VERSION = 9;
+constexpr uint8_t BOOK_CACHE_VERSION = 10;
 constexpr char bookBinFile[] = "/book.bin";
 constexpr char tmpSpineBinFile[] = "/spine.bin.tmp";
 constexpr char tmpTocBinFile[] = "/toc.bin.tmp";
@@ -27,10 +27,13 @@ std::unique_ptr<PageLine> PageLine::deserialize(FsFile& file) {
 }

 void PageImage::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) {
-  // Images don't use fontId or text rendering
  imageBlock->render(renderer, xPos + xOffset, yPos + yOffset);
 }

+void PageImage::renderWithForceLoad(GfxRenderer& renderer, const int xOffset, const int yOffset, const bool forceLoad) {
+  imageBlock->render(renderer, xPos + xOffset, yPos + yOffset, forceLoad);
+}
+
 bool PageImage::serialize(FsFile& file) {
  serialization::writePod(file, xPos);
  serialization::writePod(file, yPos);
@@ -201,12 +204,41 @@ std::unique_ptr<PageTableFragment> PageTableFragment::deserialize(FsFile& file)
      new PageTableFragment(columnCount, totalWidth, totalHeight, colWidths, std::move(rows), xPos, yPos));
 }

-void Page::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) const {
+void Page::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset,
+                  const bool forceLoadLargeImages) const {
  for (auto& element : elements) {
-    element->render(renderer, fontId, xOffset, yOffset);
+    if (element->getTag() == TAG_PageImage) {
+      static_cast<PageImage&>(*element).renderWithForceLoad(renderer, xOffset, yOffset, forceLoadLargeImages);
+    } else {
+      element->render(renderer, fontId, xOffset, yOffset);
+    }
  }
 }

+bool Page::hasPlaceholderImages(const bool forceLoadLargeImages) const {
+  for (const auto& el : elements) {
+    if (el->getTag() == TAG_PageImage) {
+      if (static_cast<const PageImage&>(*el).getImageBlock().wouldShowPlaceholder(forceLoadLargeImages)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+bool Page::allImagesArePlaceholders(const bool forceLoadLargeImages) const {
+  bool anyImage = false;
+  for (const auto& el : elements) {
+    if (el->getTag() == TAG_PageImage) {
+      anyImage = true;
+      if (!static_cast<const PageImage&>(*el).getImageBlock().wouldShowPlaceholder(forceLoadLargeImages)) {
+        return false;
+      }
+    }
+  }
+  return anyImage;
+}
+
 void Page::renderTextOnly(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) const {
  for (auto& element : elements) {
    if (element->getTag() == TAG_PageLine) {
@@ -58,6 +58,7 @@ class PageImage final : public PageElement {
  PageImage(std::shared_ptr<ImageBlock> block, const int16_t xPos, const int16_t yPos)
      : PageElement(xPos, yPos), imageBlock(std::move(block)) {}
  void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) override;
+  void renderWithForceLoad(GfxRenderer& renderer, int xOffset, int yOffset, bool forceLoad);
  bool serialize(FsFile& file) override;
  PageElementTag getTag() const override { return TAG_PageImage; }
  static std::unique_ptr<PageImage> deserialize(FsFile& file);
@@ -128,8 +129,10 @@ class Page {
    footnotes.push_back(entry);
  }

-  void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) const;
+  void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset, bool forceLoadLargeImages = true) const;
  void renderTextOnly(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) const;
+  bool hasPlaceholderImages(bool forceLoadLargeImages) const;
+  bool allImagesArePlaceholders(bool forceLoadLargeImages) const;
  bool serialize(FsFile& file) const;
  static std::unique_ptr<Page> deserialize(FsFile& file);

@@ -1,20 +1,25 @@
 #include "ImageBlock.h"

+#include <FsHelpers.h>
 #include <GfxRenderer.h>
+#include <I18n.h>
 #include <Logging.h>
 #include <Serialization.h>

 #include "../../../../src/CrossPointSettings.h"
+#include "../../../../src/fontIds.h"
 #include "../converters/DirectPixelWriter.h"
 #include "../converters/ImageDecoderFactory.h"
+#include "../converters/JpegToFramebufferConverter.h"
+#include "../converters/PngToFramebufferConverter.h"

 // Cache file format:
 // - uint16_t width
 // - uint16_t height
 // - uint8_t pixels[...] - 2 bits per pixel, packed (4 pixels per byte), row-major order

-ImageBlock::ImageBlock(const std::string& imagePath, int16_t width, int16_t height)
-    : imagePath(imagePath), width(width), height(height) {}
+ImageBlock::ImageBlock(const std::string& imagePath, int16_t width, int16_t height, const std::string& altText)
+    : imagePath(imagePath), altText(altText), width(width), height(height) {}

 bool ImageBlock::imageExists() const { return Storage.exists(imagePath.c_str()); }

@@ -97,7 +102,56 @@ bool renderFromCache(GfxRenderer& renderer, const std::string& cachePath, int x,

 }  // namespace

-void ImageBlock::render(GfxRenderer& renderer, const int x, const int y) {
+bool ImageBlock::isLargeImage() const {
+  if (largeImageCached != 0) return largeImageCached == 1;
+  ImageDimensions dims{0, 0};
+  const bool ok = FsHelpers::hasJpgExtension(imagePath)
+                      ? JpegToFramebufferConverter::getDimensionsStatic(imagePath, dims)
+                      : PngToFramebufferConverter::getDimensionsStatic(imagePath, dims);
+  if (ok && dims.width > 0 && dims.height > 0) {
+    largeImageCached = (int32_t(dims.width) * dims.height > LARGE_IMAGE_PIXEL_THRESHOLD) ? 1 : -1;
+  } else {
+    largeImageCached = -1;  // unreadable header → assume not large, render normally
+  }
+  return largeImageCached == 1;
+}
+
+bool ImageBlock::wouldShowPlaceholder(bool forceLoad) const {
+  if (forceLoad) return false;
+  if (!isLargeImage()) return false;
+  // If the pixel cache already exists the render is instant — no placeholder needed
+  const ImageDitherMode ditherMode = imageDitherModeFromSetting(SETTINGS.imageDithering);
+  const std::string pxcPath = [&] {
+    size_t dot = imagePath.rfind('.');
+    return (dot != std::string::npos ? imagePath.substr(0, dot) : imagePath) + getImageDitherCacheSuffix(ditherMode) +
+           ".pxc";
+  }();
+  return !Storage.exists(pxcPath.c_str());
+}
+
+void ImageBlock::renderPlaceholder(GfxRenderer& renderer, const int x, const int y) const {
+  constexpr int BORDER = 1;
+  constexpr int PADDING = 6;
+
+  renderer.drawRect(x, y, width, height, BORDER, true);
+
+  const int lineH = renderer.getLineHeight(UI_10_FONT_ID);
+  const bool hasAlt = !altText.empty();
+  const int lineCount = hasAlt ? 3 : 2;
+  const int totalTextH = lineH * lineCount;
+
+  if (lineH > 0 && width > PADDING * 2 && height > totalTextH + PADDING * 2) {
+    const int textX = x + PADDING;
+    const int textY = y + (height - totalTextH) / 2;
+    renderer.drawText(UI_10_FONT_ID, textX, textY, tr(STR_LARGE_IMAGE));
+    if (hasAlt) {
+      renderer.drawText(UI_10_FONT_ID, textX, textY + lineH, altText.c_str());
+    }
+    renderer.drawText(UI_10_FONT_ID, textX, textY + lineH * (lineCount - 1), tr(STR_PRESS_CONFIRM_TO_LOAD));
+  }
+}
+
+void ImageBlock::render(GfxRenderer& renderer, const int x, const int y, const bool forceLoad) {
  LOG_DBG("IMG", "Rendering image at %d,%d: %s (%dx%d)", x, y, imagePath.c_str(), width, height);

  const int screenWidth = renderer.getScreenWidth();
@@ -110,15 +164,21 @@ void ImageBlock::render(GfxRenderer& renderer, const int x, const int y) {
    return;
  }

-  // Try to render from cache first
+  // Try to render from pixel cache first (always, regardless of forceLoad)
  const ImageDitherMode ditherMode = imageDitherModeFromSetting(SETTINGS.imageDithering);
  std::string cachePath = getCachePath(imagePath, ditherMode);
  if (renderFromCache(renderer, cachePath, x, y, width, height)) {
-    return;  // Successfully rendered from cache
+    return;
  }

-  // No cache - need to decode the image
-  // Check if image file exists
+  // No pixel cache — check if this is a large image that should show a placeholder
+  if (wouldShowPlaceholder(forceLoad)) {
+    LOG_DBG("IMG", "Large image placeholder at %d,%d (%dx%d): %s", x, y, width, height, imagePath.c_str());
+    renderPlaceholder(renderer, x, y);
+    return;
+  }
+
+  // Proceed with full decode
  FsFile file;
  if (!Storage.openFileForRead("IMG", imagePath, file)) {
    LOG_ERR("IMG", "Image file not found: %s", imagePath.c_str());
@@ -143,8 +203,8 @@ void ImageBlock::render(GfxRenderer& renderer, const int x, const int y) {
  config.useDithering = true;
  config.ditherMode = ditherMode;
  config.performanceMode = false;
-  config.useExactDimensions = true;  // Use pre-calculated dimensions to avoid rounding mismatches
-  config.cachePath = cachePath;      // Enable caching during decode
+  config.useExactDimensions = true;
+  config.cachePath = cachePath;

  ImageToFramebufferDecoder* decoder = ImageDecoderFactory::getDecoder(imagePath);
  if (!decoder) {
@@ -157,16 +217,14 @@ void ImageBlock::render(GfxRenderer& renderer, const int x, const int y) {
  bool success = decoder->decodeToFramebuffer(imagePath, renderer, config);
  if (!success) {
    LOG_ERR("IMG", "Failed to decode image: %s", imagePath.c_str());
-    return;
  }
-
-  LOG_DBG("IMG", "Decode successful");
 }

 bool ImageBlock::serialize(FsFile& file) {
  serialization::writeString(file, imagePath);
  serialization::writePod(file, width);
  serialization::writePod(file, height);
+  serialization::writeString(file, altText);
  return true;
 }

@@ -176,5 +234,7 @@ std::unique_ptr<ImageBlock> ImageBlock::deserialize(FsFile& file) {
  int16_t w, h;
  serialization::readPod(file, w);
  serialization::readPod(file, h);
-  return std::unique_ptr<ImageBlock>(new ImageBlock(path, w, h));
+  std::string alt;
+  serialization::readString(file, alt);
+  return std::unique_ptr<ImageBlock>(new ImageBlock(path, w, h, alt));
 }
@@ -6,26 +6,45 @@

 #include "Block.h"

+// Source pixel area above which an image is considered "large" and rendered
+// as a placeholder until the user explicitly requests it.
+// 800x600 covers most full-page illustrations that take >1s to dither on ESP32.
+static constexpr int32_t LARGE_IMAGE_PIXEL_THRESHOLD = 800 * 600;
+
 class ImageBlock final : public Block {
 public:
-  ImageBlock(const std::string& imagePath, int16_t width, int16_t height);
+  ImageBlock(const std::string& imagePath, int16_t width, int16_t height, const std::string& altText = "");
  ~ImageBlock() override = default;

  const std::string& getImagePath() const { return imagePath; }
  int16_t getWidth() const { return width; }
  int16_t getHeight() const { return height; }
+  const std::string& getAltText() const { return altText; }

  bool imageExists() const;

+  // Returns true if the source image dimensions exceed LARGE_IMAGE_PIXEL_THRESHOLD.
+  // Result is cached after the first call to avoid repeated header reads.
+  bool isLargeImage() const;
+
+  // Returns true if this image would be shown as a placeholder given forceLoad.
+  // False when: forceLoad is true, image is not large, or pixel cache already exists.
+  bool wouldShowPlaceholder(bool forceLoad) const;
+
  BlockType getType() override { return IMAGE_BLOCK; }
  bool isEmpty() override { return false; }

-  void render(GfxRenderer& renderer, const int x, const int y);
+  void render(GfxRenderer& renderer, int x, int y, bool forceLoad = true);
  bool serialize(FsFile& file);
  static std::unique_ptr<ImageBlock> deserialize(FsFile& file);

 private:
  std::string imagePath;
+  std::string altText;
  int16_t width;
  int16_t height;
+
+  mutable int8_t largeImageCached = 0;  // 0=unchecked, 1=large, -1=not large
+
+  void renderPlaceholder(GfxRenderer& renderer, int x, int y) const;
 };
@@ -849,7 +849,7 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
                self->currentPageNextY += imageSpacingTop;

                // Create ImageBlock and add to page
-                auto imageBlock = std::make_shared<ImageBlock>(cachedImagePath, displayWidth, displayHeight);
+                auto imageBlock = std::make_shared<ImageBlock>(cachedImagePath, displayWidth, displayHeight, alt);
                if (!imageBlock) {
                  LOG_ERR("EHP", "Failed to create ImageBlock");
                  return;
@@ -102,6 +102,9 @@ STR_IMAGES: "Images"
 STR_IMAGES_DISPLAY: "Display"
 STR_IMAGES_PLACEHOLDER: "Placeholder"
 STR_IMAGES_SUPPRESS: "Suppress"
+STR_LARGE_IMAGE_PLACEHOLDER: "Placeholder for large images"
+STR_LARGE_IMAGE: "Large Image"
+STR_PRESS_CONFIRM_TO_LOAD: "Press Confirm to load"
 STR_IMAGE_DITHERING: "Image Dithering"
 STR_IMAGE_DITHER_BAYER: "Bayer"
 STR_IMAGE_DITHER_ATKINSON: "Atkinson"
@@ -267,6 +267,9 @@ class CrossPointSettings {
  uint8_t showFileExtensions = 0;
  // Image rendering mode in EPUB reader
  uint8_t imageRendering = IMAGES_DISPLAY;
+  // Show a placeholder for large images (>800×600 source pixels) instead of decoding immediately.
+  // The user can press OK on the placeholder page to decode the image on demand.
+  uint8_t largeImagePlaceholder = 1;
  // Dithering mode for decoded images (EPUB/JPG/PNG)
  uint8_t imageDithering = IMAGE_DITHER_BAYER;
  // Tilt-based page turning (X3 only — requires QMI8658 IMU)
@@ -139,6 +139,8 @@ inline const std::vector<SettingInfo> list = {
    SettingInfo::Enum(StrId::STR_IMAGES, &CrossPointSettings::imageRendering,
                      {StrId::STR_IMAGES_DISPLAY, StrId::STR_IMAGES_PLACEHOLDER, StrId::STR_IMAGES_SUPPRESS},
                      "imageRendering", StrId::STR_CAT_READER),
+    SettingInfo::Toggle(StrId::STR_LARGE_IMAGE_PLACEHOLDER, &CrossPointSettings::largeImagePlaceholder,
+                        "largeImagePlaceholder", StrId::STR_CAT_READER),
    SettingInfo::Value(StrId::STR_SCREEN_MARGIN, &CrossPointSettings::screenMargin, {5, 40, 5}, "screenMargin",
                       StrId::STR_CAT_READER)
        .withSubmenu(StrId::STR_MENU_READER_SPACING),
@@ -407,6 +407,12 @@ void EpubReaderActivity::loop() {
        return;
      }
      if (ev.type == ButtonEventManager::PressType::Short) {
+        if (pageHasPlaceholders) {
+          forceLoadLargeImages = true;
+          pageHasPlaceholders = false;
+          requestUpdate();
+          return;
+        }
        openReaderMenu();
        return;
      }
@@ -607,6 +613,8 @@ void EpubReaderActivity::onReaderMenuConfirm(EpubReaderMenuActivity::MenuAction
                                    : std::nullopt;
            if (resolvedPage) {
              section->currentPage = *resolvedPage;
+              forceLoadLargeImages = false;
+              pageHasPlaceholders = false;
            } else {
              navTarget =
                  chapter.tocIndex ? NavigationTarget::makeTocIndex(*chapter.tocIndex) : NavigationTarget::makePage(0);
@@ -1512,6 +1520,8 @@ bool EpubReaderActivity::stepPageState(const bool isForwardTurn) {
  }

  lastPageTurnTime = millis();
+  forceLoadLargeImages = false;
+  pageHasPlaceholders = false;
  return true;
 }

@@ -1782,6 +1792,8 @@ void EpubReaderActivity::render(RenderLock&& lock) {

    navTarget.resolveInto(*section, currentSpineIndex);
    navTarget = NavigationTarget::makePage(section->currentPage);
+    forceLoadLargeImages = false;
+    pageHasPlaceholders = false;
  }

  renderer.clearScreen();
@@ -1949,15 +1961,20 @@ void EpubReaderActivity::renderContents(std::unique_ptr<Page> page, const int or
  }
  lastRenderStats.textAntiAliasing = aaEnabledForThisRender;

-  // Force special handling for pages with images when anti-aliasing is on
-  bool imagePageWithAA = page->hasImages() && aaEnabledForThisRender;
+  const bool effectiveForceLoad = forceLoadLargeImages || !SETTINGS.largeImagePlaceholder;
+  pageHasPlaceholders = page->hasPlaceholderImages(effectiveForceLoad);
+
+  // Force special handling for pages with at least one real (decoded) image when anti-aliasing is on.
+  // Mixed pages (some decoded, some placeholder) still need the AA codepath.
+  bool imagePageWithAA =
+      page->hasImages() && !page->allImagesArePlaceholders(effectiveForceLoad) && aaEnabledForThisRender;
  bool forceHalfRefreshThisPage = pendingHalfRefreshAfterImagePage && SETTINGS.halfRefreshAfterImagePage;
  pendingHalfRefreshAfterImagePage = false;
  lastRenderStats.imagePageWithAA = imagePageWithAA;
  lastRenderStats.forcedHalfRefresh = forceHalfRefreshThisPage;

  logReaderMemSnapshot("before_bw_render");
-  page->render(renderer, getEffectiveReaderFontId(), orientedMarginLeft, contentTop);
+  page->render(renderer, getEffectiveReaderFontId(), orientedMarginLeft, contentTop, effectiveForceLoad);
  renderStatusBar();
  if (showTruncatedSectionHintThisRender) {
    const int hintX = orientedMarginLeft + 4;
@@ -1993,7 +2010,7 @@ void EpubReaderActivity::renderContents(std::unique_ptr<Page> page, const int or

      // Re-render page content to restore images into the blanked area
      // Status bar is not re-rendered here to avoid reading stale dynamic values (e.g. battery %)
-      page->render(renderer, getEffectiveReaderFontId(), orientedMarginLeft, contentTop);
+      page->render(renderer, getEffectiveReaderFontId(), orientedMarginLeft, contentTop, effectiveForceLoad);
      renderer.displayBuffer(HalDisplay::FAST_REFRESH);
    } else {
      renderer.displayBuffer(HalDisplay::HALF_REFRESH);
@@ -2051,7 +2068,10 @@ void EpubReaderActivity::renderContents(std::unique_ptr<Page> page, const int or
    LOG_INF("ERS", "Skipping grayscale/BW-restore for this page (insufficient heap for BW snapshot)");
  }

-  if (page->hasImages() && getEffectiveImageRendering() != CrossPointSettings::IMAGES_SUPPRESS) {
+  // Only schedule the half-refresh if at least one real image was decoded on this page.
+  // Placeholder-only pages don't deposit grayscale data that needs settling.
+  if (page->hasImages() && !page->allImagesArePlaceholders(effectiveForceLoad) &&
+      getEffectiveImageRendering() != CrossPointSettings::IMAGES_SUPPRESS) {
    pendingHalfRefreshAfterImagePage = true;
  }

@@ -2137,8 +2157,8 @@ void EpubReaderActivity::renderContents(std::unique_ptr<Page> page, const int or
 }

 void EpubReaderActivity::renderPageContentOnly(const Page& page, const int orientedMarginTop,
-                                               const int orientedMarginRight,
-                                               const int orientedMarginBottom, const int orientedMarginLeft) {
+                                               const int orientedMarginRight, const int orientedMarginBottom,
+                                               const int orientedMarginLeft) {
  auto* fcm = renderer.getFontCacheManager();
  fcm->resetStats();

@@ -2155,8 +2175,8 @@ void EpubReaderActivity::renderPageContentOnly(const Page& page, const int orien
 }

 void EpubReaderActivity::displayPreRenderedPage(const Page& page, const int orientedMarginTop,
-                                                const int orientedMarginRight,
-                                                const int orientedMarginBottom, const int orientedMarginLeft) {
+                                                const int orientedMarginRight, const int orientedMarginBottom,
+                                                const int orientedMarginLeft) {
  const int viewportHeight = std::max(0, renderer.getScreenHeight() - orientedMarginTop - orientedMarginBottom);
  const int contentTop = orientedMarginTop + getImageOnlyPageYOffset(page, viewportHeight);

@@ -2509,6 +2529,8 @@ void EpubReaderActivity::onButtonAction(const CrossPointSettings::BUTTON_ACTION
                                         : std::nullopt;
                                 if (resolvedPage) {
                                   section->currentPage = *resolvedPage;
+                                   forceLoadLargeImages = false;
+                                   pageHasPlaceholders = false;
                                 } else {
                                   navTarget = chapter.tocIndex ? NavigationTarget::makeTocIndex(*chapter.tocIndex)
                                                                : NavigationTarget::makePage(0);
@@ -2535,6 +2557,8 @@ void EpubReaderActivity::onButtonAction(const CrossPointSettings::BUTTON_ACTION
            if (newSpineIndex == currentSpineIndex) {
              if (const auto resolvedPage = section->getPageForTocIndex(nextTocIndex)) {
                section->currentPage = *resolvedPage;
+                forceLoadLargeImages = false;
+                pageHasPlaceholders = false;
              }
            } else {
              navTarget = NavigationTarget::makeTocIndex(nextTocIndex);
@@ -109,6 +109,11 @@ class EpubReaderActivity final : public Activity {
  unsigned long lastPageTurnTime = 0UL;
  unsigned long pageTurnDuration = 0UL;
  bool pendingHalfRefreshAfterImagePage = false;
+  // When true, large images on the current page are decoded instead of shown as placeholders.
+  // Reset to false on every page turn so the next image page starts with a placeholder again.
+  bool forceLoadLargeImages = false;
+  // Set after each render: true if the current page contains at least one placeholder image.
+  bool pageHasPlaceholders = false;
  // Temporary AA suspension when BW snapshot allocation fails under memory pressure.
  // Automatically lifted once heap recovers above hysteresis thresholds.
  bool antiAliasingSuspendedLowMemory = false;
@@ -254,8 +259,8 @@ class EpubReaderActivity final : public Activity {
  // Draws the status bar over the current frame buffer and flushes to the display.
  // Handles the refresh cycle and grayscale AA pass. page must be the same page
  // that was last rendered into the buffer (needed for image AA re-render).
-  void displayPreRenderedPage(const Page& page, int orientedMarginTop, int orientedMarginRight, int orientedMarginBottom,
-                              int orientedMarginLeft);
+  void displayPreRenderedPage(const Page& page, int orientedMarginTop, int orientedMarginRight,
+                              int orientedMarginBottom, int orientedMarginLeft);
  void renderStatusBar() const;
  void silentIndexNextChapterIfNeeded(uint16_t viewportWidth, uint16_t viewportHeight);
  void saveProgress(int spineIndex, int currentPage, int pageCount);