Integrate PT 1455
This commit is contained in:
jpirnay
@@ -0,0 +1,159 @@
|
||||
# EPUB TOC Anchor Navigation
|
||||
|
||||
This document describes how the reader handles EPUB Table of Contents (TOC) entries that use fragment anchors to point into spine files, enabling navigation to sub-chapters within a single XHTML file.
|
||||
|
||||
## Background: EPUB spine and TOC structure
|
||||
|
||||
An EPUB's **spine** is an ordered list of XHTML files that define reading order. The **TOC** (table of contents) maps chapter names to positions in the spine, optionally with fragment anchors (e.g. `chapter1.xhtml#section-5`).
|
||||
|
||||
Two layouts are relevant here:
|
||||
|
||||
- **1:1** -- one TOC entry per spine item (most common, no anchors needed)
|
||||
- **Multi-TOC-per-spine** -- multiple TOC entries point into a single spine file using fragment anchors (e.g. Moby Dick from Project Gutenberg packs 3-9 chapters per file)
|
||||
|
||||
Spine items before the first TOC entry (cover pages) and after the last (appendices, copyright) have no TOC entry of their own.
|
||||
|
||||
## BookMetadataCache and TOC-to-spine mapping
|
||||
|
||||
`BookMetadataCache` builds the mapping between spine items and TOC entries at epub open time. Key details:
|
||||
|
||||
- Each `SpineEntry` has a `tocIndex` field set during cache building. For spines with no matching TOC entry, `tocIndex` inherits the previous spine's value (`lastSpineTocIndex`). This means orphan spines (cover pages, appendices) are treated as continuations of the nearest preceding chapter.
|
||||
- `getTocIndexForSpineIndex(i)` returns the stored `tocIndex` for spine `i` -- a file seek into BookMetadataCache, not computed on the fly.
|
||||
- `getTocItem(i)` returns the TOC entry (title, spineIndex, anchor) for TOC index `i` -- also a file seek per call, not cached in memory. Code that queries TOC metadata in a loop should cache the results locally first.
|
||||
- `getSpineIndexForTocIndex(i)` does the reverse lookup (TOC index to spine index).
|
||||
|
||||
## Section cache file format
|
||||
|
||||
The section cache (`.bin`) stores pre-rendered page data for a spine item. The file layout:
|
||||
|
||||
```
|
||||
[header: version, render parameters, pageCount, lutOffset, anchorMapOffset]
|
||||
[serialized pages...]
|
||||
[page LUT: array of uint32_t file offsets, one per page]
|
||||
[anchor map: uint16_t count, then (string, uint16_t) pairs]
|
||||
```
|
||||
|
||||
The header size is defined by `HEADER_SIZE` (a constexpr computed via `sizeof` sum) and validated with a `static_assert`. Three functions read this header independently and must stay in sync:
|
||||
|
||||
- `loadSectionFile` -- full section load, reads header + builds TOC boundaries from anchor map
|
||||
- `getPageForAnchor` -- seeks directly to anchor map offset from header
|
||||
- `writeSectionFileHeader` -- writes the header during cache creation
|
||||
|
||||
When modifying the header layout, bump `SECTION_FILE_VERSION` to invalidate stale caches and update all read paths.
|
||||
|
||||
## Anchor-to-page mapping
|
||||
|
||||
### Recording anchors during parsing
|
||||
|
||||
`ChapterHtmlSlimParser` records every HTML `id` attribute and its corresponding page number into `anchorData` (a flat `std::vector<std::pair<std::string, uint16_t>>`). Recording is deferred via `pendingAnchorId` until `startNewTextBlock()`, after the previous text block is flushed to pages via `makePages()`. This ensures `completedPageCount` reflects the correct page.
|
||||
|
||||
For TOC anchors specifically, `startNewTextBlock` also forces a page break before recording, so chapters start on fresh pages rather than mid-page. The parser receives the set of TOC anchor strings via `tocAnchors` (a `std::vector<std::string>`) from `Section::createSectionFile`.
|
||||
|
||||
### On-disk format
|
||||
|
||||
The anchor data is serialized at the end of the section cache file (`.bin`), after the page LUT. The header stores the anchor map offset. Format:
|
||||
|
||||
```
|
||||
[uint16_t count]
|
||||
[string anchor_1][uint16_t page_1]
|
||||
[string anchor_2][uint16_t page_2]
|
||||
...
|
||||
```
|
||||
|
||||
This data serves two purposes:
|
||||
- **Footnote navigation** (`getPageForAnchor`): on-demand linear scan for a single anchor
|
||||
- **TOC boundary resolution** (`buildTocBoundariesFromFile`): scan matching only TOC anchors
|
||||
|
||||
### Data structure choices
|
||||
|
||||
All anchor storage uses flat vectors, not `std::map` or `std::set`. On the ESP32-C3, each `std::map`/`std::set` node requires its own heap allocation, causing fragmentation. Vectors use a single contiguous allocation. The entry counts are small enough (typically 1-10 TOC anchors per spine, dozens to hundreds of total anchors) that linear scans are faster than tree lookups at these sizes.
|
||||
|
||||
## TOC boundaries in Section
|
||||
|
||||
When a section is loaded or created, `Section` builds an in-memory `tocBoundaries` vector mapping each TOC entry in that spine to its start page. This is a small vector (1-3 entries typically) that enables O(1) lookups without file I/O.
|
||||
|
||||
### Two build paths
|
||||
|
||||
**From in-memory anchors** (`buildTocBoundaries`): Called after `createSectionFile` when the parser's anchor vector is still in memory. Iterates TOC entries and does linear scans against the anchor vector.
|
||||
|
||||
**From disk** (`buildTocBoundariesFromFile`): Called from `loadSectionFile` when loading a cached section. Caches the small set of TOC anchor strings first (since `getTocItem()` does file I/O to `BookMetadataCache`), then streams through on-disk anchors matching only those, stopping early once all are resolved. Uses a reusable `std::string` buffer to avoid per-entry heap allocation.
|
||||
|
||||
The two functions are kept separate because their iteration patterns differ fundamentally: in-memory iterates TOC entries with inner scans of anchors, while the disk path iterates disk entries with inner scans of the small TOC anchor set.
|
||||
|
||||
### Early exit optimization
|
||||
|
||||
If no TOC entries in the spine have anchors (`unresolvedCount == 0`), both functions return immediately without storing any boundaries. `getTocIndexForPage` falls back to `epub->getTocIndexForSpineIndex`, which gives the correct answer for the common 1:1 case.
|
||||
|
||||
### Query methods
|
||||
|
||||
- `getTocIndexForPage(page)` -- binary search on sorted `tocBoundaries` to find which chapter a page belongs to
|
||||
- `getPageForTocIndex(tocIndex)` -- linear scan to find a chapter's start page
|
||||
- `getPageRangeForTocIndex(tocIndex)` -- returns `[startPage, endPage)` range for a chapter within this spine
|
||||
|
||||
All are in-memory, no file I/O.
|
||||
|
||||
## Chapter navigation in EpubReaderActivity
|
||||
|
||||
### Chapter skip (long-press)
|
||||
|
||||
Navigates by TOC index, not spine index. Uses `getTocIndexForPage` to determine the current chapter, then increments or decrements.
|
||||
|
||||
- **Same-spine skip**: Resolves the target page via `getPageForTocIndex` entirely in memory
|
||||
- **Cross-spine skip**: Sets `pendingTocIndex` (a `std::optional<int>`) which is resolved after the target section loads in `render()`
|
||||
- **Forward past last TOC entry**: Jumps to end-of-book (spine index clamped in `render()`)
|
||||
- **Backward before first TOC entry**: Jumps to the spine before the current chapter's first spine (clamped to 0 in `render()`)
|
||||
- **No TOC entry for spine** (`curTocIndex < 0`): Falls back to spine-level skip
|
||||
|
||||
### Chapter selector
|
||||
|
||||
The chapter selection activity receives `currentTocIndex` (per-page, not per-spine) so it highlights the correct sub-chapter. Returns `ChapterResult` with both `spineIndex` and `std::optional<int> tocIndex`. The reader resolves the page via `getPageForTocIndex` for same-spine navigation or defers via `pendingTocIndex` for cross-spine.
|
||||
|
||||
### Footnote navigation
|
||||
|
||||
Uses the existing `pendingAnchor` mechanism from the footnote anchor navigation commit (4d222567). `getPageForAnchor` does an on-demand linear scan of the on-disk anchor data. This is separate from TOC boundaries -- it reads all anchors (not just TOC ones) and is only called for footnote jumps.
|
||||
|
||||
### Status bar
|
||||
|
||||
Uses `getTocIndexForPage()` for the chapter title, so the status bar shows the correct sub-chapter name when reading a multi-TOC-per-spine file.
|
||||
|
||||
## Orphan spine handling
|
||||
|
||||
Spine items without a TOC entry inherit the previous spine's `tocIndex` in `BookMetadataCache`. This means:
|
||||
|
||||
- Pre-TOC spines (cover pages) may have `tocIndex == -1` if they're before any chapter
|
||||
- Post-TOC spines (appendices, copyright) inherit the last chapter's `tocIndex`
|
||||
|
||||
The chapter skip logic guards against `curTocIndex < 0` and falls back to spine-level navigation.
|
||||
|
||||
## Implementation pitfalls and edge cases
|
||||
|
||||
### Anchor recording timing
|
||||
|
||||
The `pendingAnchorId` deferred recording pattern is critical for correctness. Anchors must be recorded *after* `makePages()` flushes the previous text block (so `completedPageCount` reflects the right page) but the TOC page break must happen *before* recording (so the anchor lands on the new page). Both of these happen inside `startNewTextBlock()`. An earlier design used a `recordAnchor` lambda called at various points in `startElement()`, but this had wrong timing for headings and block elements -- `startNewTextBlock` would consume `pendingAnchorId` before `recordAnchor` could force the page break. Moving all page-break logic into `startNewTextBlock` fixed this.
|
||||
|
||||
### pendingAnchorId overwrite on consecutive elements
|
||||
|
||||
If two elements with `id` attributes appear before any `startNewTextBlock` call (e.g. nested divs), the second `id` overwrites `pendingAnchorId` and the first anchor is never recorded. This is a known limitation inherited from the footnote anchor navigation commit (4d222567) on master. In practice, TOC anchors are on chapter headings which trigger `startNewTextBlock`, so this doesn't affect TOC navigation.
|
||||
|
||||
### wordsExtractedInBlock reset on empty block reuse
|
||||
|
||||
When `startNewTextBlock` reuses an empty text block (the early-return path), `wordsExtractedInBlock` must be reset to 0. Without this, footnotes in the reused block could be assigned to wrong pages based on stale word counts from a prior block.
|
||||
|
||||
### getTocItem() does file I/O
|
||||
|
||||
`epub->getTocItem()` reads from `BookMetadataCache` via file seek on every call. This is why `buildTocBoundariesFromFile` caches the TOC anchor strings into a small vector before entering the disk scan loop -- otherwise the inner loop would do file I/O (BookMetadataCache) for every on-disk anchor entry.
|
||||
|
||||
### Defensive sort on tocBoundaries
|
||||
|
||||
`tocBoundaries` is sorted by `startPage` after building. In well-formed EPUBs, entries are already in order (TOC follows document order). The sort is a safety net for malformed EPUBs where TOC entries might be out of document order. With 1-3 entries it has no measurable cost.
|
||||
|
||||
## Test epub
|
||||
|
||||
`scripts/generate_spine_toc_edges_epub.py` generates `test/epubs/test_spine_toc_edges.epub`, a purpose-built epub that exercises spine/TOC relationship patterns. See the script header for the full list of edge cases covered.
|
||||
|
||||
## Performance characteristics
|
||||
|
||||
- **Per page turn**: All in-memory. `getTocIndexForPage` (binary search on 1-3 entries), `getTocItem` for title (one file seek to BookMetadataCache -- noted as a future optimization opportunity).
|
||||
- **Section load**: One file open for the section cache. `buildTocBoundariesFromFile` scans the anchor map for a few TOC entries with early exit.
|
||||
- **Footnote navigation**: One additional file open to scan the anchor map for a single anchor.
|
||||
- **1:1 TOC-to-spine (common case)**: No overhead. `unresolvedCount == 0`, `tocBoundaries` stays empty, all queries fall back to spine-level methods.
|
||||
+175
-2
@@ -4,6 +4,8 @@
|
||||
#include <Logging.h>
|
||||
#include <Serialization.h>
|
||||
|
||||
#include <algorithm>
|
||||
|
||||
#include "Epub/css/CssParser.h"
|
||||
#include "Page.h"
|
||||
#include "hyphenation/Hyphenator.h"
|
||||
@@ -147,6 +149,10 @@ bool Section::loadSectionFile(const int fontId, const float lineCompression, con
|
||||
return false;
|
||||
}
|
||||
}
|
||||
// Build TOC boundaries by scanning anchor data from the still-open file,
|
||||
// matching only the TOC anchors we need (avoids loading all anchors into memory).
|
||||
buildTocBoundariesFromFile(file);
|
||||
|
||||
// File is intentionally left open; subsequent loadPageFromSectionFile() calls
|
||||
// seek within this handle instead of re-opening the file each time.
|
||||
LOG_DBG("SCT", "Deserialization succeeded: %d pages, LUT cached", pageCount);
|
||||
@@ -244,11 +250,24 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
|
||||
}
|
||||
}
|
||||
|
||||
// Collect TOC anchors for this spine so the parser can insert page breaks at chapter boundaries
|
||||
std::vector<std::string> tocAnchors;
|
||||
const int startTocIndex = epub->getTocIndexForSpineIndex(spineIndex);
|
||||
if (startTocIndex >= 0) {
|
||||
for (int i = startTocIndex; i < epub->getTocItemsCount(); i++) {
|
||||
auto entry = epub->getTocItem(i);
|
||||
if (entry.spineIndex != spineIndex) break;
|
||||
if (!entry.anchor.empty()) {
|
||||
tocAnchors.push_back(std::move(entry.anchor));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
ChapterHtmlSlimParser visitor(
|
||||
epub, tmpHtmlPath, renderer, fontId, lineCompression, extraParagraphSpacing, paragraphAlignment, viewportWidth,
|
||||
viewportHeight, hyphenationEnabled,
|
||||
[this, &lut](std::unique_ptr<Page> page) { lut.emplace_back(this->onPageComplete(std::move(page))); },
|
||||
embeddedStyle, contentBase, imageBasePath, imageRendering, progressFn, cssParser);
|
||||
embeddedStyle, contentBase, imageBasePath, imageRendering, std::move(tocAnchors), progressFn, cssParser);
|
||||
Hyphenator::setPreferredLanguage(epub->getLanguage());
|
||||
success = visitor.parseAndBuildPages();
|
||||
|
||||
@@ -281,7 +300,7 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
|
||||
return false;
|
||||
}
|
||||
|
||||
// Write anchor-to-page map for fragment navigation (e.g. footnote targets)
|
||||
// Write anchor-to-page map for fragment navigation (TOC + footnote targets)
|
||||
const uint32_t anchorMapOffset = file.position();
|
||||
const auto& anchors = visitor.getAnchors();
|
||||
serialization::writePod(file, static_cast<uint16_t>(anchors.size()));
|
||||
@@ -309,6 +328,8 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
|
||||
cssParser->clear();
|
||||
}
|
||||
|
||||
buildTocBoundaries(anchors);
|
||||
|
||||
// Cache the LUT in memory and open the file for reading so that
|
||||
// subsequent loadPageFromSectionFile() calls can seek directly without re-opening.
|
||||
if (!Storage.openFileForRead("SCT", filePath, file)) {
|
||||
@@ -342,6 +363,158 @@ std::unique_ptr<Page> Section::loadPageFromSectionFile() {
|
||||
// File is intentionally NOT closed; stays open for the next page load
|
||||
}
|
||||
|
||||
// Resolve TOC anchor-to-page mappings from the parser's in-memory anchor vector.
|
||||
// Called after createSectionFile when anchors are already in memory.
|
||||
// See buildTocBoundariesFromFile for the on-disk variant; the two are kept separate
|
||||
// because the anchor resolution has fundamentally different iteration patterns
|
||||
// (scan in-memory vector vs. stream from file with early exit).
|
||||
void Section::buildTocBoundaries(const std::vector<std::pair<std::string, uint16_t>>& anchors) {
|
||||
const int startTocIndex = epub->getTocIndexForSpineIndex(spineIndex);
|
||||
if (startTocIndex < 0) return;
|
||||
|
||||
// Count TOC entries for this spine and how many have anchors to resolve
|
||||
const int tocCount = epub->getTocItemsCount();
|
||||
uint16_t totalEntries = 0;
|
||||
uint16_t unresolvedCount = 0;
|
||||
for (int i = startTocIndex; i < tocCount; i++) {
|
||||
const auto entry = epub->getTocItem(i);
|
||||
if (entry.spineIndex != spineIndex) break;
|
||||
totalEntries++;
|
||||
if (!entry.anchor.empty()) unresolvedCount++;
|
||||
}
|
||||
|
||||
// If no TOC entries have anchors, all chapters start at page 0 and
|
||||
// getTocIndexForPage falls back to epub->getTocIndexForSpineIndex,
|
||||
// so there's nothing to resolve and no value in storing boundaries.
|
||||
if (totalEntries == 0 || unresolvedCount == 0) return;
|
||||
|
||||
tocBoundaries.reserve(totalEntries);
|
||||
for (int i = startTocIndex; i < startTocIndex + totalEntries; i++) {
|
||||
const auto entry = epub->getTocItem(i);
|
||||
uint16_t page = 0;
|
||||
if (!entry.anchor.empty()) {
|
||||
for (const auto& [key, val] : anchors) {
|
||||
if (key == entry.anchor) {
|
||||
page = val;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
tocBoundaries.push_back({i, page});
|
||||
}
|
||||
|
||||
// Defensive sort in case TOC entries are out of document order in a malformed epub
|
||||
std::sort(tocBoundaries.begin(), tocBoundaries.end(),
|
||||
[](const TocBoundary& a, const TocBoundary& b) { return a.startPage < b.startPage; });
|
||||
}
|
||||
|
||||
// Resolve TOC anchor-to-page mappings by scanning the section cache's on-disk anchor data.
|
||||
// Called from loadSectionFile when anchors are not in memory. Caches the small set of
|
||||
// TOC anchor strings first (since getTocItem does file I/O to BookMetadataCache), then
|
||||
// streams through on-disk anchors matching only those, stopping as soon as all are found.
|
||||
// See buildTocBoundaries for the in-memory variant.
|
||||
void Section::buildTocBoundariesFromFile(FsFile& f) {
|
||||
const int startTocIndex = epub->getTocIndexForSpineIndex(spineIndex);
|
||||
if (startTocIndex < 0) return;
|
||||
|
||||
// Count TOC entries for this spine, then reserve and populate
|
||||
const int tocCount = epub->getTocItemsCount();
|
||||
uint16_t totalEntries = 0;
|
||||
uint16_t unresolvedCount = 0;
|
||||
for (int i = startTocIndex; i < tocCount; i++) {
|
||||
const auto entry = epub->getTocItem(i);
|
||||
if (entry.spineIndex != spineIndex) break;
|
||||
totalEntries++;
|
||||
if (!entry.anchor.empty()) unresolvedCount++;
|
||||
}
|
||||
|
||||
// If no TOC entries have anchors, all chapters start at page 0 and
|
||||
// getTocIndexForPage falls back to epub->getTocIndexForSpineIndex,
|
||||
// so there's nothing to resolve and no value in storing boundaries.
|
||||
if (totalEntries == 0 || unresolvedCount == 0) return;
|
||||
|
||||
// Cache TOC anchor strings before scanning disk, since getTocItem() does file I/O
|
||||
struct TocAnchorEntry {
|
||||
int tocIndex;
|
||||
std::string anchor;
|
||||
};
|
||||
std::vector<TocAnchorEntry> tocAnchorsToResolve;
|
||||
tocAnchorsToResolve.reserve(unresolvedCount);
|
||||
tocBoundaries.reserve(totalEntries);
|
||||
for (int i = startTocIndex; i < startTocIndex + totalEntries; i++) {
|
||||
const auto entry = epub->getTocItem(i);
|
||||
tocBoundaries.push_back({i, 0});
|
||||
if (!entry.anchor.empty()) {
|
||||
tocAnchorsToResolve.push_back({i, std::move(entry.anchor)});
|
||||
}
|
||||
}
|
||||
|
||||
// Single pass through on-disk anchors, matching against cached TOC anchors.
|
||||
// Stop early once all TOC anchors are resolved.
|
||||
// Header layout: ... | lutOffset (u32) | anchorMapOffset (u32) | paragraphLutOffset (u32) |
|
||||
f.seek(HEADER_SIZE - sizeof(uint32_t) * 2);
|
||||
uint32_t anchorMapOffset;
|
||||
serialization::readPod(f, anchorMapOffset);
|
||||
|
||||
if (anchorMapOffset != 0) {
|
||||
f.seek(anchorMapOffset);
|
||||
uint16_t count;
|
||||
serialization::readPod(f, count);
|
||||
std::string key;
|
||||
for (uint16_t i = 0; i < count && unresolvedCount > 0; i++) {
|
||||
uint16_t page;
|
||||
serialization::readString(f, key);
|
||||
serialization::readPod(f, page);
|
||||
for (auto& tocAnchor : tocAnchorsToResolve) {
|
||||
if (!tocAnchor.anchor.empty() && key == tocAnchor.anchor) {
|
||||
tocBoundaries[tocAnchor.tocIndex - startTocIndex].startPage = page;
|
||||
tocAnchor.anchor.clear(); // mark resolved
|
||||
unresolvedCount--;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Defensive sort in case TOC entries are out of document order in a malformed epub
|
||||
std::sort(tocBoundaries.begin(), tocBoundaries.end(),
|
||||
[](const TocBoundary& a, const TocBoundary& b) { return a.startPage < b.startPage; });
|
||||
}
|
||||
|
||||
int Section::getTocIndexForPage(const int page) const {
|
||||
if (tocBoundaries.empty()) {
|
||||
return epub->getTocIndexForSpineIndex(spineIndex);
|
||||
}
|
||||
|
||||
// Find the first boundary AFTER page, then step back one
|
||||
auto it = std::upper_bound(tocBoundaries.begin(), tocBoundaries.end(), static_cast<uint16_t>(page),
|
||||
[](uint16_t page, const TocBoundary& boundary) { return page < boundary.startPage; });
|
||||
if (it == tocBoundaries.begin()) {
|
||||
return tocBoundaries[0].tocIndex;
|
||||
}
|
||||
return std::prev(it)->tocIndex;
|
||||
}
|
||||
|
||||
std::optional<int> Section::getPageForTocIndex(const int tocIndex) const {
|
||||
for (const auto& boundary : tocBoundaries) {
|
||||
if (boundary.tocIndex == tocIndex) {
|
||||
return boundary.startPage;
|
||||
}
|
||||
}
|
||||
return std::nullopt;
|
||||
}
|
||||
|
||||
std::optional<Section::TocPageRange> Section::getPageRangeForTocIndex(const int tocIndex) const {
|
||||
for (size_t i = 0; i < tocBoundaries.size(); i++) {
|
||||
if (tocBoundaries[i].tocIndex == tocIndex) {
|
||||
const int startPage = tocBoundaries[i].startPage;
|
||||
const int endPage = (i + 1 < tocBoundaries.size()) ? static_cast<int>(tocBoundaries[i + 1].startPage) : pageCount;
|
||||
return TocPageRange{startPage, endPage};
|
||||
}
|
||||
}
|
||||
return std::nullopt;
|
||||
}
|
||||
|
||||
std::optional<uint16_t> Section::getPageForAnchor(const std::string& anchor) const {
|
||||
FsFile f;
|
||||
if (!Storage.openFileForRead("SCT", filePath, f)) {
|
||||
|
||||
@@ -23,6 +23,15 @@ class Section {
|
||||
bool embeddedStyle, uint8_t imageRendering);
|
||||
uint32_t onPageComplete(std::unique_ptr<Page> page);
|
||||
|
||||
struct TocBoundary {
|
||||
int tocIndex = 0;
|
||||
uint16_t startPage = 0;
|
||||
};
|
||||
std::vector<TocBoundary> tocBoundaries;
|
||||
|
||||
void buildTocBoundaries(const std::vector<std::pair<std::string, uint16_t>>& anchors);
|
||||
void buildTocBoundariesFromFile(FsFile& f);
|
||||
|
||||
public:
|
||||
uint16_t pageCount = 0;
|
||||
int currentPage = 0;
|
||||
@@ -42,6 +51,19 @@ class Section {
|
||||
uint8_t imageRendering, const std::function<void(int)>& progressFn = nullptr);
|
||||
std::unique_ptr<Page> loadPageFromSectionFile();
|
||||
|
||||
// Given a page in this section, return the TOC index for that page.
|
||||
int getTocIndexForPage(int page) const;
|
||||
// Given a TOC index, return the start page in this section.
|
||||
// Returns nullopt if the TOC index doesn't map to a boundary in this spine (e.g. belongs to a different spine).
|
||||
std::optional<int> getPageForTocIndex(int tocIndex) const;
|
||||
|
||||
struct TocPageRange {
|
||||
int startPage; // inclusive
|
||||
int endPage; // exclusive
|
||||
};
|
||||
// Returns the page range [start, end) within this spine that belongs to the given TOC index.
|
||||
std::optional<TocPageRange> getPageRangeForTocIndex(int tocIndex) const;
|
||||
|
||||
// Look up the page number for an anchor id from the section cache file.
|
||||
std::optional<uint16_t> getPageForAnchor(const std::string& anchor) const;
|
||||
|
||||
|
||||
@@ -7,6 +7,8 @@
|
||||
#include <Utf8.h>
|
||||
#include <expat.h>
|
||||
|
||||
#include <algorithm>
|
||||
|
||||
#include "../../Epub.h"
|
||||
#include "../Page.h"
|
||||
#include "../converters/ImageDecoderFactory.h"
|
||||
@@ -146,15 +148,35 @@ void ChapterHtmlSlimParser::startNewTextBlock(const BlockStyle& blockStyle) {
|
||||
currentTextBlock->setBlockStyle(currentTextBlock->getBlockStyle().getCombinedBlockStyle(incoming));
|
||||
|
||||
if (!pendingAnchorId.empty()) {
|
||||
if (std::find(tocAnchors.begin(), tocAnchors.end(), pendingAnchorId) != tocAnchors.end()) {
|
||||
if (currentPage && !currentPage->elements.empty()) {
|
||||
completePageFn(std::move(currentPage));
|
||||
completedPageCount++;
|
||||
currentPage.reset(new Page());
|
||||
currentPageNextY = 0;
|
||||
}
|
||||
}
|
||||
anchorData.push_back({std::move(pendingAnchorId), static_cast<uint16_t>(completedPageCount)});
|
||||
pendingAnchorId.clear();
|
||||
}
|
||||
wordsExtractedInBlock = 0;
|
||||
return;
|
||||
}
|
||||
|
||||
makePages();
|
||||
}
|
||||
// Record deferred anchor after previous block is flushed
|
||||
// If the pending anchor is a TOC chapter boundary, force a page break after the previous
|
||||
// block is flushed so the chapter starts on a fresh page.
|
||||
if (!pendingAnchorId.empty() &&
|
||||
std::find(tocAnchors.begin(), tocAnchors.end(), pendingAnchorId) != tocAnchors.end()) {
|
||||
if (currentPage && !currentPage->elements.empty()) {
|
||||
completePageFn(std::move(currentPage));
|
||||
completedPageCount++;
|
||||
currentPage.reset(new Page());
|
||||
currentPageNextY = 0;
|
||||
}
|
||||
}
|
||||
// Record deferred anchor after previous block is flushed (and any TOC page break)
|
||||
if (!pendingAnchorId.empty()) {
|
||||
anchorData.push_back({std::move(pendingAnchorId), static_cast<uint16_t>(completedPageCount)});
|
||||
pendingAnchorId.clear();
|
||||
@@ -182,7 +204,8 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
|
||||
} else if (strcmp(atts[i], "style") == 0) {
|
||||
styleAttr = atts[i + 1];
|
||||
} else if (strcmp(atts[i], "id") == 0) {
|
||||
// Defer recording until startNewTextBlock, after previous block is flushed to pages
|
||||
// Defer both anchor recording and TOC page breaks until startNewTextBlock,
|
||||
// after the previous block is flushed to pages via makePages().
|
||||
self->pendingAnchorId = atts[i + 1];
|
||||
}
|
||||
}
|
||||
|
||||
@@ -74,6 +74,7 @@ class ChapterHtmlSlimParser {
|
||||
int completedPageCount = 0;
|
||||
std::vector<std::pair<std::string, uint16_t>> anchorData;
|
||||
std::string pendingAnchorId; // deferred until after previous text block is flushed
|
||||
std::vector<std::string> tocAnchors;
|
||||
|
||||
// Paragraph index tracking for XPath-to-page lookup table.
|
||||
// Counts <p> sibling indices (1-based, matching XPath convention) during page building.
|
||||
@@ -110,6 +111,7 @@ class ChapterHtmlSlimParser {
|
||||
const std::function<void(std::unique_ptr<Page>)>& completePageFn,
|
||||
const bool embeddedStyle, const std::string& contentBase,
|
||||
const std::string& imageBasePath, const uint8_t imageRendering = 0,
|
||||
std::vector<std::string> tocAnchors = {},
|
||||
const std::function<void(int)>& progressFn = nullptr,
|
||||
const CssParser* cssParser = nullptr)
|
||||
|
||||
@@ -129,7 +131,8 @@ class ChapterHtmlSlimParser {
|
||||
embeddedStyle(embeddedStyle),
|
||||
imageRendering(imageRendering),
|
||||
contentBase(contentBase),
|
||||
imageBasePath(imageBasePath) {}
|
||||
imageBasePath(imageBasePath),
|
||||
tocAnchors(std::move(tocAnchors)) {}
|
||||
|
||||
~ChapterHtmlSlimParser() = default;
|
||||
bool parseAndBuildPages();
|
||||
|
||||
+1
-1
Submodule open-x4-sdk updated: 9f76376a5c...f14be998ab
File diff suppressed because it is too large
Load Diff
@@ -2,6 +2,7 @@
|
||||
|
||||
#include <cstdint>
|
||||
#include <functional>
|
||||
#include <optional>
|
||||
#include <string>
|
||||
#include <type_traits>
|
||||
#include <utility>
|
||||
@@ -27,6 +28,7 @@ struct MenuResult {
|
||||
|
||||
struct ChapterResult {
|
||||
int spineIndex = 0;
|
||||
std::optional<int> tocIndex;
|
||||
};
|
||||
|
||||
struct PercentResult {
|
||||
|
||||
@@ -219,14 +219,58 @@ void EpubReaderActivity::loop() {
|
||||
|
||||
const bool skipChapter = SETTINGS.longPressChapterSkip && mappedInput.getHeldTime() > skipChapterMs;
|
||||
|
||||
// Chapter skip navigates by TOC entries, not spine boundaries.
|
||||
// Spine items without their own TOC entry inherit the previous spine's tocIndex
|
||||
// (see BookMetadataCache), so they're treated as continuations of the last chapter.
|
||||
// At the boundaries: skipping forward past the last TOC entry jumps to end-of-book
|
||||
// (clamped in render()); skipping backward before the first TOC entry jumps to the
|
||||
// spine before the current chapter's first spine (clamped to 0 in render()).
|
||||
if (skipChapter) {
|
||||
lastPageTurnTime = millis();
|
||||
// We don't want to delete the section mid-render, so grab the semaphore
|
||||
{
|
||||
RenderLock lock(*this);
|
||||
nextPageNumber = 0;
|
||||
currentSpineIndex = nextTriggered ? currentSpineIndex + 1 : currentSpineIndex - 1;
|
||||
section.reset();
|
||||
|
||||
if (section && section->pageCount > 0) {
|
||||
const int curTocIndex = section->getTocIndexForPage(section->currentPage);
|
||||
const int nextTocIndex = nextTriggered ? curTocIndex + 1 : curTocIndex - 1;
|
||||
|
||||
if (curTocIndex < 0) {
|
||||
// No TOC entry for this spine, fall back to spine-level skip
|
||||
nextPageNumber = 0;
|
||||
currentSpineIndex = nextTriggered ? currentSpineIndex + 1 : currentSpineIndex - 1;
|
||||
section.reset();
|
||||
} else if (nextTocIndex >= 0 && nextTocIndex < epub->getTocItemsCount()) {
|
||||
const int newSpineIndex = epub->getSpineIndexForTocIndex(nextTocIndex);
|
||||
|
||||
if (newSpineIndex == currentSpineIndex) {
|
||||
if (const auto resolvedPage = section->getPageForTocIndex(nextTocIndex)) {
|
||||
section->currentPage = *resolvedPage;
|
||||
} else {
|
||||
LOG_DBG("ERS", "No page boundary for TOC %d in spine %d, staying on current page", nextTocIndex,
|
||||
currentSpineIndex);
|
||||
}
|
||||
} else {
|
||||
pendingTocIndex = nextTocIndex;
|
||||
nextPageNumber = 0;
|
||||
currentSpineIndex = newSpineIndex;
|
||||
section.reset();
|
||||
}
|
||||
} else if (nextTriggered) {
|
||||
// Beyond last TOC entry, go to end of book
|
||||
nextPageNumber = 0;
|
||||
currentSpineIndex = epub->getSpineItemsCount();
|
||||
section.reset();
|
||||
} else {
|
||||
// Before first TOC entry, skip to spine before the current chapter
|
||||
nextPageNumber = 0;
|
||||
currentSpineIndex = epub->getTocItem(curTocIndex).spineIndex - 1;
|
||||
section.reset();
|
||||
}
|
||||
} else {
|
||||
nextPageNumber = 0;
|
||||
currentSpineIndex = nextTriggered ? currentSpineIndex + 1 : currentSpineIndex - 1;
|
||||
section.reset();
|
||||
}
|
||||
}
|
||||
requestUpdate();
|
||||
return;
|
||||
@@ -312,13 +356,23 @@ void EpubReaderActivity::onReaderMenuConfirm(EpubReaderMenuActivity::MenuAction
|
||||
switch (action) {
|
||||
case EpubReaderMenuActivity::MenuAction::SELECT_CHAPTER: {
|
||||
const int spineIdx = currentSpineIndex;
|
||||
const int tocIdx = section ? section->getTocIndexForPage(section->currentPage)
|
||||
: epub->getTocIndexForSpineIndex(currentSpineIndex);
|
||||
const std::string path = epub->getPath();
|
||||
startActivityForResult(
|
||||
std::make_unique<EpubReaderChapterSelectionActivity>(renderer, mappedInput, epub, path, spineIdx),
|
||||
std::make_unique<EpubReaderChapterSelectionActivity>(renderer, mappedInput, epub, path, spineIdx, tocIdx),
|
||||
[this](const ActivityResult& result) {
|
||||
if (!result.isCancelled && currentSpineIndex != std::get<ChapterResult>(result.data).spineIndex) {
|
||||
RenderLock lock(*this);
|
||||
currentSpineIndex = std::get<ChapterResult>(result.data).spineIndex;
|
||||
if (result.isCancelled) return;
|
||||
RenderLock lock(*this);
|
||||
const auto& chapter = std::get<ChapterResult>(result.data);
|
||||
auto resolvedPage = (chapter.tocIndex && chapter.spineIndex == currentSpineIndex && section)
|
||||
? section->getPageForTocIndex(*chapter.tocIndex)
|
||||
: std::nullopt;
|
||||
if (resolvedPage) {
|
||||
section->currentPage = *resolvedPage;
|
||||
} else {
|
||||
pendingTocIndex = chapter.tocIndex;
|
||||
currentSpineIndex = chapter.spineIndex;
|
||||
nextPageNumber = 0;
|
||||
section.reset();
|
||||
}
|
||||
@@ -613,7 +667,7 @@ void EpubReaderActivity::render(RenderLock&& lock) {
|
||||
const uint8_t imageRendering = getEffectiveImageRendering();
|
||||
const auto filepath = epub->getSpineItem(currentSpineIndex).href;
|
||||
LOG_DBG("ERS", "Loading file: %s, index: %d", filepath.c_str(), currentSpineIndex);
|
||||
section = std::unique_ptr<Section>(new Section(epub, currentSpineIndex, renderer));
|
||||
section = std::make_unique<Section>(epub, currentSpineIndex, renderer);
|
||||
|
||||
if (!section->loadSectionFile(SETTINGS.getReaderFontId(), SETTINGS.getReaderLineCompression(),
|
||||
SETTINGS.extraParagraphSpacing, SETTINGS.paragraphAlignment, viewportWidth,
|
||||
@@ -646,6 +700,13 @@ void EpubReaderActivity::render(RenderLock&& lock) {
|
||||
section->currentPage = nextPageNumber;
|
||||
}
|
||||
|
||||
if (pendingTocIndex) {
|
||||
if (const auto resolvedPage = section->getPageForTocIndex(*pendingTocIndex)) {
|
||||
section->currentPage = *resolvedPage;
|
||||
}
|
||||
pendingTocIndex.reset();
|
||||
}
|
||||
|
||||
if (!pendingAnchor.empty()) {
|
||||
if (const auto page = section->getPageForAnchor(pendingAnchor)) {
|
||||
section->currentPage = *page;
|
||||
@@ -895,28 +956,25 @@ void EpubReaderActivity::renderStatusBar() const {
|
||||
const float bookProgress = epub->calculateProgress(currentSpineIndex, sectionChapterProg) * 100;
|
||||
|
||||
std::string title;
|
||||
|
||||
int textYOffset = 0;
|
||||
|
||||
if (automaticPageTurnActive) {
|
||||
title = tr(STR_AUTO_TURN_ENABLED) + std::to_string(60 * 1000 / pageTurnDuration);
|
||||
|
||||
// calculates textYOffset when rendering title in status bar
|
||||
const uint8_t statusBarHeight = UITheme::getInstance().getStatusBarHeight();
|
||||
|
||||
// offsets text if no status bar or progress bar only
|
||||
if (statusBarHeight == 0 || statusBarHeight == UITheme::getInstance().getProgressBarHeight()) {
|
||||
textYOffset += UITheme::getInstance().getMetrics().statusBarVerticalMargin;
|
||||
}
|
||||
|
||||
} else if (SETTINGS.statusBarTitle == CrossPointSettings::STATUS_BAR_TITLE::CHAPTER_TITLE) {
|
||||
title = tr(STR_UNNAMED);
|
||||
const int tocIndex = epub->getTocIndexForSpineIndex(currentSpineIndex);
|
||||
if (tocIndex != -1) {
|
||||
const int tocIndex =
|
||||
section ? section->getTocIndexForPage(section->currentPage) : epub->getTocIndexForSpineIndex(currentSpineIndex);
|
||||
if (tocIndex == -1) {
|
||||
title = tr(STR_UNNAMED);
|
||||
} else {
|
||||
const auto tocItem = epub->getTocItem(tocIndex);
|
||||
title = tocItem.title;
|
||||
}
|
||||
|
||||
} else if (SETTINGS.statusBarTitle == CrossPointSettings::STATUS_BAR_TITLE::BOOK_TITLE) {
|
||||
title = epub->getTitle();
|
||||
}
|
||||
|
||||
@@ -3,6 +3,8 @@
|
||||
#include <Epub/FootnoteEntry.h>
|
||||
#include <Epub/Section.h>
|
||||
|
||||
#include <optional>
|
||||
|
||||
#include "EpubReaderMenuActivity.h"
|
||||
#include "activities/Activity.h"
|
||||
|
||||
@@ -11,6 +13,9 @@ class EpubReaderActivity final : public Activity {
|
||||
std::unique_ptr<Section> section = nullptr;
|
||||
int currentSpineIndex = 0;
|
||||
int nextPageNumber = 0;
|
||||
// Set when navigating to a TOC entry in a different spine (chapter skip or chapter selector).
|
||||
// Cleared on the next render after the new section loads and resolves it to a page.
|
||||
std::optional<int> pendingTocIndex;
|
||||
// Set when navigating to a footnote href with a fragment (e.g. #note1).
|
||||
// Cleared on the next render after the new section loads and resolves it to a page.
|
||||
std::string pendingAnchor;
|
||||
|
||||
@@ -25,7 +25,9 @@ void EpubReaderChapterSelectionActivity::onEnter() {
|
||||
return;
|
||||
}
|
||||
|
||||
selectorIndex = epub->getTocIndexForSpineIndex(currentSpineIndex);
|
||||
selectorIndex = (currentTocIndex >= 0 && currentTocIndex < epub->getTocItemsCount())
|
||||
? currentTocIndex
|
||||
: epub->getTocIndexForSpineIndex(currentSpineIndex);
|
||||
if (selectorIndex == -1) {
|
||||
selectorIndex = 0;
|
||||
}
|
||||
@@ -48,7 +50,7 @@ void EpubReaderChapterSelectionActivity::loop() {
|
||||
setResult(std::move(result));
|
||||
finish();
|
||||
} else {
|
||||
setResult(ChapterResult{newSpineIndex});
|
||||
setResult(ChapterResult{newSpineIndex, selectorIndex});
|
||||
finish();
|
||||
}
|
||||
} else if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
|
||||
|
||||
@@ -11,6 +11,7 @@ class EpubReaderChapterSelectionActivity final : public Activity {
|
||||
std::string epubPath;
|
||||
ButtonNavigator buttonNavigator;
|
||||
int currentSpineIndex = 0;
|
||||
int currentTocIndex = 0;
|
||||
int selectorIndex = 0;
|
||||
|
||||
// Number of items that fit on a page, derived from logical screen height.
|
||||
@@ -23,11 +24,12 @@ class EpubReaderChapterSelectionActivity final : public Activity {
|
||||
public:
|
||||
explicit EpubReaderChapterSelectionActivity(GfxRenderer& renderer, MappedInputManager& mappedInput,
|
||||
const std::shared_ptr<Epub>& epub, const std::string& epubPath,
|
||||
const int currentSpineIndex)
|
||||
const int currentSpineIndex, const int currentTocIndex)
|
||||
: Activity("EpubReaderChapterSelection", renderer, mappedInput),
|
||||
epub(epub),
|
||||
epubPath(epubPath),
|
||||
currentSpineIndex(currentSpineIndex) {}
|
||||
currentSpineIndex(currentSpineIndex),
|
||||
currentTocIndex(currentTocIndex) {}
|
||||
void onEnter() override;
|
||||
void onExit() override;
|
||||
void loop() override;
|
||||
|
||||
Binary file not shown.
Reference in New Issue
Block a user