getThumbnail method

Returns a thumbnail image for the page at pageIndex.

When the page contains an embedded /Thumb stream, that bitmap is decoded and returned at its native dimensions with PdfThumbnailSource.embedded. Not all PDFs contain embedded thumbnails — modern tools such as pdflatex typically do not produce them.

When no embedded thumbnail is present and generateIfAbsent is true (the default), the page is rendered at a size proportional to maxDimension (longest edge ≤ maxDimension pixels, aspect ratio preserved) and returned with PdfThumbnailSource.rendered.

When no embedded thumbnail is present and generateIfAbsent is false, null is returned without any render pass. This is useful for callers that only wish to surface natively-embedded previews.

maxDimension is a logical pixel budget — it applies only to the fallback render path and is ignored for embedded thumbnails. On high-DPI displays (e.g. Retina), multiply maxDimension by MediaQuery.of(context).devicePixelRatio before calling to obtain a full-resolution fallback render. This method lives in the pure-Dart layer and cannot access MediaQuery itself.

Error contract

Throws RangeError if pageIndex is out of range for the document. Throws ArgumentError if maxDimension ≤ 0. Throws StateError if close has been called before or during the call. Throws PdfiumException if a PDFium native call fails unexpectedly.

Platform support: Native (dart:ffi) only. Stubs on unsupported platforms throw UnsupportedError immediately.

Example — display a thumbnail in a Flutter widget:

final dpr = MediaQuery.of(context).devicePixelRatio;
final thumb = await doc.getThumbnail(0, maxDimension: (256 * dpr).round());
if (thumb != null) {
  // thumb.bgra is BGRA bytes; thumb.width × thumb.height is the size.
}