Merge pull request #557 from jonashaag/feature/bmp-encoding

Use BMP image encoding between worker and main thread

Author: bobsingor

.changeset/bmp-encoding.md

@@ -0,0 +1,13 @@
+---
+'@embedpdf/models': patch
+'@embedpdf/engines': patch
+'@embedpdf/plugin-render': patch
+---
+
+Add BMP encoding support as an optional image format
+
+BMP encoding bypasses canvas.toBlob() entirely by prepending a 66-byte header to the raw RGBA pixel data. This eliminates the dominant rendering bottleneck — in benchmarks, encoding dropped from ~76ms average (PNG via canvas.toBlob) to <1ms, reducing total tile render time by ~60%.
+
+The BMP uses BI_BITFIELDS with channel masks matching PDFium's RGBA output byte order, so no per-pixel conversion is needed. Top-down row order avoids row flipping. The result is a valid BMP that all modern browsers decode natively in `<img>` elements.
+
+Users who want to opt into the faster BMP path can set `defaultImageType: 'image/bmp'` in the render plugin config, while PNG remains the default output format.

packages/engines/src/lib/converters/browser.ts

@@ -1,6 +1,7 @@
 import type { ImageConversionTypes } from '@embedpdf/models';
 import type { ImageDataConverter, LazyImageData } from './types';
 import { ImageEncoderWorkerPool } from '../image-encoder';
+import { rgbaToBmpBlob } from '../image-encoder/bmp';
 
 // ============================================================================
 // Error Classes
@@ -25,9 +26,16 @@ export class ImageConverterError extends Error {
  */
 export const browserImageDataToBlobConverter: ImageDataConverter<Blob> = (
   getImageData: LazyImageData,
-  imageType: ImageConversionTypes = 'image/webp',
+  imageType: ImageConversionTypes = 'image/png',
   quality?: number,
 ): Promise<Blob> => {
+  const pdfImage = getImageData();
+
+  // Fast path: BMP needs no canvas — just a header prepended to raw pixels
+  if (imageType === 'image/bmp') {
+    return Promise.resolve(rgbaToBmpBlob(pdfImage.data, pdfImage.width, pdfImage.height));
+  }
+
   if (typeof document === 'undefined') {
     return Promise.reject(
       new ImageConverterError(
@@ -36,7 +44,6 @@ export const browserImageDataToBlobConverter: ImageDataConverter<Blob> = (
     );
   }
 
-  const pdfImage = getImageData();
   const imageData = new ImageData(pdfImage.data, pdfImage.width, pdfImage.height);
 
   return new Promise((resolve, reject) => {
@@ -73,11 +80,16 @@ export function createWorkerPoolImageConverter(
 ): ImageDataConverter<Blob> {
   const converter: ImageDataConverter<Blob> = (
     getImageData: LazyImageData,
-    imageType: ImageConversionTypes = 'image/webp',
+    imageType: ImageConversionTypes = 'image/png',
     quality?: number,
   ): Promise<Blob> => {
     const pdfImage = getImageData();
 
+    // Fast path: BMP needs no worker round-trip
+    if (imageType === 'image/bmp') {
+      return Promise.resolve(rgbaToBmpBlob(pdfImage.data, pdfImage.width, pdfImage.height));
+    }
+
     // Copy the data since we'll transfer it to another worker
     const dataCopy = new Uint8ClampedArray(pdfImage.data);
 
@@ -113,12 +125,18 @@ export function createHybridImageConverter(
 ): ImageDataConverter<Blob> {
   const converter: ImageDataConverter<Blob> = async (
     getImageData: LazyImageData,
-    imageType: ImageConversionTypes = 'image/webp',
+    imageType: ImageConversionTypes = 'image/png',
     quality?: number,
   ): Promise<Blob> => {
+    const pdfImage = getImageData();
+
+    // Fast path: BMP needs no worker round-trip
+    if (imageType === 'image/bmp') {
+      return rgbaToBmpBlob(pdfImage.data, pdfImage.width, pdfImage.height);
+    }
+
     try {
       // Try worker pool encoding first (OffscreenCanvas in worker)
-      const pdfImage = getImageData();
       const dataCopy = new Uint8ClampedArray(pdfImage.data);
 
       return await workerPool.encode(

packages/engines/src/lib/image-encoder/bmp.ts

@@ -0,0 +1,41 @@
+/**
+ * Creates an uncompressed BMP blob from raw RGBA pixel data.
+ *
+ * Uses BI_BITFIELDS with channel masks matching RGBA byte order, so no
+ * per-pixel byte swapping is needed. Top-down row order (negative height)
+ * avoids row flipping. The result is a valid BMP that all modern browsers
+ * can decode natively in `<img>` elements.
+ *
+ * This is dramatically faster than PNG/WebP/JPEG encoding via canvas.toBlob()
+ * because it performs no compression — just a 66-byte header prepended to the
+ * raw pixel buffer.
+ */
+export function rgbaToBmpBlob(rgba: Uint8ClampedArray, width: number, height: number): Blob {
+  const pixels = width * height * 4;
+  const headerLength = 66;
+  const le32 = (v: number) => [v & 0xff, (v >>> 8) & 0xff, (v >>> 16) & 0xff, (v >>> 24) & 0xff];
+
+  // prettier-ignore
+  const header = new Uint8Array([
+    0x42, 0x4D,                     // 'BM' signature
+    ...le32(headerLength + pixels), // file size
+    0, 0, 0, 0,                     // reserved
+    headerLength, 0, 0, 0,          // pixel data offset
+    40, 0, 0, 0,                    // DIB header size
+    ...le32(width),                 // width
+    ...le32(-height),               // height (negative = top-down)
+    1, 0,                           // color planes
+    32, 0,                          // bits per pixel
+    3, 0, 0, 0,                     // compression = BI_BITFIELDS
+    ...le32(pixels),                // image data size
+    0, 0, 0, 0,                     // h resolution
+    0, 0, 0, 0,                     // v resolution
+    0, 0, 0, 0,                     // colors in palette
+    0, 0, 0, 0,                     // important colors
+    0xFF, 0, 0, 0,                  // R channel mask
+    0, 0xFF, 0, 0,                  // G channel mask
+    0, 0, 0xFF, 0,                  // B channel mask
+  ]);
+
+  return new Blob([header, rgba], { type: 'image/bmp' });
+}

packages/engines/src/lib/image-encoder/image-encoder-worker.ts

@@ -3,6 +3,8 @@
  * Offloads OffscreenCanvas.convertToBlob() from the main PDFium worker
  */
 
+import { rgbaToBmpBlob } from './bmp';
+
 export interface EncodeImageRequest {
   id: string;
   type: 'encode';
@@ -12,7 +14,7 @@ export interface EncodeImageRequest {
       width: number;
       height: number;
     };
-    imageType: 'image/png' | 'image/jpeg' | 'image/webp';
+    imageType: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/bmp';
     quality?: number;
   };
 }
@@ -24,13 +26,18 @@ export interface EncodeImageResponse {
 }
 
 /**
- * Encode ImageData to Blob using OffscreenCanvas
+ * Encode ImageData to Blob using OffscreenCanvas (or BMP fast path)
  */
 async function encodeImage(
   imageData: { data: Uint8ClampedArray; width: number; height: number },
-  imageType: 'image/png' | 'image/jpeg' | 'image/webp',
+  imageType: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/bmp',
   quality?: number,
 ): Promise<Blob> {
+  // Fast path: BMP needs no canvas
+  if (imageType === 'image/bmp') {
+    return rgbaToBmpBlob(imageData.data, imageData.width, imageData.height);
+  }
+
   if (typeof OffscreenCanvas === 'undefined') {
     throw new Error('OffscreenCanvas is not available in this worker environment');
   }

packages/engines/src/lib/image-encoder/worker-pool.ts

@@ -114,7 +114,7 @@ export class ImageEncoderWorkerPool {
    */
   encode(
     imageData: { data: Uint8ClampedArray; width: number; height: number },
-    imageType: 'image/png' | 'image/jpeg' | 'image/webp' = 'image/webp',
+    imageType: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/bmp' = 'image/png',
     quality?: number,
   ): Promise<Blob> {
     return new Promise((resolve, reject) => {

packages/engines/src/lib/orchestrator/pdf-engine.ts

@@ -481,7 +481,7 @@ export class PdfEngine<T = Blob> implements IPdfEngine<T> {
     options: any,
     resultTask: Task<T, PdfErrorReason>,
   ): void {
-    const imageType = options?.imageType ?? 'image/webp';
+    const imageType = options?.imageType ?? 'image/png';
     const quality = options?.quality;
 
     // Convert to plain object for encoding
@@ -505,7 +505,7 @@ export class PdfEngine<T = Blob> implements IPdfEngine<T> {
     options: PdfRenderPageAnnotationOptions | undefined,
     resultTask: Task<AnnotationAppearanceMap<T>, PdfErrorReason>,
   ): void {
-    const imageType = options?.imageType ?? 'image/webp';
+    const imageType = options?.imageType ?? 'image/png';
     const quality = options?.imageQuality;
 
     const convertImage = (rawImageData: ImageDataLike): Promise<T> => {

packages/models/src/pdf.ts

@@ -2537,7 +2537,7 @@ export function unionFlags(flags: MatchFlag[]) {
  *
  * @public
  */
-export type ImageConversionTypes = 'image/webp' | 'image/png' | 'image/jpeg';
+export type ImageConversionTypes = 'image/webp' | 'image/png' | 'image/jpeg' | 'image/bmp';
 
 /**
  * Targe for searching

packages/plugin-render/src/lib/types.ts

@@ -21,7 +21,7 @@ export interface RenderPluginConfig extends BasePluginConfig {
   withAnnotations?: boolean;
   /**
    * The image type to use for rendering.
-   * Defaults to `'image/webp'`.
+   * Defaults to `'image/png'`.
    */
   defaultImageType?: ImageConversionTypes;
   /**

packages/plugin-tiling/src/lib/tiling-plugin.ts

@@ -206,6 +206,9 @@ export class TilingPlugin extends BasePlugin<TilingPluginConfig, TilingCapabilit
       options: {
         scaleFactor: options.tile.srcScale,
         dpr: options.dpr,
+        ...(options.imageType || this.config.defaultImageType
+          ? { imageType: options.imageType ?? this.config.defaultImageType }
+          : {}),
       },
     });
 

packages/plugin-tiling/src/lib/types.ts

@@ -1,11 +1,23 @@
 import { BasePluginConfig, EventHook } from '@embedpdf/core';
-import { PdfErrorReason, PdfPageObject, Rect, Rotation, Task } from '@embedpdf/models';
+import {
+  ImageConversionTypes,
+  PdfErrorReason,
+  PdfPageObject,
+  Rect,
+  Rotation,
+  Task,
+} from '@embedpdf/models';
 import { PageVisibilityMetrics } from '@embedpdf/plugin-scroll';
 
 export interface TilingPluginConfig extends BasePluginConfig {
   tileSize: number;
   overlapPx: number;
   extraRings: number;
+  /**
+   * Optional image type override for tile rendering.
+   * When omitted, tile rendering falls back to the render plugin defaults.
+   */
+  defaultImageType?: ImageConversionTypes;
 }
 
 export interface VisibleRect {
@@ -66,4 +78,9 @@ export interface RenderTileOptions {
   pageIndex: number;
   tile: Tile;
   dpr: number;
+  /**
+   * Optional image type override for this tile render.
+   * Falls back to the tiling plugin config, then to the render plugin default.
+   */
+  imageType?: ImageConversionTypes;
 }