Rotation Support (#77)

• What is the goal of this PR? Implement a horizontal EPUB reading mode so books can be read in landscape orientation (both 90° and 270°), while keeping the rest of the UI in portrait. • What changes are included? ◦ Rendering / Display ▪ Added an orientation model to GfxRenderer (Portrait, LandscapeNormal, LandscapeFlipped) and made: ▪ drawPixel, drawImage, displayWindow map logical coordinates differently depending on orientation. ▪ getScreenWidth() / getScreenHeight() return orientation‑aware logical dimensions (480×800 in portrait, 800×480 in landscape). ◦ Settings / Configuration ▪ Extended CrossPointSettings with: ▪ landscapeReading (toggle for portrait vs. landscape EPUB reading). ▪ landscapeFlipped (toggle to flip landscape 180° so both horizontal holding directions are supported). ▪ Updated settings serialization/deserialization to persist these fields while remaining backward‑compatible with existing settings files. ▪ Updated SettingsActivity to expose two new toggles: ▪ “Landscape Reading” ▪ “Flip Landscape (swap top/bottom)” ◦ EPUB Reader ▪ In EpubReaderActivity: ▪ On onEnter, set GfxRenderer orientation based on the new settings (Portrait, LandscapeNormal, or LandscapeFlipped). ▪ On onExit, reset orientation back to Portrait so Home, WiFi, Settings, etc. continue to render as before. ▪ Adjusted renderStatusBar to position the status bar and battery indicator relative to GfxRenderer::getScreenHeight() instead of hard‑coded Y coordinates, so it stays correctly at the bottom in both portrait and landscape. ◦ EPUB Caching / Layout ▪ Extended Section cache metadata (section.bin) to include the logical screenWidth and screenHeight used when pages were generated; bumped SECTION_FILE_VERSION. ▪ Updated loadCacheMetadata to compare: ▪ font/margins/line compression/extraParagraphSpacing and screen dimensions; mismatches now invalidate and clear the cache. ▪ Updated persistPageDataToSD and all call sites in EpubReaderActivity to pass the current GfxRenderer::getScreenWidth() / getScreenHeight() so portrait and landscape caches are kept separate and correctly sized. Additional Context • Cache behavior / migration ◦ Existing section.bin files (old SECTION_FILE_VERSION) will be detected as incompatible and their caches cleared and rebuilt once per chapter when first opened after this change. ◦ Within a given orientation, caches will be reused as before. Switching orientation (portrait ↔ landscape) will cause a one‑time re‑index of each chapter in the new orientation. • Scope and risks ◦ Orientation changes are scoped to the EPUB reader; the Home screen, Settings, WiFi selection, sleep screens, and web server UI continue to assume portrait orientation. ◦ The renderer’s orientation is a static/global setting; if future code uses GfxRenderer outside the reader while a reader instance is active, it should be aware that orientation is no longer implicitly fixed. ◦ All drawing primitives now go through orientation‑aware coordinate transforms; any code that previously relied on edge‑case behavior or out‑of‑bounds writes might surface as logged “Outside range” warnings instead. • Testing suggestions / areas to focus on ◦ Verify in hardware: ▪ Portrait mode still renders correctly (boot, home, settings, WiFi, reader). ▪ Landscape reading in both directions: ▪ Landscape Reading = ON, Flip Landscape = OFF. ▪ Landscape Reading = ON, Flip Landscape = ON. ▪ Status bar (page X/Y, % progress, battery icon) is fully visible and aligned at the bottom in all three combinations. ◦ Open the same book: ▪ In portrait first, then switch to landscape and reopen it. ▪ Confirm that: ▪ Old portrait caches are rebuilt once for landscape (you should see the “Indexing…” page). ▪ Progress save/restore still works (resume opens to the correct page in the current orientation). ◦ Ensure grayscale rendering (the secondary pass in EpubReaderActivity::renderContents) still looks correct in both orientations. --------- Co-authored-by: Dave Allie <dave@daveallie.com>
2025-12-28 05:33:20 -05:00
parent bf031fd999
commit dd280bdc97
22 changed files with 297 additions and 139 deletions
--- a/lib/Epub/Epub/Page.cpp
+++ b/lib/Epub/Epub/Page.cpp
@@ -7,7 +7,9 @@ namespace {
 constexpr uint8_t PAGE_FILE_VERSION = 3;
 }

-void PageLine::render(GfxRenderer& renderer, const int fontId) { block->render(renderer, fontId, xPos, yPos); }
+void PageLine::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) {
+  block->render(renderer, fontId, xPos + xOffset, yPos + yOffset);
+}

 void PageLine::serialize(File& file) {
  serialization::writePod(file, xPos);
@@ -27,9 +29,9 @@ std::unique_ptr<PageLine> PageLine::deserialize(File& file) {
  return std::unique_ptr<PageLine>(new PageLine(std::move(tb), xPos, yPos));
 }

-void Page::render(GfxRenderer& renderer, const int fontId) const {
+void Page::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) const {
  for (auto& element : elements) {
-    element->render(renderer, fontId);
+    element->render(renderer, fontId, xOffset, yOffset);
  }
 }

--- a/lib/Epub/Epub/Page.h
+++ b/lib/Epub/Epub/Page.h
@@ -17,7 +17,7 @@ class PageElement {
  int16_t yPos;
  explicit PageElement(const int16_t xPos, const int16_t yPos) : xPos(xPos), yPos(yPos) {}
  virtual ~PageElement() = default;
-  virtual void render(GfxRenderer& renderer, int fontId) = 0;
+  virtual void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) = 0;
  virtual void serialize(File& file) = 0;
 };

@@ -28,7 +28,7 @@ class PageLine final : public PageElement {
 public:
  PageLine(std::shared_ptr<TextBlock> block, const int16_t xPos, const int16_t yPos)
      : PageElement(xPos, yPos), block(std::move(block)) {}
-  void render(GfxRenderer& renderer, int fontId) override;
+  void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) override;
  void serialize(File& file) override;
  static std::unique_ptr<PageLine> deserialize(File& file);
 };
@@ -37,7 +37,7 @@ class Page {
 public:
  // the list of block index and line numbers on this page
  std::vector<std::shared_ptr<PageElement>> elements;
-  void render(GfxRenderer& renderer, int fontId) const;
+  void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) const;
  void serialize(File& file) const;
  static std::unique_ptr<Page> deserialize(File& file);
 };
--- a/lib/Epub/Epub/ParsedText.cpp
+++ b/lib/Epub/Epub/ParsedText.cpp
@@ -18,14 +18,14 @@ void ParsedText::addWord(std::string word, const EpdFontStyle fontStyle) {
 }

 // Consumes data to minimize memory usage
-void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fontId, const int horizontalMargin,
+void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fontId, const int viewportWidth,
                                       const std::function<void(std::shared_ptr<TextBlock>)>& processLine,
                                       const bool includeLastLine) {
  if (words.empty()) {
    return;
  }

-  const int pageWidth = renderer.getScreenWidth() - horizontalMargin;
+  const int pageWidth = viewportWidth;
  const int spaceWidth = renderer.getSpaceWidth(fontId);
  const auto wordWidths = calculateWordWidths(renderer, fontId);
  const auto lineBreakIndices = computeLineBreaks(pageWidth, spaceWidth, wordWidths);
--- a/lib/Epub/Epub/ParsedText.h
+++ b/lib/Epub/Epub/ParsedText.h
@@ -34,7 +34,7 @@ class ParsedText {
  TextBlock::BLOCK_STYLE getStyle() const { return style; }
  size_t size() const { return words.size(); }
  bool isEmpty() const { return words.empty(); }
-  void layoutAndExtractLines(const GfxRenderer& renderer, int fontId, int horizontalMargin,
+  void layoutAndExtractLines(const GfxRenderer& renderer, int fontId, int viewportWidth,
                             const std::function<void(std::shared_ptr<TextBlock>)>& processLine,
                             bool includeLastLine = true);
 };
--- a/lib/Epub/Epub/Section.cpp
+++ b/lib/Epub/Epub/Section.cpp
@@ -8,8 +8,8 @@
 #include "parsers/ChapterHtmlSlimParser.h"

 namespace {
-constexpr uint8_t SECTION_FILE_VERSION = 5;
-}
+constexpr uint8_t SECTION_FILE_VERSION = 6;
+}  // namespace

 void Section::onPageComplete(std::unique_ptr<Page> page) {
  const auto filePath = cachePath + "/page_" + std::to_string(pageCount) + ".bin";
@@ -26,9 +26,8 @@ void Section::onPageComplete(std::unique_ptr<Page> page) {
  pageCount++;
 }

-void Section::writeCacheMetadata(const int fontId, const float lineCompression, const int marginTop,
-                                 const int marginRight, const int marginBottom, const int marginLeft,
-                                 const bool extraParagraphSpacing) const {
+void Section::writeCacheMetadata(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
+                                 const int viewportWidth, const int viewportHeight) const {
  File outputFile;
  if (!FsHelpers::openFileForWrite("SCT", cachePath + "/section.bin", outputFile)) {
    return;
@@ -36,18 +35,15 @@ void Section::writeCacheMetadata(const int fontId, const float lineCompression,
  serialization::writePod(outputFile, SECTION_FILE_VERSION);
  serialization::writePod(outputFile, fontId);
  serialization::writePod(outputFile, lineCompression);
-  serialization::writePod(outputFile, marginTop);
-  serialization::writePod(outputFile, marginRight);
-  serialization::writePod(outputFile, marginBottom);
-  serialization::writePod(outputFile, marginLeft);
  serialization::writePod(outputFile, extraParagraphSpacing);
+  serialization::writePod(outputFile, viewportWidth);
+  serialization::writePod(outputFile, viewportHeight);
  serialization::writePod(outputFile, pageCount);
  outputFile.close();
 }

-bool Section::loadCacheMetadata(const int fontId, const float lineCompression, const int marginTop,
-                                const int marginRight, const int marginBottom, const int marginLeft,
-                                const bool extraParagraphSpacing) {
+bool Section::loadCacheMetadata(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
+                                const int viewportWidth, const int viewportHeight) {
  const auto sectionFilePath = cachePath + "/section.bin";
  File inputFile;
  if (!FsHelpers::openFileForRead("SCT", sectionFilePath, inputFile)) {
@@ -65,20 +61,18 @@ bool Section::loadCacheMetadata(const int fontId, const float lineCompression, c
      return false;
    }

-    int fileFontId, fileMarginTop, fileMarginRight, fileMarginBottom, fileMarginLeft;
+    int fileFontId, fileViewportWidth, fileViewportHeight;
    float fileLineCompression;
    bool fileExtraParagraphSpacing;
    serialization::readPod(inputFile, fileFontId);
    serialization::readPod(inputFile, fileLineCompression);
-    serialization::readPod(inputFile, fileMarginTop);
-    serialization::readPod(inputFile, fileMarginRight);
-    serialization::readPod(inputFile, fileMarginBottom);
-    serialization::readPod(inputFile, fileMarginLeft);
    serialization::readPod(inputFile, fileExtraParagraphSpacing);
+    serialization::readPod(inputFile, fileViewportWidth);
+    serialization::readPod(inputFile, fileViewportHeight);

-    if (fontId != fileFontId || lineCompression != fileLineCompression || marginTop != fileMarginTop ||
-        marginRight != fileMarginRight || marginBottom != fileMarginBottom || marginLeft != fileMarginLeft ||
-        extraParagraphSpacing != fileExtraParagraphSpacing) {
+    if (fontId != fileFontId || lineCompression != fileLineCompression ||
+        extraParagraphSpacing != fileExtraParagraphSpacing || viewportWidth != fileViewportWidth ||
+        viewportHeight != fileViewportHeight) {
      inputFile.close();
      Serial.printf("[%lu] [SCT] Deserialization failed: Parameters do not match\n", millis());
      clearCache();
@@ -113,9 +107,9 @@ bool Section::clearCache() const {
  return true;
 }

-bool Section::persistPageDataToSD(const int fontId, const float lineCompression, const int marginTop,
-                                  const int marginRight, const int marginBottom, const int marginLeft,
-                                  const bool extraParagraphSpacing, const std::function<void()>& progressSetupFn,
+bool Section::persistPageDataToSD(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
+                                  const int viewportWidth, const int viewportHeight,
+                                  const std::function<void()>& progressSetupFn,
                                  const std::function<void(int)>& progressFn) {
  constexpr size_t MIN_SIZE_FOR_PROGRESS = 50 * 1024;  // 50KB
  const auto localPath = epub->getSpineItem(spineIndex).href;
@@ -163,8 +157,8 @@ bool Section::persistPageDataToSD(const int fontId, const float lineCompression,
  }

  ChapterHtmlSlimParser visitor(
-      tmpHtmlPath, renderer, fontId, lineCompression, marginTop, marginRight, marginBottom, marginLeft,
-      extraParagraphSpacing, [this](std::unique_ptr<Page> page) { this->onPageComplete(std::move(page)); }, progressFn);
+      tmpHtmlPath, renderer, fontId, lineCompression, extraParagraphSpacing, viewportWidth, viewportHeight,
+      [this](std::unique_ptr<Page> page) { this->onPageComplete(std::move(page)); }, progressFn);
  success = visitor.parseAndBuildPages();

  SD.remove(tmpHtmlPath.c_str());
@@ -173,7 +167,7 @@ bool Section::persistPageDataToSD(const int fontId, const float lineCompression,
    return false;
  }

-  writeCacheMetadata(fontId, lineCompression, marginTop, marginRight, marginBottom, marginLeft, extraParagraphSpacing);
+  writeCacheMetadata(fontId, lineCompression, extraParagraphSpacing, viewportWidth, viewportHeight);

  return true;
 }
--- a/lib/Epub/Epub/Section.h
+++ b/lib/Epub/Epub/Section.h
@@ -13,8 +13,8 @@ class Section {
  GfxRenderer& renderer;
  std::string cachePath;

-  void writeCacheMetadata(int fontId, float lineCompression, int marginTop, int marginRight, int marginBottom,
-                          int marginLeft, bool extraParagraphSpacing) const;
+  void writeCacheMetadata(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
+                          int viewportHeight) const;
  void onPageComplete(std::unique_ptr<Page> page);

 public:
@@ -27,13 +27,12 @@ class Section {
        renderer(renderer),
        cachePath(epub->getCachePath() + "/" + std::to_string(spineIndex)) {}
  ~Section() = default;
-  bool loadCacheMetadata(int fontId, float lineCompression, int marginTop, int marginRight, int marginBottom,
-                         int marginLeft, bool extraParagraphSpacing);
+  bool loadCacheMetadata(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
+                         int viewportHeight);
  void setupCacheDir() const;
  bool clearCache() const;
-  bool persistPageDataToSD(int fontId, float lineCompression, int marginTop, int marginRight, int marginBottom,
-                           int marginLeft, bool extraParagraphSpacing,
-                           const std::function<void()>& progressSetupFn = nullptr,
+  bool persistPageDataToSD(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
+                           int viewportHeight, const std::function<void()>& progressSetupFn = nullptr,
                           const std::function<void(int)>& progressFn = nullptr);
  std::unique_ptr<Page> loadPageFromSD() const;
 };
--- a/lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp
+++ b/lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp
@@ -155,7 +155,7 @@ void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char
  if (self->currentTextBlock->size() > 750) {
    Serial.printf("[%lu] [EHP] Text block too long, splitting into multiple pages\n", millis());
    self->currentTextBlock->layoutAndExtractLines(
-        self->renderer, self->fontId, self->marginLeft + self->marginRight,
+        self->renderer, self->fontId, self->viewportWidth,
        [self](const std::shared_ptr<TextBlock>& textBlock) { self->addLineToPage(textBlock); }, false);
  }
 }
@@ -301,15 +301,14 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {

 void ChapterHtmlSlimParser::addLineToPage(std::shared_ptr<TextBlock> line) {
  const int lineHeight = renderer.getLineHeight(fontId) * lineCompression;
-  const int pageHeight = GfxRenderer::getScreenHeight() - marginTop - marginBottom;

-  if (currentPageNextY + lineHeight > pageHeight) {
+  if (currentPageNextY + lineHeight > viewportHeight) {
    completePageFn(std::move(currentPage));
    currentPage.reset(new Page());
-    currentPageNextY = marginTop;
+    currentPageNextY = 0;
  }

-  currentPage->elements.push_back(std::make_shared<PageLine>(line, marginLeft, currentPageNextY));
+  currentPage->elements.push_back(std::make_shared<PageLine>(line, 0, currentPageNextY));
  currentPageNextY += lineHeight;
 }

@@ -321,12 +320,12 @@ void ChapterHtmlSlimParser::makePages() {

  if (!currentPage) {
    currentPage.reset(new Page());
-    currentPageNextY = marginTop;
+    currentPageNextY = 0;
  }

  const int lineHeight = renderer.getLineHeight(fontId) * lineCompression;
  currentTextBlock->layoutAndExtractLines(
-      renderer, fontId, marginLeft + marginRight,
+      renderer, fontId, viewportWidth,
      [this](const std::shared_ptr<TextBlock>& textBlock) { addLineToPage(textBlock); });
  // Extra paragraph spacing if enabled
  if (extraParagraphSpacing) {
--- a/lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h
+++ b/lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h
@@ -32,11 +32,9 @@ class ChapterHtmlSlimParser {
  int16_t currentPageNextY = 0;
  int fontId;
  float lineCompression;
-  int marginTop;
-  int marginRight;
-  int marginBottom;
-  int marginLeft;
  bool extraParagraphSpacing;
+  int viewportWidth;
+  int viewportHeight;

  void startNewTextBlock(TextBlock::BLOCK_STYLE style);
  void makePages();
@@ -47,19 +45,17 @@ class ChapterHtmlSlimParser {

 public:
  explicit ChapterHtmlSlimParser(const std::string& filepath, GfxRenderer& renderer, const int fontId,
-                                 const float lineCompression, const int marginTop, const int marginRight,
-                                 const int marginBottom, const int marginLeft, const bool extraParagraphSpacing,
+                                 const float lineCompression, const bool extraParagraphSpacing, const int viewportWidth,
+                                 const int viewportHeight,
                                 const std::function<void(std::unique_ptr<Page>)>& completePageFn,
                                 const std::function<void(int)>& progressFn = nullptr)
      : filepath(filepath),
        renderer(renderer),
        fontId(fontId),
        lineCompression(lineCompression),
-        marginTop(marginTop),
-        marginRight(marginRight),
-        marginBottom(marginBottom),
-        marginLeft(marginLeft),
        extraParagraphSpacing(extraParagraphSpacing),
+        viewportWidth(viewportWidth),
+        viewportHeight(viewportHeight),
        completePageFn(completePageFn),
        progressFn(progressFn) {}
  ~ChapterHtmlSlimParser() = default;