StreamPDFStreamPDF
Back to blog

PDF.js Deep Dive from Demo 5: render

October 27, 2026 · StreamPDF Team

PDF.js Deep Dive from Demo 5: render

Introduction

In the previous articles, we obtained the page (PDFPageProxy) and the viewport (PageViewport) one by one, and adjusted the canvas size. Back to the demo from the first article, the final step, lines 20-28:

const renderContext = {
  canvasContext: context,
  viewport,
};
const renderTask = page.render(renderContext);
await renderTask.promise;

render returns a RenderTask object. This article follows this call through the complete render execution flow.

The render call

An object parameter is passed in:

ParameterValueMeaning
canvasContextcontextThe 2d context of the canvas, i.e. the return value of canvas.getContext('2d')
viewportPageViewport { width: 297.5, height: 421, scale: 0.5, rotation: 0 }The viewport object, i.e. the return value of getViewport({ scale: 0.5 }) from the previous article

Based on the definition of PDFPageProxy.render in api.js, the execution flow is as follows.

Lines 1491-1508: Destructure the parameters

render({
  canvasContext,
  canvas = canvasContext.canvas,
  viewport,
  intent = "display",
  annotationMode = AnnotationMode.ENABLE,
  transform = null,
  background = null,
  optionalContentConfigPromise = null,
  annotationCanvasMap = null,
  pageColors = null,
  printAnnotationStorage = null,
  isEditing = false,
  recordImages = false,
  recordOperations = false,
  operationsFilter = null,
}) { ... }

There are 15 parameters in total. The demo only passes 2, and the remaining 13 use default values:

VariableResultLogic
canvascanvas elementIf not passed, take canvasContext.canvas, retrieved from the context
intent"display"Rendering intent: display
annotationMode1 (ENABLE)Render annotations
transformnullAdditional transform matrix
backgroundnullBackground color
optionalContentConfigPromisenullLayer config, default value filled in later
annotationCanvasMapnullAnnotation canvas map
pageColorsnullPage colors (accessibility scenario)
printAnnotationStoragenullAnnotation storage for printing
isEditingfalseWhether in editing mode
recordImagesfalseWhether to record image coordinates
recordOperationsfalseWhether to record drawing operations
operationsFilternullOperation filter

Q: What does the first line this._stats?.time("Overall") do?

A: It is performance measurement. _stats is a StatTimer instance only when pdfBug is enabled. The demo's _stats is null (in Part 3, pdfBug was false when PDFPageProxy was constructed), so the optional chaining short-circuits and this line costs nothing.

Lines 1510-1516: Compute the rendering intent

const intentArgs = this._transport.getRenderingIntent(
  'display', // intent
  1, // annotationMode
  null, // printAnnotationStorage
  false, // isEditing
);
const { renderingIntent, cacheKey } = intentArgs;

getRenderingIntent (view source) contains a set of bit operations (RenderingIntentFlag). Substituting the demo's values:

  • intent is "display" → renderingIntent = 0x02 (DISPLAY)
  • Not PRINT → annotationStorage takes the globally shared AnnotationStorage on the transport
  • annotationMode is ENABLE → no flag bit added
  • isEditing is false, not an opList call → no flag bit added
  • No modifications in the storage → annotationStorage.modifiedIds = { ids: Set(), hash: "" }
  • Destructure ids as modifiedIds, modifiedIdsHash = ""
  • cacheKey = [2, "", ""].join("_") → "2__"

It returns { renderingIntent: 2, cacheKey: "2__", annotationStorageSerializable: { map: null, hash: "", transfer: undefined }, modifiedIds: Set() }.

Q: What is cacheKey for?

A: On the same page object, different rendering intents (display / print / annotations modified...) each maintain an independent set of operator lists and render tasks, stored in the page's _intentStates Map, keyed by cacheKey. As long as the intents differ, the caches never interfere with each other. The demo is a first-time render, so "2__" corresponds to a brand-new intentState.

Lines 1519-1534: Prepare the intentState

this.#pendingCleanup = false;
optionalContentConfigPromise ||= this._transport.getOptionalContentConfig(2);
const intentState = this._intentStates.getOrInsertComputed('2__', makeObj);
const intentPrint = !!(2 & 0x04); // false

Three things happen in sequence:

  1. #pendingCleanup = false: cancel any pending cleanup task, ensuring no memory reclamation happens during rendering;
  2. optionalContentConfigPromise: the document's layer configuration (OCProperties). If the caller didn't pass it, it is fetched from the worker (the transport layer caches it). The layer mechanism will be covered in a separate article;
  3. intentState: the state slot for this rendering intent, created as an empty object on first use.

Lines 1538-1549: First render, start fetching the operator list

if (!intentState.displayReadyCapability) {
  intentState.displayReadyCapability = Promise.withResolvers();
  intentState.operatorList = {
    fnArray: [], // opcode array
    argsArray: [], // argument array
    lastChunk: false, // whether all chunks have been received
    separateAnnots: null,
  };
  this._pumpOperatorList(intentArgs);
}

If displayReadyCapability doesn't exist, it means this intent has never requested an operator list, so the request is initiated immediately.

_pumpOperatorList (view source) establishes a streaming channel with the worker via messageHandler.sendWithStream("GetOperatorList", { pageId: 0, pageIndex: 0, intent: 2, cacheKey: "2__", ... }): the worker parses the page's content stream and pushes drawing instructions (opcodes + arguments) back to the main thread in chunks; each time the main thread receives a chunk, it appends it to operatorList and notifies all render tasks under this intentState that "new instructions are available to draw." Both the streaming communication and the worker-side instruction parsing will be covered in a separate article.

Q: Why streaming instead of returning everything at once?

A: A large PDF page can have tens of thousands of drawing operators. Streaming offers two benefits: (1) draw while receiving, so first paint is faster — the worker pushes each chunk to the main thread as soon as it is generated; (2) partial cleanup on cancellation or failure. Correspondingly, right after the worker finishes parsing the page's content stream + resources (before any operators are generated), it sends back a StartRenderPage message that resolves displayReadyCapability — this is the precondition awaited by the subsequent Promise.all.

Lines 1561-1608: Define the completion callback

const complete = error => { ... };

The complete closure (view source) handles the wrap-up: removing this task from intentState.renderTasks; on error, rejecting the capability and aborting the operator list fetch; on success, resolving the capability. The demo doesn't enable any recording switches, so all related branches are skipped.

Lines 1625-1654: Create the InternalRenderTask

const internalRenderTask = new InternalRenderTask({
  callback: complete,
  params: {
    canvas,
    canvasContext,
    dependencyTracker: null,
    imagesTracker: null,
    viewport,
    transform: null,
    background: null,
  },
  objs: this.objs, // page-level resource container (created in Part 3)
  commonObjs: this.commonObjs, // document-wide shared resource container
  annotationCanvasMap: null,
  operatorList: intentState.operatorList, // shares the same object with the streaming fetch
  pageIndex: 0,
  canvasFactory: this._transport.canvasFactory, // the DOMCanvasFactory from Part 2
  filterFactory: this._transport.filterFactory,
  useRequestAnimationFrame: true, // not printing
  pdfBug: false,
  pageColors: null,
  enableHWA: false,
  operationsFilter: null,
});

(intentState.renderTasks ||= new Set()).add(internalRenderTask);
const renderTask = internalRenderTask.task;

The InternalRenderTask constructor (view source) performs two key actions:

  • this.capability = Promise.withResolvers() — the success/failure of rendering converges here;
  • this.task = new RenderTask(this) — the externally exposed handle, i.e., the final return value of render.

Note that operatorList is passed by reference: InternalRenderTask shares the same list object with the streaming fetch from Step 4, so instructions can be consumed as soon as they arrive.

Q: What is the difference between InternalRenderTask and RenderTask?

A: InternalRenderTask is the executor of rendering. It holds all internal state such as the canvas, operator list, and dependency tracker, and advances drawing frame by frame. RenderTask is merely the handle wrapped around it (view source), exposing only a few members like promise / cancel / onContinue. render returns a RenderTask, while internally it uses internalRenderTask to drive drawing.

Lines 1656-1681: Wait for the preconditions, start drawing

Promise.all([
  intentState.displayReadyCapability.promise, // operator list has received the first displayable content
  optionalContentConfigPromise, // layer config is ready
])
  .then(([transparency, optionalContentConfig]) => {
    if (this.destroyed) {
      complete();
      return;
    }
    if (!(optionalContentConfig.renderingIntent & 2)) {
      throw new Error(
        'Must use the same `intent`-argument when calling the `PDFPageProxy.render` ' +
          'and `PDFDocumentProxy.getOptionalContentConfig` methods.',
      );
    }
    internalRenderTask.initializeGraphics({ transparency, optionalContentConfig });
    internalRenderTask.operatorListChanged();
  })
  .catch(complete);

return renderTask;

Once both preconditions are ready:

  1. destroyed check: the page may have been destroyed while waiting;
  2. The layer config's intent must be compatible with this render's intent, otherwise an error is thrown — layer configs are cached per intent, and mixing them would corrupt layer state;
  3. initializeGraphics (view source): creates the CanvasGraphics (the object that actually executes drawing instructions), and checks that the same canvas must not be used concurrently by two render tasks (#canvasInUse is a WeakSet; reuse throws directly);
  4. operatorListChanged (view source): starts consuming the instructions that have already arrived in operatorList, drawing them onto the canvas one by one.

The drawing details of initializeGraphics and CanvasGraphics are covered in Article 10.

Return value: renderTask

The .then chain above advances asynchronously in the background, while render itself returns renderTask synchronously.

Q: Why doesn't the demo await page.render(renderContext) directly, but instead gets a renderTask first and then awaits renderTask.promise?

A: Because RenderTask is not a thenable. It only has a promise getter and no then method, so await page.render(renderContext) resolves immediately with the object itself — it looks like it waits, but it actually waits for nothing. Rendering continues in the background; if subsequent code depends on "rendering has completed" (for example, exporting the canvas as an image), it may get a canvas that is not finished yet.

const renderTask = page.render(renderContext);
await renderTask.promise; // the signal for render success/failure

At this point, the last line of the demo has finished executing, and the first page is rendered onto the canvas.

Summary

This article followed the demo through the complete render({ canvasContext, viewport }) call:

  1. Destructure 15 parameters; the demo only passes canvasContext and viewport;
  2. getRenderingIntent bit operations: renderingIntent = 2, cacheKey = "2__";
  3. Prepare the intentState and fill in the layer config promise;
  4. First render: establish the GetOperatorList streaming channel, drawing while receiving;
  5. Create the InternalRenderTask and the external handle RenderTask;
  6. Once the preconditions are ready, initializeGraphics + operatorListChanged start the drawing;
  7. renderTask is returned synchronously; the rendering completion signal lives on renderTask.promise.

Looking back at the demo from the first article: getDocument → getPage → getViewport → render, each step merely "initiates" — the real parsing and drawing happens inside the worker thread (pdfManager, GetOperatorList) and the main thread's CanvasGraphics. Starting from the next article, we enter these "heavyweight players."


About me: Creator of StreamPDF, focused on research and development in AI and PDF.

More from PDF.js Deep Dive from Demo