Render appearance stream

Author: bobsingor

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

@@ -45,6 +45,7 @@ import {
   CompoundTask,
   ImageDataLike,
   IPdfiumExecutor,
+  AnnotationAppearanceMap,
 } from '@embedpdf/models';
 import { WorkerTaskQueue, Priority } from './task-queue';
 import type { ImageDataConverter } from '../converters/types';
@@ -337,6 +338,14 @@ export class PdfEngine<T = Blob> implements IPdfEngine<T> {
     );
   }
 
+  renderPageAnnotationsRaw(
+    doc: PdfDocumentObject,
+    page: PdfPageObject,
+    options?: PdfRenderPageAnnotationOptions,
+  ): PdfTask<AnnotationAppearanceMap> {
+    return this.executor.renderPageAnnotationsRaw(doc, page, options);
+  }
+
   /**
    * Helper to render and encode in two stages with priority queue
    */

packages/engines/src/lib/orchestrator/remote-executor.ts

@@ -37,6 +37,7 @@ import {
   serializeLogger,
   IPdfiumExecutor,
   ImageDataLike,
+  AnnotationAppearanceMap,
 } from '@embedpdf/models';
 import type { WorkerRequest, WorkerResponse } from './pdfium-native-runner';
 import type { FontFallbackConfig } from '../pdfium/font-fallback';
@@ -80,6 +81,7 @@ type MessageType =
   | 'renderPageRect'
   | 'renderThumbnailRaw'
   | 'renderPageAnnotationRaw'
+  | 'renderPageAnnotationsRaw'
   | 'getPageAnnotations'
   | 'getPageAnnotationsRaw'
   | 'createPageAnnotation'
@@ -349,6 +351,14 @@ export class RemoteExecutor implements IPdfiumExecutor {
     return this.send<ImageDataLike>('renderPageAnnotationRaw', [doc, page, annotation, options]);
   }
 
+  renderPageAnnotationsRaw(
+    doc: PdfDocumentObject,
+    page: PdfPageObject,
+    options?: PdfRenderPageAnnotationOptions,
+  ): PdfTask<AnnotationAppearanceMap> {
+    return this.send<AnnotationAppearanceMap>('renderPageAnnotationsRaw', [doc, page, options]);
+  }
+
   getPageAnnotationsRaw(
     doc: PdfDocumentObject,
     page: PdfPageObject,

packages/engines/src/lib/pdfium/engine.ts

@@ -113,6 +113,12 @@ import {
   PdfTrappedStatus,
   PdfStampFit,
   PdfAddAttachmentParams,
+  AnnotationAppearanceMap,
+  AnnotationAppearances,
+  AnnotationAppearanceImage,
+  AP_MODE_NORMAL,
+  AP_MODE_ROLLOVER,
+  AP_MODE_DOWN,
 } from '@embedpdf/models';
 import { computeFormDrawParams, isValidCustomKey, readArrayBuffer, readString } from './helper';
 import { WrappedPdfiumModule } from '@embedpdf/pdfium';
@@ -4147,6 +4153,12 @@ export class PdfiumNative implements IPdfiumExecutor {
     // Post-process: reverse-rotate vertices for vertex types that have rotation metadata
     if (annotation) {
       annotation = this.reverseRotateAnnotationOnLoad(annotation);
+
+      // Populate available appearance stream modes bitmask
+      const apModes = this.pdfiumModule.EPDFAnnot_GetAvailableAppearanceModes(annotationPtr);
+      if (apModes) {
+        annotation.appearanceModes = apModes;
+      }
     }
 
     return annotation;
@@ -7491,6 +7503,194 @@ export class PdfiumNative implements IPdfiumExecutor {
     return task;
   }
 
+  /**
+   * Batch-render all annotation appearance streams for a page in one call.
+   * Returns a map of annotation ID -> rendered appearances (Normal/Rollover/Down).
+   * Skips annotations that have rotation + unrotatedRect (EmbedPDF-rotated)
+   * and annotations without any appearance stream.
+   *
+   * @public
+   */
+  renderPageAnnotationsRaw(
+    doc: PdfDocumentObject,
+    page: PdfPageObject,
+    options?: PdfRenderPageAnnotationOptions,
+  ): PdfTask<AnnotationAppearanceMap> {
+    const { scaleFactor = 1, rotation = Rotation.Degree0, dpr = 1 } = options ?? {};
+
+    this.logger.debug(LOG_SOURCE, LOG_CATEGORY, 'renderPageAnnotationsRaw', doc, page, options);
+    this.logger.perf(
+      LOG_SOURCE,
+      LOG_CATEGORY,
+      'RenderPageAnnotationsRaw',
+      'Begin',
+      `${doc.id}-${page.index}`,
+    );
+
+    const ctx = this.cache.getContext(doc.id);
+    if (!ctx) {
+      this.logger.perf(
+        LOG_SOURCE,
+        LOG_CATEGORY,
+        'RenderPageAnnotationsRaw',
+        'End',
+        `${doc.id}-${page.index}`,
+      );
+      return PdfTaskHelper.reject({
+        code: PdfErrorCode.DocNotOpen,
+        message: 'document does not open',
+      });
+    }
+
+    const pageCtx = ctx.acquirePage(page.index);
+    const result: AnnotationAppearanceMap = {};
+    const finalScale = Math.max(0.01, scaleFactor * dpr);
+    const annotCount = this.pdfiumModule.FPDFPage_GetAnnotCount(pageCtx.pagePtr);
+
+    for (let i = 0; i < annotCount; i++) {
+      const annotPtr = this.pdfiumModule.FPDFPage_GetAnnot(pageCtx.pagePtr, i);
+      if (!annotPtr) continue;
+
+      try {
+        // Read annotation NM (id)
+        const nm = this.getAnnotString(annotPtr, 'NM');
+        if (!nm) continue;
+
+        // Skip EmbedPDF-rotated annotations (have rotation + unrotatedRect)
+        const extRotation = this.getAnnotExtendedRotation(annotPtr);
+        if (extRotation !== 0) {
+          const unrotatedRaw = this.readAnnotUnrotatedRect(annotPtr);
+          if (unrotatedRaw) continue;
+        }
+
+        // Detect available AP modes
+        const apModes = this.pdfiumModule.EPDFAnnot_GetAvailableAppearanceModes(annotPtr);
+        if (!apModes) continue;
+
+        const appearances: AnnotationAppearances = {};
+
+        // Render each available mode
+        const modesToRender: Array<{
+          bit: number;
+          mode: AppearanceMode;
+          key: keyof AnnotationAppearances;
+        }> = [
+          { bit: AP_MODE_NORMAL, mode: AppearanceMode.Normal, key: 'normal' },
+          { bit: AP_MODE_ROLLOVER, mode: AppearanceMode.Rollover, key: 'rollover' },
+          { bit: AP_MODE_DOWN, mode: AppearanceMode.Down, key: 'down' },
+        ];
+
+        for (const { bit, mode, key } of modesToRender) {
+          if (!(apModes & bit)) continue;
+
+          const rendered = this.renderSingleAnnotAppearance(
+            doc,
+            page,
+            pageCtx,
+            annotPtr,
+            mode,
+            rotation,
+            finalScale,
+          );
+          if (rendered) {
+            appearances[key] = rendered;
+          }
+        }
+
+        if (appearances.normal || appearances.rollover || appearances.down) {
+          result[nm] = appearances;
+        }
+      } finally {
+        this.pdfiumModule.FPDFPage_CloseAnnot(annotPtr);
+      }
+    }
+
+    pageCtx.release();
+    this.logger.perf(
+      LOG_SOURCE,
+      LOG_CATEGORY,
+      'RenderPageAnnotationsRaw',
+      'End',
+      `${doc.id}-${page.index}`,
+    );
+
+    const task = new Task<AnnotationAppearanceMap, PdfErrorReason>();
+    task.resolve(result);
+    return task;
+  }
+
+  /**
+   * Render a single annotation's appearance for a given mode.
+   * Returns the image data and rect, or null on failure.
+   * @private
+   */
+  private renderSingleAnnotAppearance(
+    doc: PdfDocumentObject,
+    page: PdfPageObject,
+    pageCtx: PageContext,
+    annotPtr: number,
+    mode: AppearanceMode,
+    rotation: Rotation,
+    finalScale: number,
+  ): AnnotationAppearanceImage | null {
+    // Read rect using EPDFAnnot_GetRect (normalized) and convert to device coords
+    const pageRect = this.readPageAnnoRect(annotPtr);
+    const annotRect = this.convertPageRectToDeviceRect(doc, page, pageRect);
+
+    const rect = toIntRect(annotRect);
+    const devRect = toIntRect(transformRect(page.size, rect, rotation, finalScale));
+    const wDev = Math.max(1, devRect.size.width);
+    const hDev = Math.max(1, devRect.size.height);
+    const stride = wDev * 4;
+    const bytes = stride * hDev;
+
+    const heapPtr = this.memoryManager.malloc(bytes);
+    const bitmapPtr = this.pdfiumModule.FPDFBitmap_CreateEx(
+      wDev,
+      hDev,
+      BitmapFormat.Bitmap_BGRA,
+      heapPtr,
+      stride,
+    );
+    this.pdfiumModule.FPDFBitmap_FillRect(bitmapPtr, 0, 0, wDev, hDev, 0x00000000);
+
+    const M = buildUserToDeviceMatrix(rect, rotation, wDev, hDev);
+    const mPtr = this.memoryManager.malloc(6 * 4);
+    const mView = new Float32Array(this.pdfiumModule.pdfium.HEAPF32.buffer, mPtr, 6);
+    mView.set([M.a, M.b, M.c, M.d, M.e, M.f]);
+
+    const FLAGS = RenderFlag.REVERSE_BYTE_ORDER;
+    let ok = false;
+    try {
+      ok = !!this.pdfiumModule.EPDF_RenderAnnotBitmap(
+        bitmapPtr,
+        pageCtx.pagePtr,
+        annotPtr,
+        mode,
+        mPtr,
+        FLAGS,
+      );
+    } finally {
+      this.memoryManager.free(mPtr);
+      this.pdfiumModule.FPDFBitmap_Destroy(bitmapPtr);
+    }
+
+    if (!ok) {
+      this.memoryManager.free(heapPtr);
+      return null;
+    }
+
+    const data = this.pdfiumModule.pdfium.HEAPU8.subarray(heapPtr, heapPtr + bytes);
+    const imageData: ImageDataLike = {
+      data: new Uint8ClampedArray(data),
+      width: wDev,
+      height: hDev,
+    };
+    this.memoryManager.free(heapPtr);
+
+    return { data: imageData, rect: annotRect };
+  }
+
   private renderRectEncoded(
     doc: PdfDocumentObject,
     page: PdfPageObject,

packages/engines/src/lib/webworker/engine.ts

@@ -39,6 +39,7 @@ import {
   PdfPrintOptions,
   PdfBookmarkObject,
   PdfAddAttachmentParams,
+  AnnotationAppearanceMap,
 } from '@embedpdf/models';
 import { ExecuteRequest, Response, SpecificExecuteRequest } from './runner';
 
@@ -451,6 +452,25 @@ export class WebWorkerEngine implements PdfEngine {
     return task;
   }
 
+  renderPageAnnotationsRaw(
+    doc: PdfDocumentObject,
+    page: PdfPageObject,
+    options?: PdfRenderPageAnnotationOptions,
+  ) {
+    this.logger.debug(LOG_SOURCE, LOG_CATEGORY, 'renderPageAnnotationsRaw', doc, page, options);
+    const requestId = this.generateRequestId(doc.id);
+    const task = new WorkerTask<AnnotationAppearanceMap>(this.worker, requestId);
+
+    const request: ExecuteRequest = createRequest(requestId, 'renderPageAnnotationsRaw', [
+      doc,
+      page,
+      options,
+    ]);
+    this.proxy(task, request);
+
+    return task;
+  }
+
   /**
    * {@inheritDoc @embedpdf/models!PdfEngine.getAllAnnotations}
    *

packages/engines/src/lib/webworker/runner.ts

@@ -291,6 +291,9 @@ export class EngineRunner {
       case 'renderPageAnnotation':
         task = engine.renderPageAnnotation!(...args);
         break;
+      case 'renderPageAnnotationsRaw':
+        task = engine.renderPageAnnotationsRaw!(...args);
+        break;
       case 'renderThumbnail':
         task = engine.renderThumbnail!(...args);
         break;