summaryrefslogtreecommitdiff
path: root/addons/pdf/pdf_bridge.h
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-06 06:24:42 -0300
committerGabriel Schneider <[email protected]>2026-11-06 11:19:32 -0300
commit76c55b5bce0f181b0b15b16596c900397dfef544 (patch)
treee99180a43bfaa7d8d7c3ff22ed28ee5c425c3e1a /addons/pdf/pdf_bridge.h
parent0893d632e242553390d968751fff0e880627c34a (diff)
downloadpardes-76c55b5bce0f181b0b15b16596c900397dfef544.tar.gz
pardes-76c55b5bce0f181b0b15b16596c900397dfef544.zip
kinds #13, pdf.so: addons/pdf/pdf.c is the PDF kind against ABI 2.1 (its record the file's bytes, renders on jobs over two MuPDF lanes a cookie aborts, its strip laid out at `at` with crops and repainted rows for hover and selection, its text the body, search, links and PdfSections through look and text, P:F S places, PdfFit, PdfTint, PdfSections, its keys), pdf_bridge moves beside it, and the build makes it from position-independent MuPDF, FreeType and zlib exporting pardes_addon alone, installs <prefix>/lib/pardes/addons/pdf.so, -Dmupdf now builds it or not and mupdf-check runs its addon-test script
Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
Diffstat (limited to 'addons/pdf/pdf_bridge.h')
-rw-r--r--addons/pdf/pdf_bridge.h402
1 files changed, 402 insertions, 0 deletions
diff --git a/addons/pdf/pdf_bridge.h b/addons/pdf/pdf_bridge.h
new file mode 100644
index 00000000..fd5d05d0
--- /dev/null
+++ b/addons/pdf/pdf_bridge.h
@@ -0,0 +1,402 @@
+#ifndef PARDES_PDF_BRIDGE_H
+#define PARDES_PDF_BRIDGE_H
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * MuPDF reports failures with setjmp/longjmp through fz_try/fz_catch. Those
+ * jumps must never cross Zig frames, so every operation that can throw lives
+ * behind this deliberately small C boundary.
+ */
+typedef struct pardes_pdf_document pardes_pdf_document;
+
+typedef void *(*pardes_pdf_alloc_fn)(void *user, size_t size);
+typedef void *(*pardes_pdf_realloc_fn)(
+ void *user,
+ void *pointer,
+ size_t size
+);
+typedef void (*pardes_pdf_free_fn)(void *user, void *pointer);
+
+typedef struct pardes_pdf_allocator {
+ void *user;
+ pardes_pdf_alloc_fn alloc;
+ pardes_pdf_realloc_fn realloc;
+ pardes_pdf_free_fn free;
+} pardes_pdf_allocator;
+
+/*
+ * Install one process-global allocator, or restore libc/default MuPDF
+ * allocation by passing NULL. Changing it while a document is live fails.
+ */
+int pardes_pdf_set_allocator(const pardes_pdf_allocator *allocator);
+
+typedef struct pardes_pdf_raster_layout {
+ int width;
+ int height;
+ int stride;
+ size_t samples_len;
+} pardes_pdf_raster_layout;
+
+/*
+ * One raster request (pdf.zig's RenderRequest, bounded): every function
+ * that rasterizes a page, paints over it or measures it takes the same one
+ * and computes the same raster from it (see pardes_pdf_measure_render).
+ * Zero minimum or display sizes are none.
+ */
+typedef struct pardes_pdf_request {
+ int dpi;
+ int minimum_width;
+ int minimum_height;
+ int max_dimension;
+ int display_width;
+ int display_height;
+} pardes_pdf_request;
+
+typedef struct pardes_pdf_page_size {
+ float width;
+ float height;
+} pardes_pdf_page_size;
+
+typedef struct pardes_pdf_text {
+ void *handle;
+ const unsigned char *data;
+ size_t len;
+} pardes_pdf_text;
+
+/*
+ * All geometry crossing this boundary is normalized to the cached page's
+ * bounds. (0,0) is the page's top-left and (1,1) its bottom-right, regardless
+ * of the DPI used for a particular render. Corner names retain MuPDF's quad
+ * orientation; callers must not collapse them to an axis-aligned rectangle.
+ */
+typedef struct pardes_pdf_point {
+ float x;
+ float y;
+} pardes_pdf_point;
+
+typedef struct pardes_pdf_quad {
+ pardes_pdf_point ul;
+ pardes_pdf_point ur;
+ pardes_pdf_point ll;
+ pardes_pdf_point lr;
+} pardes_pdf_quad;
+
+typedef enum pardes_pdf_highlight_kind {
+ PARDES_PDF_HIGHLIGHT_CUSTOM = 0,
+ PARDES_PDF_HIGHLIGHT_SEARCH = 1,
+ PARDES_PDF_HIGHLIGHT_SELECTION = 2
+} pardes_pdf_highlight_kind;
+
+typedef struct pardes_pdf_highlight {
+ pardes_pdf_quad quad;
+ unsigned char rgba[4];
+ int kind;
+} pardes_pdf_highlight;
+
+typedef struct pardes_pdf_search_quad {
+ pardes_pdf_quad quad;
+ size_t hit;
+} pardes_pdf_search_quad;
+
+typedef struct pardes_pdf_search_result {
+ void *handle;
+ const pardes_pdf_search_quad *quads;
+ size_t quad_count;
+ size_t hit_count;
+} pardes_pdf_search_result;
+
+typedef struct pardes_pdf_selection {
+ void *handle;
+ const pardes_pdf_quad *quads;
+ size_t quad_count;
+ pardes_pdf_point start;
+ pardes_pdf_point end;
+} pardes_pdf_selection;
+
+typedef struct pardes_pdf_owned_text {
+ void *handle;
+ const unsigned char *data;
+ size_t len;
+} pardes_pdf_owned_text;
+
+typedef enum pardes_pdf_outline_destination_kind {
+ PARDES_PDF_OUTLINE_DESTINATION_NONE = 0,
+ PARDES_PDF_OUTLINE_DESTINATION_INTERNAL = 1,
+ PARDES_PDF_OUTLINE_DESTINATION_EXTERNAL = 2
+} pardes_pdf_outline_destination_kind;
+
+/*
+ * One pre-order depth-first row. Offsets address the result's byte arena;
+ * title_present distinguishes a missing title from a present empty title.
+ * Internal page numbers are zero-based. has_x/has_y preserve MuPDF's NAN
+ * sentinel for viewing coordinates that the outline destination omits.
+ */
+typedef struct pardes_pdf_outline_item {
+ size_t title_offset;
+ size_t title_len;
+ size_t uri_offset;
+ size_t uri_len;
+ unsigned int depth;
+ int page;
+ float x;
+ float y;
+ unsigned char title_present;
+ unsigned char has_x;
+ unsigned char has_y;
+ unsigned char is_open;
+ unsigned char flags;
+ unsigned char r;
+ unsigned char g;
+ unsigned char b;
+ int destination_kind;
+} pardes_pdf_outline_item;
+
+typedef struct pardes_pdf_outline_result {
+ void *handle;
+ const pardes_pdf_outline_item *items;
+ size_t item_count;
+ const unsigned char *bytes;
+ size_t bytes_len;
+} pardes_pdf_outline_result;
+
+/* URI borrows the current page's lazily loaded link list. Copy it before any
+ * other document operation. A NULL URI means the point has no usable link. */
+typedef struct pardes_pdf_link {
+ const unsigned char *uri;
+ size_t uri_len;
+ pardes_pdf_quad quad;
+ int destination_kind;
+ int page;
+ float x;
+ float y;
+ unsigned char has_x;
+ unsigned char has_y;
+} pardes_pdf_link;
+
+enum {
+ PARDES_PDF_OK = 0,
+ PARDES_PDF_ERROR = -1,
+ PARDES_PDF_LIMIT_EXCEEDED = -2,
+ /* A render stopped early through its cookie (pardes_pdf_set_cookie). */
+ PARDES_PDF_ABORTED = -3,
+
+ /* Per-document MuPDF eviction cache; render buffers are separate. */
+ PARDES_PDF_STORE_LIMIT_BYTES = 64 * 1024 * 1024,
+
+ /*
+ * Search grows geometrically up to this aggregate count and then fails
+ * atomically with PARDES_PDF_LIMIT_EXCEEDED; it never returns a silently
+ * truncated result. Selection uses one extra private probe slot so an
+ * exact-at-the-limit result remains distinguishable from truncation.
+ */
+ PARDES_PDF_MAX_RESULT_QUADS = 65536,
+
+ /* Outline conversion is atomic: crossing any bound returns no rows. */
+ PARDES_PDF_MAX_OUTLINE_ITEMS = 8192,
+ PARDES_PDF_MAX_OUTLINE_DEPTH = 64,
+ PARDES_PDF_MAX_OUTLINE_BYTES = 4 * 1024 * 1024,
+ PARDES_PDF_MAX_LINK_URI_BYTES = 64 * 1024,
+
+ /* No page raster is taller than this, whatever it is shown at. */
+ PARDES_PDF_MAX_RASTER_ROWS = 1 << 20
+};
+
+pardes_pdf_document *pardes_pdf_open_memory(const unsigned char *bytes, size_t length, int *page_count);
+void pardes_pdf_close(pardes_pdf_document *document);
+/* The bytes a document was opened from (its own copy, a lane's its base's),
+ * for as long as it is open. */
+const unsigned char *pardes_pdf_bytes(pardes_pdf_document *document, size_t *length);
+
+/*
+ * A render lane: a context cloned from `base`'s (fz_clone_context: the store,
+ * the allocator and the locks shared) and a document of its OWN, opened from
+ * the bytes `base` holds (the fz_buffer shared, read only). MuPDF allows one
+ * thread at a time in a context and in a document; a lane is used by one
+ * thread at a time and never shares either with `base` or another lane, so
+ * lanes render while `base` serves the UI thread. Clone on the thread that
+ * owns `base` (the clone reads its context); `pardes_pdf_lane_open` then runs
+ * on the lane's thread. Close every lane before `base`. NULL: no lane (out of
+ * memory).
+ */
+pardes_pdf_document *pardes_pdf_lane_clone(pardes_pdf_document *base);
+int pardes_pdf_lane_open(pardes_pdf_document *lane);
+
+/* Mirrors fz_cookie (checked in the bridge): set `abort` nonzero from any
+ * thread and a render running under it stops at its next operator. */
+typedef struct pardes_pdf_cookie {
+ int abort;
+ int progress;
+ size_t progress_max;
+ int errors;
+ int incomplete;
+} pardes_pdf_cookie;
+
+/* The cookie the document's renders run under (NULL: none), until set again. */
+void pardes_pdf_set_cookie(pardes_pdf_document *document, pardes_pdf_cookie *cookie);
+
+/* Page dimensions in PDF points after crop/rotation, without rasterizing. */
+int pardes_pdf_get_page_size(
+ pardes_pdf_document *document,
+ int page,
+ pardes_pdf_page_size *out
+);
+
+/*
+ * Start at dpi, raise the uniform scale until both optional minimum pixel
+ * dimensions are met, then clamp the page's width to max_dimension, and its
+ * height too unless that would draw it smaller than the optional display size
+ * (the width or height it is shown at): a tall page is then as tall as it is
+ * shown, and its owner renders it in bands. Every function below takes the
+ * same request and computes the same raster from it.
+ * Measuring may populate the page cache, but never advances adaptive display
+ * list promotion; only a successful render_into does that.
+ */
+int pardes_pdf_measure_render(
+ pardes_pdf_document *document,
+ int page,
+ const pardes_pdf_request *request,
+ pardes_pdf_raster_layout *out
+);
+
+/*
+ * Rasterize one horizontal BAND of a page — rows [band_y, band_y+band_height)
+ * of the raster `pardes_pdf_measure_render` describes — directly into an
+ * exactly-sized caller-owned packed RGBA buffer, `stride * band_height` bytes.
+ * A full page is the band `(0, height)`.
+ *
+ * MuPDF wraps but never owns or frees samples. Every successful pixel is
+ * opaque unless transparent_paper is nonzero. That mode preserves content
+ * coverage and returns straight-alpha RGBA over an unpainted page.
+ * The CTM does not depend on the band, so a band is a clip of the same
+ * rendering -- but not a bit-exact one: its edge rows and resampled images can
+ * differ from the whole page's (see pardes_pdf_render_into).
+ */
+int pardes_pdf_render_into(
+ pardes_pdf_document *document,
+ int page,
+ const pardes_pdf_request *request,
+ const pardes_pdf_highlight *highlights,
+ size_t highlight_count,
+ unsigned char *samples,
+ size_t samples_len,
+ int width,
+ int height,
+ int stride,
+ int band_y,
+ int band_height,
+ int transparent_paper
+);
+
+/*
+ * The highlight pass of `pardes_pdf_render_into` alone, over caller-supplied
+ * rows of that page's opaque raster: render_into(h) == paint(render_into({}), h)
+ * row for row, because a render draws its highlights over the finished page.
+ */
+int pardes_pdf_paint_highlights(
+ pardes_pdf_document *document,
+ int page,
+ const pardes_pdf_request *request,
+ const pardes_pdf_highlight *highlights,
+ size_t highlight_count,
+ unsigned char *samples,
+ size_t samples_len,
+ int width,
+ int height,
+ int stride,
+ int band_y,
+ int band_height
+);
+
+/*
+ * The raster rows [*row_start, *row_end) that painting `highlights` can touch
+ * under the same request, in the coordinates `pardes_pdf_render_into` bands
+ * use. An empty set (or only transparent ones) yields start == end == 0.
+ */
+int pardes_pdf_highlight_rows(
+ pardes_pdf_document *document,
+ int page,
+ const pardes_pdf_request *request,
+ const pardes_pdf_highlight *highlights,
+ size_t highlight_count,
+ int *row_start,
+ int *row_end
+);
+
+int pardes_pdf_page_text(
+ pardes_pdf_document *document,
+ int page,
+ pardes_pdf_text *out
+);
+void pardes_pdf_drop_text(pardes_pdf_document *document, void *buffer);
+
+/* Case-insensitive, single-page search using MuPDF 1.27's iterative API. */
+int pardes_pdf_search_page(
+ pardes_pdf_document *document,
+ int page,
+ const char *needle,
+ pardes_pdf_search_result *out
+);
+void pardes_pdf_drop_search_result(pardes_pdf_document *document, void *result);
+
+/* Word-snap two normalized points and return oriented highlight quads. */
+int pardes_pdf_select(
+ pardes_pdf_document *document,
+ int page,
+ pardes_pdf_point start,
+ pardes_pdf_point end,
+ pardes_pdf_selection *out
+);
+void pardes_pdf_drop_selection(pardes_pdf_document *document, void *selection);
+
+/* Pure/no-throw oriented-quad hit test in normalized page space. */
+int pardes_pdf_point_inside_quad(
+ pardes_pdf_point point,
+ pardes_pdf_quad quad
+);
+
+/* The input endpoints are normally the snapped points returned above. */
+int pardes_pdf_copy_selection(
+ pardes_pdf_document *document,
+ int page,
+ pardes_pdf_point start,
+ pardes_pdf_point end,
+ pardes_pdf_owned_text *out
+);
+void pardes_pdf_drop_owned_text(pardes_pdf_document *document, void *text);
+
+/*
+ * Flatten fz_load_outline's tree in stable document-order DFS. The borrowed
+ * table and byte arena remain valid until drop_outline_result.
+ */
+int pardes_pdf_load_outline(
+ pardes_pdf_document *document,
+ pardes_pdf_outline_result *out
+);
+void pardes_pdf_drop_outline_result(
+ pardes_pdf_document *document,
+ void *outline
+);
+
+int pardes_pdf_link_at(
+ pardes_pdf_document *document,
+ int page_number,
+ pardes_pdf_point point,
+ pardes_pdf_link *out
+);
+int pardes_pdf_copy_rectangle(
+ pardes_pdf_document *document,
+ int page_number,
+ pardes_pdf_quad quad,
+ pardes_pdf_owned_text *out
+);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif