PdfRasterCache class

Persists low-resolution page rasters to a PdfDiskCache so a document reopened in a later session shows soft page content immediately - instead of blank paper - while the (heavy, twice-over-the-content- stream) full render computes.

This is the raster half of the library's on-disk caching, layered on the same pluggable PdfCacheStore seam as the text cache. The primary cache stores small page previews. Hosts may also provide independent byte-budgeted stores for exact page rasters and LoD tiles. Keeping the three workloads in separate namespaces prevents a handful of large page images from evicting the previews that make cold navigation resilient. Rasters are encoded as PNG via ui.Image (no extra dependency) and decoded with ui.instantiateImageCodec.

A cache is bound to one document via documentKey; call forDocument to derive a view for the currently-open file (its pdfContentKey, or a host-supplied stable id). With an empty key every operation no-ops, so an un-bound cache is harmless.

Implemented types

Constructors

PdfRasterCache(PdfDiskCache cache, {String documentKey = '', PdfDiskCache? fullRasters, PdfDiskCache? tiles, PdfRasterDiskFormat fullRasterFormat = PdfRasterDiskFormat.png, PdfRasterCacheStats? fullRasterStats, PdfRasterCacheStats? tileStats})

Properties

cache → PdfDiskCache
The byte store these rasters persist into.
final
documentKey → String
Identifies the document these rasters belong to; empty disables I/O.
final
fullRasterFormat → PdfRasterDiskFormat
How full rasters are serialized (see PdfRasterDiskFormat).
final
fullRasters → PdfDiskCache?
Optional persistent tier for exact full-resolution page rasters (issue #615). Host opt-in and deliberately a separate PdfDiskCache: full rasters are two to three orders of magnitude larger than a preview, so sharing one budget would let a handful of page images evict the whole preview/thumbnail set that makes cold navigation resilient. Give it its own namespace and its own PdfDiskCache.maxBytes:
final
fullRasterStats → PdfRasterCacheStats
Diagnostics for the full-raster tier, shared across forDocument views.
final
hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
storesFullRasters → bool
Whether exact full-resolution rasters can be read and written right now (the host wired fullRasters and the view is bound to a document).
no setter
storesTiles → bool
Whether LoD tiles can be read and written for this bound document.
no setter
tiles → PdfDiskCache?
Optional persistent tier for LoD tiles. Keep this separate from previews and full-page rasters so each workload has an independent byte budget. Tile reads race the live raster path and writes happen after admission, so enabling this tier never blocks a cache miss from rendering.
final
tileStats → PdfRasterCacheStats
Diagnostics for the persistent tile tier.
final

Methods

clearFullRasters() → Future<void>
Empties the persistent full-raster tier. Previews and thumbnails (a different PdfDiskCache) are untouched.
clearTiles() → Future<void>
Empties the persistent LoD tile tier. Previews and exact full-page rasters use different stores and are untouched.
forDocument(String documentKey) → PdfRasterCache
A view of this cache bound to documentKey - share one underlying PdfDiskCache (and its byte budget) across every document the session opens.
fullRasterKey(int pageIndex, {required int width, required int height, required int pageColor, required bool annotations, required int? rotation, String revision = ''}) → String
The persistent key for one exact page raster.
loadFullRaster(int pageIndex, {required int width, required int height, required int pageColor, required bool annotations, required int? rotation, String revision = ''}) → Future<Image?>
The stored exact raster for pageIndex at exactly width x height, decoded into a ui.Image the caller owns (and must dispose), or null on any miss: absent entry, corrupt payload, dimension disagreement, decode failure, or a throwing backend. Every one of those degrades to an ordinary render.
loadPreview(int pageIndex) → Future<Image?>
The stored preview for pageIndex decoded to a ui.Image the caller owns (and must dispose), or null on a miss / decode failure.
loadThumbnail(int pageIndex, int pixelWidth, {int pageColor = 0xFFFFFFFF, bool annotations = true}) → Future<Image?>
The stored thumbnail for pageIndex at the pixelWidth bucket, decoded to a ui.Image the caller owns (and must dispose), or null on a miss / decode failure. Lets the page grid open onto already-rendered thumbnails in a later session instead of re-interpreting every page.
loadTile(PdfTileKey key, {required Rect region, required double pixelRatio, required int width, required int height}) → Future<Image?>
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
readBytes(int pageIndex) → Future<Uint8List?>
Reads the raw stored PNG bytes for pageIndex (test hook / advanced callers that decode themselves).
readFullRasterBytes(int pageIndex, {required int width, required int height, int pageColor = 0xFFFFFFFF, bool annotations = true, int? rotation, String revision = ''}) → Future<Uint8List?>
Raw stored bytes for one exact raster (test hook).
storeFullRaster(int pageIndex, Image image, {required int pageColor, required bool annotations, required int? rotation, String revision = ''}) → Future<void>
Encodes image and stores it as pageIndex's exact raster.
storePreview(int pageIndex, Image image) → Future<void>
Encodes image as PNG and writes it as pageIndex's preview. Best-effort and fire-and-forget at the call sites; image stays owned by the caller.
storeThumbnail(int pageIndex, int pixelWidth, Image image, {int pageColor = 0xFFFFFFFF, bool annotations = true}) → Future<void>
Encodes image as PNG and writes it as pageIndex's thumbnail at the pixelWidth bucket. Best-effort and fire-and-forget at the call sites; image stays owned by the caller.
storeTile(PdfTileKey key, Image image, {required Rect region, required double pixelRatio}) → Future<void>
Best-effort write-through. Implementations must retain or clone image synchronously before their first await because the memory LRU owns it.
override
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

fullRasterVersion → const String
Generation of the stored full-raster payload and of the renderer that produced the pixels. Bump it whenever either changes meaning: it is part of the key, so old entries simply stop matching and age out of the LRU.
tileVersion → const String