A page cache keyed by file name will show yesterday's pages for a PDF that was overwritten overnight with a new revision under the same name. A cache keyed by a full SHA-256 of the file never makes that mistake, but on a 400 MB scanned archive the hash can take longer than rendering the two pages the user actually opens. The workable key sits between those two, and choosing it also forces a second decision: what an in-memory edit should do to pages already sitting on disk
How the RenderCacheFolder disk tier sits behind the memory cache
HotPDF RenderCacheFolder adds a persistent tier behind the in-memory raster cache of the HotPDF Delphi component, and it only takes part when the property holds a non-empty path. A call to RenderLoadedPageToBitmapCached(PageIndex, DPI) checks memory first, using page index, DPI and the current render settings as the key. On a miss it asks the disk. A disk hit decodes the stored PNG, promotes it back into memory and hands you a copy. Only when both tiers miss does the page go through the full renderer described in rendering a loaded PDF page to a TBitmap, and that fresh bitmap is written to disk on the way out
The folder layout is plain enough to inspect in Explorer. Each document gets a subfolder whose name combines a 16-hex-character document key with a 16-hex-character render-settings key, and every page lands there as <page>@<dpi>.png. An index.txt at the root lists documents in most-recently-used order under a schema tag; if the tag does not match, the whole folder is cleared on first use. PNG and index writes go to a temporary file first and are then swapped in with MoveFileExW and the replace-existing flag, so a crash halfway through a write leaves the previous file or no file. A PNG that fails to decode is deleted and counted as a miss
Three limits keep the folder from growing without bound:
RenderCacheMaxDocuments(default 20) caps the number of document subfolders, evicting the least recently used one firstRenderCacheMaxBytes(default 524288000, or 500 MB) caps the combined size of every PNG under the root- Each document folder holds at most 200 page images; that cap is fixed inside THotPDF and has no property
RenderCacheCapacity (default 8) is unrelated to the disk. It counts pages held in memory
uses
SysUtils, Graphics, HPDFDoc;
procedure WarmThumbnails(const FileName: string);
var
Pdf: THotPDF;
Bmp: TBitmap;
I: Integer;
begin
Pdf := THotPDF.Create(nil);
try
// The disk tier reads the folder and both limits once, on the first
// cached render, so set them before that call
Pdf.RenderCacheFolder := IncludeTrailingPathDelimiter(
GetEnvironmentVariable('LOCALAPPDATA')) + 'MyViewer\PageCache';
Pdf.RenderCacheMaxDocuments := 50;
Pdf.RenderCacheMaxBytes := Int64(1024) * 1024 * 1024; // 1 GiB
Pdf.RenderCacheCapacity := 16; // pages in memory
if Pdf.LoadFromFile(FileName) > 0 then
for I := 0 to Pdf.LoadedPageCount - 1 do
begin
Bmp := Pdf.RenderLoadedPageToBitmapCached(I, 96);
if Bmp <> nil then
try
// Hand the copy to the thumbnail strip here
finally
Bmp.Free; // the cached call always returns a caller-owned copy
end;
end;
finally
Pdf.Free; // disk entries survive for the next session
end;
end;
Run that procedure twice on the same file and the second pass rasterizes nothing that fit the limits. The disk cache is created on the first cached render and lives as long as the THotPDF instance, so changing the folder or either limit after that moment does not move or resize it. Two more conditions keep a page off the disk. A bitmap above the memory cache's default per-entry ceiling (64 MiB of 32-bit pixels, a 4096 × 4096 page) is not stored. And the disk tier is consulted only while RenderFallbackPolicy stays at its default rfpIgnore, since a PNG carries pixels but none of the fallback diagnostics a stricter policy reports
Why do the obvious cache keys fail?
Three keys come to mind first, and each fails in a different way. The file path fails on overwrite. A hash of an in-memory copy of the PDF bytes looks safe until you notice that a parser reading the file in place has no reason to keep such a copy; hashing a buffer that was never filled yields an empty key, and a cache that treats an empty key as "skip the disk" leaves a correctly configured folder that never receives a PNG. Hashing the whole file from disk works, at the cost of reading every byte on every open
The harder trap is invalidation. A component like this has to clear its in-memory pages at the start of every load, after every edit and when it is destroyed, and the tempting move is to delete the document's disk folder in the same place. Do that and every viewer session wipes its own cache on exit, so the next morning starts cold anyway. Recomputing the key from the unchanged source after an edit is worse still: the edited renders land under the original file's key and get served to whoever opens the untouched PDF next. Identity and invalidation have to be designed as one piece. Get either one wrong and you ship a cache that never hits, or one that shows pages the file does not contain
How HotPDF fingerprints a PDF source
HotPDF identifies a PDF loaded with LoadFromFile by hashing its size, its last-write time and its first and last 64 KiB with SHA-256, and identifies a stream or random-access source by a SHA-256 of the entire content. The identity is captured once, when a load succeeds, and the first 16 hex characters of the digest (64 bits) become the document key
| Source | Identity | Cost | Captured when |
|---|---|---|---|
LoadFromFile | Size + last-write time + leading and trailing 64 KiB, hashed with SHA-256 | At most 128 KiB read, whatever the file size | Every successful load, even if RenderCacheFolder is set afterwards |
LoadFromStream | SHA-256 of the whole stream | One full pass over the source | Only if RenderCacheFolder was set before the load |
LoadFromRandomAccessSource | SHA-256 of the whole source | One full pass over the source | Only if the folder was set first and every byte range is available |
Any source with an /Encrypt entry | None | None | Never; the disk tier is bypassed |
For a desktop viewer the sampled fingerprint is the right default, and full hashing on every open is the wrong one. The two sampled regions were picked from the file structure. The header sits at the start; the trailer and the last cross-reference section sit at the end (ISO 32000-1 §7.5). An incremental update appends a new body, cross-reference section and trailer (§7.5.6), which changes the size and the tail together, and any ordinary full rewrite bumps the last-write time. Below 128 KiB the two samples overlap and cover every byte, so small documents are hashed in full anyway
What slips through is a same-size edit in the middle of a large file by a tool that then restores the original timestamp. Editors that deliberately preserve modification times while changing content exist, but they are rare, and against such a file the cache serves stale pages. The opposite case works in your favor: a Windows file copy keeps the last-write time, so a copy of a cached document hits the same entries, which is correct since the bytes match
A stream has no timestamp. Content is the only honest identity, so HotPDF pays for the full SHA-256 pass only when a disk cache was requested before the load, and code that calls LoadFromStream without a cache folder pays nothing extra. That makes the order of two lines matter:
procedure OpenDownloadedPdf(Pdf: THotPDF; Data: TStream;
const CacheRoot: string);
begin
// Wrong order for streams: the content hash is only computed when the
// folder is already set, so this document would bypass the disk tier
// Pdf.LoadFromStream(Data);
// Pdf.RenderCacheFolder := CacheRoot;
Pdf.RenderCacheFolder := CacheRoot; // set first
Data.Position := 0;
if Pdf.LoadFromStream(Data) <= 0 then
raise Exception.Create('The stream is not a loadable PDF');
end;
A random-access source that is still downloading gets no identity at all instead of a hash of whatever ranges have arrived. If computing the identity throws for any reason, the load still succeeds and the document renders through memory only
What happens to cached pages after an edit?
Editing a loaded document never deletes anything from the HotPDF disk render cache. The edit drops the document's identity instead, so the rest of that load bypasses the disk tier, and the stored pages stay valid for the unmodified file they were rendered from. Entries leave the disk only through the document and byte limits, the 200-page cap, a PNG that fails to decode, or a schema change
The key describes a file on disk. Once you stamp a page or change an annotation, the document in memory no longer matches it, so neither reading nor writing under that key would be honest. InvalidateRenderedPageCache and the per-page invalidation that edits trigger both clear the identity and leave the folder alone. A second check covers edit paths that never invalidated anything: before each disk lookup, THotPDF asks whether any loaded object carries unsaved changes and, if one does, treats the document as having no identity
Render settings go the other way. Assigning PageRenderBackend (which UseNativeGDIRenderBackend does for you), calling ConfigureRenderICCWorkflow or calling ClearRenderICCWorkflow flushes the pages in memory but keeps the identity, because the document still matches its file. Those settings change pixels without appearing in the memory key, so the disk key folds in the backend name, the black-point compensation flag and SHA-256 digests of the ICC proof and output profiles. The memory key already covers the color intent, output dithering, overprint preview, luminosity mask mode, fallback policy and the visibility of every optional content group
Layer visibility is a good example of a change that stays on disk. SetLoadedOptionalContentGroupVisible records the override in memory without touching any PDF object, so the document keeps its identity and the toggled view renders into its own subfolder next to the default one:
procedure ShowLayer(Pdf: THotPDF; const LayerName: AnsiString;
PageIndex: Integer; out Bmp: TBitmap);
var
I: Integer;
begin
for I := 0 to Pdf.GetLoadedOptionalContentGroupCount - 1 do
if Pdf.GetLoadedOptionalContentGroupName(I) = LayerName then
Pdf.SetLoadedOptionalContentGroupVisible(I, True);
// Same document key, different render-settings key: this page is read
// from or written to a second folder, and the default view is untouched
Bmp := Pdf.RenderLoadedPageToBitmapCached(PageIndex, 150);
end;
An edited document gets back onto the disk tier only by becoming a new file. Save it and load the result:
procedure CommitEditsAndRekey(Pdf: THotPDF; const EditedFile: string);
begin
// After editing: refresh the in-memory pages. The source identity is
// already gone, so the original document's folder is neither read
// nor written
Pdf.InvalidateRenderedPageCache;
// The saved file has its own size and last-write time, hence its own
// identity; renders after this load are cached under the new key
Pdf.SaveLoadedDocument(EditedFile);
if Pdf.LoadFromFile(EditedFile) <= 0 then
raise Exception.Create('Could not reload the edited document');
end;
The original document's folder stays where it was and ages out through RenderCacheMaxDocuments and RenderCacheMaxBytes like any other entry. Reopen the unedited original and its pages are still there
Encrypted sources, junctions and shared roots
The HotPDF disk render cache refuses two inputs on purpose: pages of an encrypted PDF, and document subfolders that are junctions or other reparse points. Both rules trade cache hits for safety
Encrypted PDFs stay in memory
A rendered page is decrypted content. Writing it as a plain PNG into a cache folder would leave a readable copy of a password-protected document on disk, outside the protection its author chose (ISO 32000-1 §7.6). HotPDF captures no identity for any source whose trailer carries an /Encrypt entry, whether it was opened with a password or with an empty user password. Those documents still use the memory tier, which disappears with the process
Linked document folders are skipped
The cache root is yours to choose, and pointing it at a junction is fine. The subfolders under it are different: the cache creates, touches and deletes them on its own during startup cleanup, lookup, store and all three eviction limits. If someone with write access to the root swapped a document folder for a junction to another directory, every one of those operations would follow it, and eviction would delete files elsewhere. Each entry point reads the folder's attributes first and skips anything flagged as a reparse point. A lookup counts a miss, a store counts a write failure, and eviction leaves it alone
Unicode paths and one root per process
RenderCacheFolder is a Unicode string, and the atomic replace calls the wide Windows API, so a profile path outside the system code page (a Chinese user name on an English Windows installation, say) reaches the cache intact. Several THotPDF instances in one process that resolve to the same root, compared case-insensitively after path expansion, share one reference-counted index and one lock. That matters for the limits: separate copies of index.txt would each enforce the 500 MB budget against a partial view and let the folder grow several times past it
Sharing ends at the process boundary. Two processes on the same root keep separate in-memory indexes, so each concurrently running application should get its own root. Worker threads inside one process are fine: PrefetchLoadedPages and the queue in background rendering with a request queue go through the same cached path and the same lock
Settings to get right before shipping
- Set the folder and both limits before the first cached render, and for stream or random-access loads before loading
- Expect memory-only rendering for encrypted PDFs, for documents edited after the load, and whenever
RenderFallbackPolicyis notrfpIgnore - Give each running application its own cache root under a per-user location such as
%LOCALAPPDATA%
A persistent page cache earns its disk space in a viewer that reopens the same documents all day, which is the workload behind the custom PDF viewer architecture in Delphi on this blog. The disk tier, the memory raster cache and the page renderer are all part of the HotPDF Delphi PDF component, available for Delphi and C++Builder