Technischer Artikel

HotPDF Resolution in Delphi: Zeicheneinheiten und UserWidth

In der HotPDF Component definiert THotPDF.Resolution die Zeicheneinheit: Jede X- und Y-Koordinate, jeder Rand, die an SetFont übergebene Größe und die Ergebnisse von TextWidth und GetWideTextWidth werden in 1/Resolution Zoll gemessen. THPDFPage.Width und Height folgen ihr nicht und bleiben in Punkt, Layoutgrenzen müssen also vom schreibgeschützten UserWidth und UserHeight kommen. Der übliche Grund, Resolution anzufassen, ist eine Portierung: Eine Report-Engine, die bereits in 1/96 oder 1/144 Zoll denkt, lässt sich leichter herüberziehen, wenn die PDF-Seite dieselbe Einheit spricht, als wenn jede Aufrufstelle einen Umrechnungsfaktor bekommt. Das funktioniert gut, solange Sie wissen, welche Zahlen mit in die neue Einheit gezogen sind und welche zurückgeblieben sind

Was ändert THotPDF.Resolution überhaupt?

THotPDF.Resolution ändert nur, wie HotPDF die Zahlen liest, die Sie hereinreichen; die PDF, die es schreibt, bleibt dieselbe. Der Setter besteht aus zwei Zeilen: SetResolution speichert den Wert und setzt DocScale := Value / 72. Von da an teilen XProjection und YProjection jede Koordinate auf dem Weg in den Content-Stream durch DocScale, und SetFont teilt die Größe auf dieselbe Weise, bevor er sie notiert. Der PDF User Space ist standardmäßig 1/72 Zoll (ISO 32000-1 §8.3.2.3), bei der Default-Resolution von 72 ist die Projektion also die Identität, und bei 144 ist eine Zeicheneinheit ein halber Punkt. Kein /UserUnit-Eintrag wird geschrieben. Jenes Seitenattribut, in PDF 1.6 hinzugekommen, ist ein eigenes Ding, das HotPDF als THPDFPage.SetUserUnit anbietet. Ein Detail, das Leute aus den TextOut-Tutorials erwischt: Seitenkoordinaten laufen von der oberen linken Ecke mit Y nach unten wachsend, weil YProjection die MediaBox-oberkante minus das skalierte Y rechnet — und das gilt bei jeder Resolution

Wie THotPDF.Resolution in Delphi die Zeicheneinheit definiert: Der Setter speichert DocScale als Resolution geteilt durch 72, dann teilen XProjection, YProjection und SetFont jede Koordinate und Größe auf dem Weg in den Content-Stream — Resolution 72 ist also eine Identitätsabbildung, und Resolution 144 macht eine Zeicheneinheit zu einem halben Punkt, während die Seite weiter oben links mit Y abwärts läuft
Nichts in der Ausgabedatei bewegt sich — nur die Bedeutung der Zahlen, die Sie hereinreichen, ändert sich, deshalb erscheint derselbe Content-Stream bei 72 und bei 144
var
  Pdf: THotPDF;
  Page: THPDFPage;
  Margin: Single;
  Title: WideString;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.FileName := 'invoice.pdf';
    Pdf.Resolution := 144;               // 1 Zeicheneinheit = 1/144 Zoll
    Pdf.BeginDoc;
    Page := Pdf.CurrentPage;             // A4: Width = 595, UserWidth = 1190
    Margin := 144;                       // ein Zoll in Zeicheneinheiten
    Page.SetFont('Arial', [fsBold], 28); // 28/144 Zoll, ein 14-pt-Font
    Title := 'INVOICE 2026-0417';
    // Rechtsbündig gegen die Seitenkante, gemessen in derselben Einheit
    Page.TextOut(Page.UserWidth - Margin - Page.GetWideTextWidth(Title),
      Margin, 0, Title);
    Page.SetLineWidth(2);                // 1-pt-Linie
    Page.MoveTo(Margin, Margin + 48);
    Page.LineTo(Page.UserWidth - Margin, Margin + 48);
    Page.Stroke;
    Pdf.EndDoc;
  finally
    Pdf.Free;
  end;
end;

Warum widerspricht Page.Width meinen Koordinaten bei Resolution 144?

THPDFPage.Width und Height melden die Seite in Punkt, egal welche Dokument-Resolution gilt, während Ihre Koordinaten in 1/Resolution Zoll laufen, bei 144 wirkt die Seite also halb so breit wie sie wirklich ist. Eine A4-Seite liest sich bei Resolution 72 als Width = 595 und Height = 842 und bei 144 weiterhin als 595 und 842, obwohl die rechte Kante tatsächlich bei X = 1190 liegt. UserWidth und UserHeight, verfügbar seit v2.766.0, liefern Width * DocScale, also die Seitengröße in der Einheit, in der Sie zeichnen. Mischt man die beiden, sind die Symptome bei Resolution 144 dramatisch: Absätze brechen nach jedem Zeichen um, eine Tabelle schiebt jede Zeile auf eine neue Seite, und importierter oder flach gedrückter Content zeichnet mit halber Größe, gequetscht in die obere linke Ecke. Deshalb lesen Absatz-Layout, Tabellen-Rendering, HTML-Import, EMF-Zentrierung, der WMF-Seiten-Clip und Layout-Diagnostik allesamt die User-Unit-Größe. Ihr eigener Layout-Code sollte es ihnen nachtun: Alles, was sich mit einer Zeichenkoordinate vergleicht (ein rechter Rand, ein Seitenumbruch-Test, eine Zentrierungsrechnung), gehört auf UserWidth und UserHeight, nie auf Width und Height

Falle eins: Width oder Height zuweisen schaltet die Seite auf Punkt um

Wer Page.Width oder Page.Height setzt, stellt die Seite still auf UserDefined um, und eine UserDefined-Seite ignoriert DocScale komplett; alles, was Sie danach darauf zeichnen, ist in Punkt, nicht in 1/Resolution Zoll. Der Setter nimmt Punkt — by design. Die Projektion einer UserDefined-Seite ist schlicht X + MinX, und SetFont speichert die Größe unverändert. Bei Resolution 144 ist das Ergebnis eine Seite, deren Inhalt plötzlich doppelt so groß herauskommt wie der der Seite davor. Dieselbe Falle wartet auf jeden Code, der eine Seite klont: die Größe der Vorseite über Width zu kopieren macht jede Kopie zur Punktseite. HotPDFs Absatz-Fortsetzungsseiten kopieren stattdessen Size, Orientation und die Seiten-Resolution und fallen nur auf Width und Height zurück, wenn die Originalseite ohnehin schon UserDefined war

Zwei Auswege, je nachdem, was Sie brauchen. Taugt ein Standardformat, setzen Sie Page.Size und Page.Orientation und zeichnen weiter in Ihrer Resolution-Einheit. Brauchen Sie wirklich eine eigene Seitengröße, akzeptieren Sie, dass es eine Punktseite ist, und zeichnen Sie in Punkt; dort ist UserWidth gleich Width, Layout-Code, der immer UserWidth liest, funktioniert also auf beiden Seitenarten. Ein schneller Check zeigt es: Bei Resolution 144 meldet eine A4-Seite ein UserWidth von 1190, nach Width := 500 und Height := 400 aber 500 und 400. Geladene Seiten verhalten sich genauso, denn eine aus einem bestehenden PDF wiederaufgebaute Seite kennt nur ihre MediaBox in Punkt und zeichnet in Punkt. Seiten, die dieses Dokument selbst erzeugt hat, behalten ihre Einheiten, wenn Sie über CurrentPageNumber weg und wieder zurückschalten

Warum Page.Width bei Resolution 144 in HotPDF Ihren Koordinaten widerspricht: Width und Height bleiben in Punkt, während das Zeichnen in 1/144 Zoll läuft — eine A4-Seite liest sich als 595, ihre rechte Kante liegt aber bei UserWidth 1190, und eine Width-Zuweisung schaltet die Seite auf UserDefined um, das DocScale ignoriert, sodass Absätze pro Zeichen umbrechen, Tabellen pro Zeile brechen und SetFont-Größen halbieren
Alles, was sich mit einer Zeichenkoordinate vergleicht, gehört auf UserWidth und UserHeight — auf einer UserDefined-Punktseite fallen beide zusammen, derselbe Layout-Code überlebt also beide Seitenarten

Falle zwei: Warum kommen Fontgrößen halb so groß heraus?

Eine Fontgröße, die als Punkt begann, kommt bei Resolution 144 mit halber Größe heraus, weil SetFont sein Größenargument als Zeicheneinheit behandelt und vor dem Speichern in Punkt konvertiert. Intern legt SetFont ASize / DocScale * DPI im aktuellen Font-Objekt ab, der gespeicherte Wert ist also immer Punkt. Reichen Sie diesen gespeicherten Punkt-Wert zurück an SetFont, wird er ein zweites Mal skaliert und halbiert den Text — genau das muss jeder Pfad vermeiden, der einen Font neu anwendet, etwa ein Font-Fallback oder eine Fortsetzungsseite. Ihr Code kann den gespeicherten Wert nicht lesen, aber dieselbe Falle zeigt sich immer dann, wenn ein Punkt-Wert von woanders SetFont erreicht: ein TFont.Size aus einem VCL-Formular, eine Größe in einer Report-Definition, eine CSS-pt-Angabe. Konvertieren Sie ihn zuerst, und ziehen Sie die eigene Resolution der Seite und den UserDefined-Fall in den Faktor ein, so wie die Metafile-Wiedergabe es beim Abspielen des Seiten-Canvas tut (dieser Pfad ist in wie HotPDF EMF- und WMF-Vektorgrafiken importiert beschrieben):

// Zeicheneinheiten pro Punkt auf der aktuellen Seite. Spiegelt die Projektion,
// die HotPDF benutzt: 1 auf einer über Width/Height bemessenen Seite, sonst
// (document Resolution / 72) * (page Resolution / 72)
function UnitsPerPoint(Pdf: THotPDF): Single;
begin
  if Pdf.CurrentPage.Size = UserDefined then
    Result := 1
  else
    Result := (Pdf.Resolution / 72) * (Pdf.CurrentPage.Resolution / 72);
end;

procedure SetFontFromVcl(Pdf: THotPDF; Font: TFont);
begin
  // TFont.Size ist in Punkt; SetFont erwartet Zeicheneinheiten
  Pdf.CurrentPage.SetFont(AnsiString(Font.Name), Font.Style,
    Font.Size * UnitsPerPoint(Pdf));
end;

Die Bibliothek wendet dieselbe Regel auf ihre eigenen Punkt-Konstanten an. Der 12-Punkt-Font, mit dem jede neue Seite startet, wird mit dem internen Einheiten-pro-Punkt-Faktor multipliziert, er ist also bei jeder Resolution 12 Punkt. DrawChart, dessen Ränder, Label-Größen und Linienbreiten alle hart kodierte Punkt sind, läuft mit temporär auf 1 gesetztem Scale. Bewusst in Zeicheneinheiten bleiben öffentliche Parameter-Defaults wie die DrawQRCode-Modulgröße und die Default-Tabellenfontgröße: Sie sind Teil des API-Vertrags, bedeuten bei Resolution 144 also die Hälfte von dem, was sie bei 72 bedeuten. Wenn Sie Reports aus einer Vorlage bemessen, behandelt die Anleitung zu Report-Ausgabe mit Fonts und Bildern in HotPDF, wo diese Werte üblicherweise herkommen

Wie prüfen Sie, dass ein Layout von der Resolution unabhängig ist?

Der verlässlichste Check ist ein Byte-Vergleich: dieselbe Seite einmal bei Resolution 72 und einmal bei 144 rendern, mit jeder Koordinate und jeder Größe verdoppelt, und die unkomprimierten Content-Streams müssen identisch sein. Beide Läufe landen nach der Projektion auf denselben Punkt-Werten, jede Abweichung ist also ein Wert, der die Konvertierung übersprungen hat. Die Technik funktioniert für Ihren eigenen Report-Code mit fast keinem Testgerüst:

procedure RenderPage(const FileName: string; Res: Integer; K: Single);
var
  Pdf: THotPDF;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.AutoLaunch := False;
    Pdf.Compression := cmNone;       // lesbare Content-Streams
    Pdf.FileName := FileName;
    Pdf.Resolution := Res;
    Pdf.BeginDoc;
    Pdf.CurrentPage.SetFont('Arial', [], 10 * K);
    Pdf.CurrentPage.TextOut(36 * K, 36 * K, 0, 'Line 1');
    Pdf.CurrentPage.Rectangle(36 * K, 60 * K, 200 * K, 40 * K);
    Pdf.CurrentPage.Stroke;
    Pdf.EndDoc;
  finally
    Pdf.Free;
  end;
end;

// RenderPage('r72.pdf', 72, 1) und RenderPage('r144.pdf', 144, 2)
// müssen byte-identische Seiten-Content-Streams erzeugen
Wie man Auflösungsunabhängigkeit in HotPDF-Delphi-Code verifiziert: dasselbe Layout zweimal rendern, einmal bei Resolution 72 mit Skalierung 1 und einmal bei 144 mit jeder Koordinate und jeder Fontgröße verdoppelt, dann byte-identische unkomprimierte Content-Streams fordern — eine Abweichung zeigt auf eine über Width auf UserDefined umgestellte Seite oder auf einen unkonvertierten Punkt-Wert, der SetFont erreicht
Beide Läufe landen nach der Projektion auf denselben Punkt-Werten, jede Abweichung ist also eine Zahl, die ihre Konvertierung übersprungen hat

Prüfen Sie die Operatoren, die Zahlen tragen: Td, Tm, Tf, re, w und die TJ-Arrays. Bytes auf Dateiebene unterscheiden sich weiterhin im Erzeugungsdatum und in der /ID, vergleichen Sie also die Streams, nicht ganze Dateien. Eine Abweichung zeigt fast immer auf eine der zwei Fallen oben: eine Seite, die über Width umgestellt wurde, oder ein Punkt-Wert, der unverändert in SetFont gelangt. Wenn Sie neu bei den Zeichenaufrufen selbst sind, beginnen Sie mit dem HotPDF-TextOut-Walkthrough zu Größe, Stil und Rotation, und kommen Sie dann zurück und schalten die Resolution um, sobald Ihr Layout UserWidth liest. Vollständige API-Details und Trial-Downloads gibt es auf der HotPDF Delphi PDF component-Seite