path: root/src/pdf_bridge.h

#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 struct pardes_pdf_raster_layout {
    int width;
    int height;
    int stride;
    size_t samples_len;
} pardes_pdf_raster_layout;

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;

enum {
    PARDES_PDF_OK = 0,
    PARDES_PDF_ERROR = -1,
    PARDES_PDF_LIMIT_EXCEEDED = -2,

    /* 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_document *pardes_pdf_open(const char *path, int *page_count);
void pardes_pdf_close(pardes_pdf_document *document);

/* 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 longest side to max_dimension.
 * 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,
    int dpi,
    int minimum_width,
    int minimum_height,
    int max_dimension,
    pardes_pdf_raster_layout *out
);

/*
 * Rasterize directly into an exactly-sized caller-owned packed RGBA buffer.
 * MuPDF wraps but never owns or frees samples. Every successful pixel is
 * opaque, including the caller-supplied highlights composited onto the page.
 */
int pardes_pdf_render_into(
    pardes_pdf_document *document,
    int page,
    int dpi,
    int minimum_width,
    int minimum_height,
    int max_dimension,
    const pardes_pdf_highlight *highlights,
    size_t highlight_count,
    unsigned char *samples,
    size_t samples_len,
    int width,
    int height,
    int stride
);

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
);

#ifdef __cplusplus
}
#endif

#endif