Progressive Rendering and Cancellation

HotPDF can render a loaded page over multiple bounded calls and can stop long-running document operations through a shared caller-owned cancellation token

Progressive page rendering

Session := PDF.BeginLoadedPageProgressiveRender(0, 144);
try
  repeat
    Status := Session.ContinueRender(8, 128);
    Preview.Assign(Session.Bitmap);
  until Status in [prsCompleted, prsCancelled];

  if Status = prsCompleted then
    FinalBitmap := Session.TakeBitmap;
finally
  Session.Free;
end;

ContinueRender accepts a maximum elapsed time in milliseconds, a maximum number of top-level page content operators, or both; zero means unlimited for that budget

The call completes at least one operator before applying a non-zero time budget, so the graphics state is always paused at an operator boundary

Bitmap exposes the live caller-read-only partial bitmap, while TakeBitmap transfers ownership without copying after the session reaches prsCompleted or prsCancelled

ObjectsProcessed and TotalObjects report top-level content operators from every page /Contents stream in source order

Progressive region rendering

Session := PDF.BeginLoadedPageProgressiveRegionRender(
  0, 72, 144, 360, 432, 144);
try
  repeat
    Status := Session.ContinueRender(6, 96);
  until Status in [prsCompleted, prsCancelled];
finally
  Session.Free;
end;

The four region coordinates are PDF user-space points with a lower-left origin and the output bitmap covers exactly that window at the requested DPI

The session reuses the cached display list, retains graphics and text state across calls, and suppresses expensive path, text, image, Form, and shading paints whose conservative bounds do not intersect the ROI

State operators and text advancement still execute in source order, so culling an earlier mark cannot move or recolour a later visible mark

RegionVisiblePaintObjects and RegionCulledPaintObjects expose the display-list selection, while the peak-memory reservation follows the region dimensions instead of the full page

Progressive JPEG scans

When THotPDF.ProgressiveJPEGScanDecoding is true, an eligible progressive DCTDecode image advances by one JPEG scan per bounded ContinueRender call so the live bitmap can show an early coarse preview before the final scan

THotPDF.ProgressiveJPEGMaxScans limits each image to between 1 and 4096 scans, while the document decode-byte budget also covers the aligned output bitmap

THPDFLoadedPageRenderSession.ProgressiveJPEGScansDecoded and THPDFLoadedPageRenderSession.ProgressiveJPEGImagesDecoded report completed scan and image counts; THPDFLoadedPageRenderSession.OnProgressiveJPEGScan receives a THPDFProgressiveJPEGScanEvent after each visible scan and can cancel the session

The HPDFJpeg unit also exposes THPDFJpegScanDecoder for raw THPDFJpegByteArray inputs, with THPDFJpegScanDecodeStatus results and an optional THPDFJpegCancellationCheck callback for row-level cancellation

The incremental path accepts full-target DeviceRGB or DeviceGray JPEG image paints with default opacity and no masks, transfer functions, halftones, overprint, or transparency-group state; all other paints use the complete-image decoder to preserve rendering semantics

Disabling the option, requiring codec isolation, exceeding a limit, or encountering malformed input also selects the complete-image path without exposing a partial failed decode

Progress callbacks

THPDFProgressiveRenderProgressEvent runs after each completed operator and receives processed and total counts plus elapsed render-execution time

Set the callback Cancel parameter to true to finish that session in prsCancelled without cancelling the shared token

A Form XObject, pattern, image decode, or other nested operation belongs to its enclosing top-level operator and may exceed a small time budget before control returns

Operation-wide cancellation

Token := THPDFCancellationToken.Create;
try
  PDF.OperationCancellationToken := Token;
  Worker.Start;
  // Call Token.Cancel from another thread when the operation should stop
finally
  PDF.OperationCancellationToken := nil;
  Token.Free;
end;

THPDFCancellationToken is thread-safe, one-shot, and owned by the caller; Cancel permanently requests cancellation and IsCancellationRequested exposes the state

ThrowIfCancellationRequested raises EHPDFOperationCancelled and preserves the operation name in OperationName

THotPDF.OperationCancellationToken applies to load, synchronous render, progressive render without an explicit token, OptimizeLoadedStreams, CreatePreflightReport, and ValidatePDFVT

SignPDFWithPFX and SignPDFWithSystemCertificate provide overloads that accept a token directly

Ownership and partial-result rules

Related APIs