Skip to content

Read a range of a text page's character geometry in one call - #126

Merged
bobsingor merged 1 commit into
embedpdf/mainfrom
embedpdf/feature/text-page-geometry
Nov 19, 2026
Merged

bobsingor merged 1 commit into
embedpdf/mainfrom
embedpdf/feature/text-page-geometry

Conversation

@bobsingor

@bobsingor bobsingor commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

The engine reads a page's text geometry one character at a time. For each character it calls FPDFText_GetTextObject and EPDFText_GetCharGeometry, and then reads 25 values of the struct, each across the boundary on its own. Crossing into JavaScript that often costs more than the geometry itself: on a 1,310-page text document those calls and reads take 4.6 ms a page on the native runtime and 4.0 ms on WASM, where parsing the page and building its text page take about 1.8 ms together.

This adds one call that writes the geometry of a range of characters into one buffer.

Change

typedef struct EPDF_PAGE_CHAR_GEOMETRY_ {
  EPDF_CHAR_GEOMETRY geometry;
  uint32_t object_run;
  float font_size;
} EPDF_PAGE_CHAR_GEOMETRY;

int EPDFText_GetPageGeometry(FPDF_TEXTPAGE text_page,
                             int start_index,
                             int count,
                             EPDF_PAGE_CHAR_GEOMETRY* buffer);
  • Each record holds what the three per-character calls answer: the character's EPDF_CHAR_GEOMETRY, the run of consecutive characters with one text object that it is in, and its font size (FPDFText_GetFontSize).
  • object_run counts from the page's first character whatever the range, so pieces read one after another are the page. Generated characters have no text object and make runs of their own.
  • It takes a start and a count, as FPDFText_GetText does, so a caller reads a large page in bounded pieces and can stop between two of them. It returns the number of characters written, 0 when the range names no character, and -1 for an invalid text page.
  • It carries no text, like EPDFText_GetCharGeometry: geometry and text stay two reads.
  • EPDFText_GetCharGeometry and the new call share one helper (CharGeometryOf), so a character's geometry is the same from either. static_asserts pin the record's layout (132 bytes).
  • The ledger's text-geometry rule names the new call.

Tests

In epdf_text_embeddertest.cpp:

  • GetPageGeometryMatchesTheCharCalls: every character of eight documents against the three calls, read in one piece and seven characters at a time. The documents hold upright, turned, sheared, mirrored and vertical text, a font with its own matrix, a Type3 font with a text object per glyph, and a character that prints nothing.
  • GetPageGeometryMatchesTheCharCallsOnActualText: the same for /ActualText on a page and through a form.
  • GetPageGeometryRunsFollowTheTextObjects: the three runs of hello_world.pdf and their font sizes, also from a range that starts inside a run.
  • GetPageGeometryReadsARange: a range in the middle, one that ends at the page's end, and ranges that name no character, which write nothing.
  • GetPageGeometryOfAPageWithoutText and GetPageGeometryInvalidArgs.

epdf_c_api_test.c lists the new function.

Checked

macOS arm64, on this branch (4a52c97 plus the change):

  • The text, C API and content rewrite embedder tests: 219 pass.
  • check-c-api.py: ok, 600 functions. check-fork-tags.py --strict: no untagged block.
  • Layer-mode writers: the six new tests leave nothing in a layer, so embedpdf_layer_mode_writers.txt is unchanged.

On the branch before it was rebased onto #125 (d0edbb1 plus the change):

  • Embedder: 1814 pass. The 12 failures are the ones on record for this Mac without the change.
  • Unit: 1402 pass.
  • Pixel: 51 failures and 2 surprises, as on record for this Mac.

With the engine's reader switched to the new call (its own pull request in embed-pdf-viewer, once this is released and pinned), the engine answers the same geometry for every page of a 1,310-page text document and of a 29-page CAD set, on WASM and on native. A whole geometry read of a text page, page load included, takes 3.7 ms where it took 7.1 ms on WASM, and 3.6 ms where it took 8.1 ms on native.

Linux x64, in the test image (scripts/test-pdfium.sh with PDFIUM_TEST_SUITE=all), on this branch:

  • Unit: 1409 pass.
  • Embedder: 1840 pass, 4 skipped, none failed. The six new tests are among those that pass.

The engine reads a page's text geometry one character at a time: for each
character a call to FPDFText_GetTextObject and one to EPDFText_GetCharGeometry,
and then 25 values of the struct, each read across the boundary on its own.
Crossing into JavaScript that often costs more than the geometry itself. On a
1,310-page text document the calls and reads take 4.6 ms a page on the native
runtime and 4.0 ms on WASM, more than parsing the page and building its text
page together.

EPDFText_GetPageGeometry(text_page, start_index, count, buffer) writes the
geometry of a range of characters into one buffer. Each EPDF_PAGE_CHAR_GEOMETRY
holds what the three calls answer for a character: its EPDF_CHAR_GEOMETRY, the
run of consecutive characters with one text object it is in (object_run), and
its font size. Runs count from the page's first character whatever the range,
so pieces read one after another are the page. It carries no text, like the
call it stands beside: geometry and text stay two reads.

It takes a start and a count, as FPDFText_GetText does, so a caller reads a
large page in bounded pieces and can stop between two of them.

EPDFText_GetCharGeometry and the new call share one helper, so a character's
geometry is the same from either.

Tests: the records against the three calls for every character of eight
documents (upright, turned, sheared, mirrored and vertical text, a font
matrix, a Type3 font with a text object per glyph, a character that prints
nothing) and of /ActualText on a page and through a form, read in one piece
and in pieces; the runs of hello_world.pdf; ranges that end at the page's
end or name no character; a page without text; an invalid text page.
@bobsingor
bobsingor marked this pull request as ready for review November 18, 2026 23:58
@bobsingor
bobsingor merged commit 47f0d99 into embedpdf/main Nov 19, 2026
1 check passed
@bobsingor
bobsingor deleted the embedpdf/feature/text-page-geometry branch November 19, 2026 00:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant