@reekon-tools/react-native-pdf-canvas 0.1.1 → 0.2.0

package/dist/types.d.ts

@@ -66,10 +66,10 @@ export declare class PdfError extends Error {
     });
 }
 /**
- * Byte order of a raster. The three backends produce different orderings and
- * the descriptor travels with the bytes rather than being assumed:
- * PDFium emits BGRA natively (or RGBA with FPDF_REVERSE_BYTE_ORDER), Android
- * Bitmap ARGB_8888 is RGBA in memory, CGBitmapContext is configured explicitly.
+ * Byte order of a raster. The descriptor travels with the bytes rather than
+ * being assumed: PDFium emits BGRA natively and RGBA with
+ * `FPDF_REVERSE_BYTE_ORDER`, and every backend this package ships asks for the
+ * latter — but a backend that did not would still be describable.
  */
 export type PixelFormat = 'rgba8888' | 'bgra8888';
 /**
@@ -82,22 +82,22 @@ export type PixelFormat = 'rgba8888' | 'bgra8888';
  * therefore worse.
  *
  * `'premultiplied'` — each channel is already scaled by alpha, so a 62%-covered
- * white edge is stored `[158, 158, 158, 158]`. Android's `Bitmap` ARGB_8888 is
- * this by default (`isPremultiplied()` is true unless a caller opts out) and so
- * is a `CGBitmapContext` created `kCGImageAlphaPremultipliedFirst`.
+ * white edge is stored `[158, 158, 158, 158]`. Android's `Bitmap` ARGB_8888 and
+ * a `CGBitmapContext` are both this, which is what the two retired native cores
+ * produced.
  *
  * `'straight'` — the channels carry the colour and alpha carries the coverage
  * independently, so the same edge is stored `[255, 255, 255, 158]`. MEASURED:
  * PDFium reads `[255, 255, 255, 157]` and pdf.js `[255, 255, 255, 160]` for an
  * antialiased opaque-white edge over a transparent page; premultiplied would
- * have been `~[157, 157, 157, 157]`. A canvas `getImageData` buffer is likewise
- * straight (a 50% grey patch reads `[128, 128, 128, 128]`).
+ * have been `~[157, 157, 157, 157]`. Every backend this package ships is PDFium
+ * and declares `'straight'`; the fake declares what it writes.
  *
- * NOT DEFAULTABLE, on purpose. Two of the three engines this package knows about
- * emit `'straight'` and one emits `'premultiplied'`, so there is no default that
- * is right more often than it is wrong — and a default is exactly how a global
- * `AlphaType.Premul` constant survived in `ingest.ts` until the first backend
- * that renders `background: 'transparent'` would have been silently wrong.
+ * NOT DEFAULTABLE, on purpose, even now that the shipped answers agree. A
+ * default is exactly how a global `AlphaType.Premul` constant survived in
+ * `ingest.ts` until the first backend that rendered `background: 'transparent'`
+ * would have been silently wrong, and a host-injected backend can still be
+ * either.
  *
  * INVISIBLE UNDER `background: 'white'`. A fully opaque pixel is byte-identical
  * in both encodings, which is why this can be stated wrongly for a long time
@@ -209,12 +209,14 @@ export interface RasterRequest {
     /** Device pixels per PDF point. */
     scale: number;
     /**
-     * Whether PDF-embedded annotations are drawn into the raster.
+     * Whether PDF-embedded annotations — and form fields, which are widget
+     * annotations — are drawn into the raster.
      *
-     * TRUE for file rasters (thumbnails, print) — that is what the outgoing
-     * react-native-pdf-thumbnail did via PDFKit, and the app depends on it.
-     * FALSE for tiles, because the Skia layer draws the app's own annotations and
-     * they would double-draw.
+     * TRUE by default everywhere: file rasters (thumbnails, print) and the
+     * layer's tiles alike, so a page looks as it does in any other viewer. FALSE
+     * is for a host that imports the PDF's annotations into its own layer and
+     * would otherwise draw each one twice (`UsePdfLayerOptions.annotations`).
+     * Every shipped backend is PDFium and honours both values identically.
      */
     annotations: boolean;
     background: 'white' | 'transparent';
@@ -230,31 +232,23 @@ export interface RasterizerCapabilities {
     /**
      * How many `render` calls this backend can usefully have in flight at once.
      *
-     * A PROPERTY OF THE BACKEND, never a constant in the controller. Android's
-     * ceiling is the `PdfRendererPool` size — each slot is one more `PdfRenderer`
-     * on its own dup'd file descriptor, and a request beyond that blocks on the
-     * pool's queue rather than doing anything. A backend with one document handle
-     * and no pool declares 1 and is scheduled exactly as it is today.
+     * A PROPERTY OF THE BACKEND, never a constant in the controller. OPTIONAL,
+     * DEFAULTING TO 1, and that default is the safe one: an unaware backend keeps
+     * the strictly-sequential behaviour it was written against. The controller
+     * reads it as `min(bound, plan.items.length)`.
      *
-     * OPTIONAL, DEFAULTING TO 1, and that default is the safe one: an unaware
-     * backend keeps the strictly-sequential behaviour it was written against. The
-     * controller reads it as `min(bound, plan.items.length)`.
+     * EVERY SHIPPED BACKEND DECLARES 1, because PDFium is not thread-safe — not
+     * across documents, not across threads — and each backend serialises every
+     * call behind one lock. It was measured before it was a rule: on an LG V60
+     * (Snapdragon 865) the platform `PdfRenderer` — PDFium behind AOSP's own
+     * lock — ran every lane count above one SLOWER on real drawings, because the
+     * lock convoyed. What buys responsiveness instead is cancellation: the native
+     * core stops a superseded tile mid-render, so a stale render never holds the
+     * lock for longer than one progressive batch.
      *
-     * IT IS NOT A PROMISE OF SPEEDUP, AND ON ANDROID IT IS A PROMISE OF THE
-     * OPPOSITE. Measured on an LG V60 (Snapdragon 865, API 33): AOSP serialises
-     * `PdfRenderer` behind a process-wide PDFium lock, so `openPage` throughput is
-     * FLAT at 0.084 / 0.073 / 0.074 ops/ms across 1 / 2 / 4 threads while an
-     * identical pure-Java workload scales 2.8x — and the lock CONVOYS, so
-     * contending for it makes each call slower rather than merely unparallel. The
-     * Android backend therefore declares 1. It used to declare 2 to PIPELINE its
-     * base64 decode against the next tile's native work; the JSI transport deleted
-     * that decode, and re-measuring on the JSI path put every lane count above 1
-     * behind it on real documents. See `AndroidRasterizerOptions.poolSize` for the
-     * numbers.
-     *
-     * A backend whose rasterizing genuinely parallelises should still declare it.
-     * The lane machinery is not Android-specific and the controller has no opinion;
-     * this field is where a backend states what it can actually do.
+     * A host-injected backend whose rasterizing genuinely parallelises should
+     * still declare it. The lane machinery is engine-agnostic and the controller
+     * has no opinion; this field is where a backend states what it can do.
      */
     maxConcurrentRenders?: number;
     /**