Technischer Artikel

PDFlibPas MovePage: Wenn geerbte Boxen Instanzen teilen

In PDFlibPas, der Delphi-PDF-Bibliothek, bekommt eine mit MovePage verschobene Seite eigene Kopien der MediaBox-, CropBox- und Resources-Werte, die sie von ihrem alten Pages-Knoten geerbt hatte, und eine indirekte Referenz bleibt eine Referenz. Der verschobenen Seite dieselben Objekte zu geben, die der alte Pages-Knoten hält, ist die naheliegende Implementierung, und sie bedeutet, dass ein späteres SetPageBox oder DrawText auf der verschobenen Seite still diesen Knoten und jedes Geschwister umschreibt, das noch von ihm erbt. Dieselbe Kopieren-statt-Teilen-Regel deckt zwei verwandte Pfade ab: SetPageBox auf einer indirekten Box, die mehrere Seiten teilen, und CopyPageRanges, das geerbte Werte auf den Seiten des Quelldokuments materialisiert

Symptome dieser Art von Aliasing erwähnen nie die Objektidentität. Sie klingen wie "Ich habe Seite 7 zugeschnitten und die Seiten 8 bis 12 wurden mit zugeschnitten", oder "Ich habe die CropBox verkleinert und die MediaBox ist mitgewandert", oder, das verwirrendste, "Ich habe eine Seite in ein neues Dokument kopiert und die Originaldatei hat sich geändert". Nichts stürzt ab, nichts leckt, und die gespeicherte Datei ist völlig valides PDF. Sie enthält nur Geometrie, nach der niemand gefragt hat

Wie kann SetPageBox auf einer Seite ihre Geschwister verkleinern?

Es passiert, wenn zwei Seitenbaum-Einträge auf ein In-Memory-Array zeigen und SetPageBox sein Zielarray an Ort und Stelle editiert: Jede Seite oder jeder Pages-Knoten, der dieselbe Instanz hält, sieht die Änderung. Drei Codepfade in einem Seitenbaum-Editor können dieses Teilen erzeugen:

  • MovePage materialisiert die vererbbaren Attribute auf die Seite, bevor es sie vom Parent abtrennt; die eigenen Objekte des Ahnen statt Kopien anzuhängen lässt die verschobene Seite und ihre früheren Geschwister ein Box-Array und ein Resources-Dictionary teilen
  • Ein Box-Schreiber, der indirekten Referenzen folgt und das referenzierte Array editiert, verkleinert mit einem einzigen Aufruf jede Seite, die auf ein /MediaBox 11 0 R-Objekt zeigt, ob MovePage je beteiligt war oder nicht
  • CopyPageRanges materialisiert geerbte Werte auf der Quellseite, bevor es sie in das Zieldokument klont; die Pages-Knoten-Instanzen an die Quellseite anzuhängen, plus die MediaBox-Instanz selbst als Standard-CropBox, verknotet alle miteinander
MovePage-Aliasing-Stolperfalle, bei der eine verschobene Seite und ihr früheres Geschwister beide die eigene MediaBox-Array-Instanz des Ahnen halten, sodass SetPageBox eine Seite editiert und die andere verkleinert; die PDFlibPas-Materialisierung hängt dekodierte Kopien an, sodass Änderungen lokal bei der angefassten Seite bleiben
Zwei Seitenbaum-Einträge, die auf ein In-Memory-Array zeigen, lassen jede Änderung bei jedem Halter landen, und die gespeicherte PDF bleibt die ganze Zeit valid

Materialisierung selbst ist nicht optional. Nur /Resources mitzunehmen und eine Seite unter einen anderen Parent zu verschieben lässt sie still Größe und Drehung des Parents annehmen, also trägt MovePage MediaBox, CropBox und Rotate ebenfalls mit, worauf sich auch CollateDocumentsEx verlässt, wenn es Seiten umordnet. Die einzige Frage ist, ob diese Werte als Kopien oder als geteilte Instanzen ankommen

Direkte Werte, indirekte Referenzen und die Vererbung von Seitenattributen

Eine korrekte Kopie eines geerbten Seitenattributs dupliziert direkte Werte und belässt indirekte Referenzen als Referenzen, denn das ist genau die Unterscheidung, die ISO 32000-1 selbst zieht. Ein direktes Objekt wie [0 0 400 300], geschrieben innerhalb eines Dictionaries, gehört diesem Dictionary allein. Ein indirektes Objekt, einmal definiert als 11 0 obj und zitiert als 11 0 R, ist per Design geteilt: ISO 32000-1 §7.3.10 macht es von überall in der Datei adressierbar, und jedes 11 0 R bedeutet dasselbe Objekt

Die Vererbung von Seitenattributen, ISO 32000-1 §7.7.3.4, fügt einen dritten Fall hinzu. Resources, MediaBox, CropBox und Rotate dürfen auf einem Pages-Knoten sitzen und gelten für jede Nachfolgeseite, die keine eigenen definiert. Die Seite hält den Wert nicht; sie schlägt ihn über /Parent nach. Diese Nachschlagkette bricht in dem Moment, in dem eine Seite den Parent wechselt, deshalb müssen MovePage und BalancePageTree zuerst die effektiven Werte auf die Seite selbst schreiben. Die Frage ist nur, wie man sie schreibt

Warum ein Objekt-Pool den Fehler versteckt

In PDFlibPas gehört jedes geparste oder erzeugte PDF-Objekt dem TPDFStructure-Pool des Dokuments, und Dictionaries und Arrays speichern schlicht Zeiger auf ihre Einträge. TPDFDictionary.Add notiert den Zeiger und nichts weiter. Eine Instanz an zwei Parent-Container anzuhängen ist also auf jeder Ebene legal, die die Runtime prüfen kann: kein Double Free beim Abbau, kein Referenzzähler, der schiefgehen könnte, keine Exception. Die Serialisierung ist ebenso gnädig, denn jeder Container schreibt den aktuellen Wert der geteilten Instanz inline, und vor jeder Änderung ist die Ausgabe byte für byte das, was eine korrekte Kopie liefern würde

Das Aliasing kommt erst ans Licht, wenn jemand die geteilte Instanz an Ort und Stelle mutiert. SetPageBox tut genau das über einen Rechteck-Wrapper über dem bestehenden Array, und das Zeichnen auf einer Seite tut es am Resources-Dictionary, sobald ein Font oder Bild registriert wird. Die Änderung landet, stillschweigend, in jedem anderen Container, der den Zeiger hält

Wie PDFlibPas kopiert, statt zu teilen

PDFlibPas behandelt das Problem an beiden Enden: Die Materialisierung hängt Kopien an, und Box-Schreibvorgänge editieren nur ein Array, das die Seite besitzt. Jede Regel deckt einen Fall ab, den die andere nicht kann

Der Materialisierungs-Helfer, PLInheritPageAttributes, hängt Page.Owner.Decode(Value.Output) an statt Value selbst. Der Round-Trip durch den Serialisierer ist eine plumpe, aber exakte Art, die PDF-Semantik gratis zu bekommen. Ein direktes Array oder Dictionary serialisiert zu seinem Literaltext und dekodiert zu einer frischen, unabhängigen Instanz. Eine indirekte Referenz serialisiert zu 11 0 R und dekodiert zu einem neuen Referenzobjekt, das auf dasselbe Objekt 11 zeigt, also verweist die Seite weiterhin auf das geteilte Objekt, statt eine inline Kopie zu erhalten. Die Kopie ist exakt so tief wie die direkte Struktur: Alles, was über eine Referenz innerhalb eines kopierten Dictionaries erreichbar ist, bleibt geteilt, wie das Dateiformat es vorsieht. BalancePageTree ruft denselben Helfer für jede Seite auf, deren Parent es wechselt, also bekommen auch dort materialisierte Seiten getrennte Instanzen

PDFlibPas-Materialisierungs-Roundtrip, bei dem PLInheritPageAttributes Page.Owner.Decode(Value.Output) anhängt: ein direktes Array serialisiert zu Literaltext und dekodiert zu einer frischen Instanz, während eine indirekte 11 0 R serialisiert und zu einer neuen Referenz dekodiert, die weiterhin auf das geteilte Objekt 11 zeigt
Serialisieren und neu Parsen liefert die PDF-Objektsemantik gratis: direkte Werte werden kopiert, Referenzen bleiben Referenzen, exakt wie ISO 32000-1 es vorsieht

Kopieren allein reicht nicht, denn der Referenzfall zeigt weiterhin auf ein geteiltes Objekt. Folgte SetPageBox dieser Referenz und editierte Objekt 11, würde die verschobene Seite erneut den alten Parent und seine anderen Kinder verkleinern. Also wendet der Box-Schreiber Copy-on-Write an: Er editiert nur an Ort und Stelle, wenn der eigene Eintrag der Seite ein direktes Array ist, und ersetzt eine indirekte oder fehlende Box durch ein neues direktes Array. Objekt 11 bleibt unangetastet für jede andere Seite, die es zitiert

PDFlibPas-SetPageBox-Copy-on-Write-Entscheidung: Ist der eigene Eintrag der Seite ein direktes Array, wird er an Ort und Stelle editiert, ist es eine indirekte Referenz oder fehlt die Box, ersetzt der Schreiber sie durch ein neues direktes Array, sodass das geteilte Objekt 11 seinen Wert für jede andere zitierende Seite behält
Kopieren bei der Materialisierung reicht nicht, solange Referenzen weiter auf geteilte Objekte zeigen, der Box-Schreiber editiert also nur, was die Seite besitzt
CodepfadGeteilte Instanzen (die Falle)PDFlibPas
MovePage-MaterialisierungSeite hält die eigenen direkten Instanzen des AhnenSeite hält dekodierte Kopien; Referenzen bleiben Referenzen
SetPageBoxFolgt einer Referenz und editiert das geteilte ArrayEditiert nur ein direktes Array auf der Seite, schreibt sonst ein neues
CopyPageRanges-QuellseiteTeilt Pages-Knoten-Boxen; CropBox ist die MediaBox-InstanzJeder materialisierte Wert auf der Quellseite ist eine Kopie
Default-Boxen beim Klonen von SeitenressourcenCropBox, BleedBox, TrimBox und ArtBox teilen ein ArrayJede Default-Box bekommt ihr eigenes Array

Die letzte Zeile ist die subtile. Klont die Bibliothek die Ressourcen einer Seite für Seiten-Erfassung oder Merging, füllt sie fehlende CropBox-, BleedBox-, TrimBox- und ArtBox-Einträge auf, und alle vier aus einer Array-Instanz zu füllen ließe ein Alias warten auf den ersten Aufrufer, der eine davon editiert. Wie diese Default-Box-Werte gewählt werden, ist ein eigenes Thema, behandelt im PDFlibPas-Leitfaden zu TrimBox-, BleedBox- und CropBox-Defaults

Das MovePage-Aliasing mit einem handgebauten PDF reproduzieren

Der schnellste Weg, Seitenbaum-Editier-Code auf Aliasing zu testen, ist ein kleines handgeschriebenes PDF, geladen mit LoadFromString, bei dem jede Objektnummer im Voraus bekannt ist. Der Helfer unten schreibt eine klassische Cross-Reference-Tabelle mit korrekt berechneten Byte-Offsets, sodass der Test nicht auf das Wiederherstellungs-Verhalten des Parsers bei beschädigten Dateien angewiesen ist

uses
  System.SysUtils, PDFlibrary;

function BuildPdf(const Objects: array of AnsiString): AnsiString;
var
  Offsets: array of Integer;
  I, XRefPos: Integer;
begin
  Result := '%PDF-1.4'#10;
  SetLength(Offsets, Length(Objects));
  for I := 0 to High(Objects) do
  begin
    Offsets[I] := Length(Result);   // 0-basiertes Byte-Offset von "N 0 obj"
    Result := Result + AnsiString(IntToStr(I + 1)) + ' 0 obj'#10 +
      Objects[I] + #10'endobj'#10;
  end;
  XRefPos := Length(Result);
  Result := Result + 'xref'#10'0 ' + AnsiString(IntToStr(Length(Objects) + 1)) +
    #10'0000000000 65535 f '#10;
  for I := 0 to High(Offsets) do      // jeder Eintrag ist exakt 20 Bytes
    Result := Result + AnsiString(Format('%.10d 00000 n ', [Offsets[I]])) + #10;
  Result := Result + 'trailer'#10'<< /Size ' +
    AnsiString(IntToStr(Length(Objects) + 1)) + ' /Root 1 0 R >>'#10 +
    'startxref'#10 + AnsiString(IntToStr(XRefPos)) + #10'%%EOF'#10;
end;

function StreamObj(const Content: AnsiString): AnsiString;
begin
  Result := '<< /Length ' + AnsiString(IntToStr(Length(Content))) +
    ' >>'#10'stream'#10 + Content + #10'endstream';
end;

Das Testdokument hat zwei Zwischen-Pages-Knoten. Knoten 3 trägt eine indirekte MediaBox (Objekt 11, 400 mal 300 Punkte), eine direkte CropBox und ein direktes Resources-Dictionary und besitzt zwei Seiten. Knoten 4 hat eine Letter-große MediaBox und besitzt die dritte Seite. Seite 1 auf Position 3 zu verschieben hängt sie unter Knoten 4 um, genau die Verschiebung also, die Materialisierung braucht: ohne sie würde die Seite zu einer Letter-Seite

procedure Check(Condition: Boolean; const Msg: string);
begin
  if not Condition then
    raise Exception.Create(Msg);
end;

procedure CheckMovedPageIsIsolated;
var
  Lib: TPDFlib;
  FontID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Check(Lib.LoadFromString(BuildPdf([
      '<< /Type /Catalog /Pages 2 0 R >>',
      '<< /Type /Pages /Kids [3 0 R 4 0 R] /Count 3 >>',
      '<< /Type /Pages /Parent 2 0 R /Kids [5 0 R 6 0 R] /Count 2 ' +
        '/MediaBox 11 0 R /CropBox [10 20 390 280] /Resources << >> >>',
      '<< /Type /Pages /Parent 2 0 R /Kids [7 0 R] /Count 1 ' +
        '/MediaBox [0 0 612 792] >>',
      '<< /Type /Page /Parent 3 0 R /Contents 8 0 R >>',
      '<< /Type /Page /Parent 3 0 R /Contents 9 0 R >>',
      '<< /Type /Page /Parent 4 0 R /Contents 10 0 R >>',
      StreamObj('1 w'), StreamObj('2 w'), StreamObj('3 w'),
      '[0 0 400 300]']), '') = 1, 'load failed');

    Lib.SelectPage(1);
    Check(Lib.MovePage(3) = 1, 'MovePage failed');
    Lib.SelectPage(3);                       // die Seite, die wir gerade verschoben haben
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'inherited MediaBox lost');

    Lib.SetPageBox(1, 0, 200, 200, 200);     // MediaBox 200 x 200
    Lib.SetPageBox(2, 0, 100, 100, 100);     // CropBox 100 x 100
    FontID := Lib.AddStandardFont(4);        // Helvetica
    Lib.SelectFont(FontID);
    Lib.SetTextSize(12);
    Lib.DrawText(20, 20, 'MOVED');

    // Den alten Parent ansehen, BEVOR eine andere Seite gewählt wird (siehe unten)
    Check(Pos(AnsiString('/Font'), Lib.GetObjectToString(3)) = 0,
      'font registered in the old Pages node');

    Lib.SelectPage(1);                       // frühere Seite 2, weiterhin unter Knoten 3
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'sibling MediaBox changed');
    Check(Abs(Lib.GetPageBox(2, 2) - 380) < 0.001, 'sibling CropBox changed');
    Check(Pos(AnsiString('400'), Lib.GetObjectToString(11)) > 0,
      'shared object 11 was rewritten');
  finally
    Lib.Free;
  end;
end;

GetPageBox(BoxType, Dimension) nimmt den Box-Typ 1 für MediaBox und 2 für CropBox, und Dimension 2 für die Breite. Beim voreingestellten Ursprung unten links bedeutet SetPageBox(1, 0, 200, 200, 200) links 0, oben 200, 200 breit und 200 hoch. Mit einem Materialisierer, der Instanzen teilt, scheitern die Geschwister-Prüfungen: Die CropBox-Änderung landet im direkten Array von Knoten 3, und ein Box-Schreiber, der Referenzen folgt, schreibt Objekt 11 um

Ändert CopyPageRanges das Quelldokument?

CopyPageRanges schreibt tatsächlich auf die Quellseiten, aber jeder Wert, den es schreibt, ist eine separate Kopie, also bleiben spätere Änderungen an der Quelle lokal bei der Seite, die man editiert. Das Schreiben selbst ist Absicht: Die Quellseite braucht explizite MediaBox, CropBox, Rotate und Resources, bevor ihr Dictionary in das Ziel geklont wird, sonst würde die Kopie alles verlieren, was sie geerbt hatte. Umnummerierung und das Kopieren der Seite ins Ziel sind in dokumentübergreifende Objekt-Deep-Copy in PDFlibPas behandelt; die Falle hier sitzt auf der Quellseite, von der die meisten annehmen, eine Kopie lese sie nur

Die gespeicherte Ausgabe zeigt es nie. Geteilt oder kopiert, die materialisierten Werte serialisieren identisch, also speichern beide Dokumente so oder so byte für byte dasselbe. Erst eine Änderung am Quelldokument nach der Kopie enthüllt einen Alias:

procedure CheckSourceSurvivesCopy;
var
  Lib: TPDFlib;
  SourceID, TargetID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Check(Lib.LoadFromString(BuildPdf([
      '<< /Type /Catalog /Pages 2 0 R >>',
      '<< /Type /Pages /Kids [3 0 R 4 0 R] /Count 2 ' +
        '/MediaBox [0 0 400 300] /Resources << >> >>',
      '<< /Type /Page /Parent 2 0 R /Contents 5 0 R >>',
      '<< /Type /Page /Parent 2 0 R /Contents 6 0 R >>',
      StreamObj('1 w'), StreamObj('2 w')]), '') = 1, 'load failed');
    SourceID := Lib.SelectedDocument;

    TargetID := Lib.NewDocument;             // wird das gewählte Dokument
    Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');

    Lib.SelectDocument(SourceID);
    Lib.SelectPage(1);
    Lib.SetPageBox(2, 50, 250, 100, 100);    // nur die CropBox verkleinern
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'MediaBox followed CropBox');
    Lib.SetPageBox(1, 0, 200, 200, 200);

    Lib.SelectPage(2);
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'sibling page resized');

    Lib.SelectDocument(TargetID);            // die Kopie behält ihre Originalgröße
    Lib.SelectPage(Lib.PageCount);
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'copied page resized');
  finally
    Lib.Free;
  end;
end;

Beide Seiten hier erben die direkte MediaBox des Wurzelknotens. Ein Kopier-Schritt, der diese Instanz an Quellseite 1 anhängt, und sie erneut als CropBox von Seite 1 anhängt, würde das Verkleinern der CropBox die MediaBox verkleinern lassen und das Verkleinern der MediaBox Seite 2 über den Wurzelknoten verkleinern. Workflows, die Seiten herauskopieren und dann weiter an der Quelle editieren, etwa Duplex-Scans zu einem PDF kollatieren, bevor man die Originale beschneidet, sind der Ort, an dem diese Art von Alias auftaucht

Warum ist Instanz-Aliasing so schwer zu testen?

Instanz-Aliasing ist schwer zu testen, weil der beobachtbare Effekt drei Schritte in einer bestimmten Reihenfolge braucht: das Aliasing erzeugen, eine Seite mutieren, dann die andere Seite ansehen, bevor irgendetwas anderes sie anfasst. Die meisten Tests tun nur den ersten Schritt und vergleichen gespeicherte Ausgabe, die identisch ist, ob das Aliasing existiert oder nicht

Die Reihenfolgen-Falle in PDFlibPas ist SelectPage. Eine Seite zu wählen wendet den aktuellen Font erneut über SelectFont an, was diesen Font in den Ressourcen der Seite registriert. Eine Seite ohne eigenes /Resources löst zum Dictionary ihres Parents auf, also fügt das schlichte Wählen einer solchen Seite legitim /Font zum Pages-Knoten hinzu. Im MovePage-Test oben fügt das Wählen der früheren Seite 2 den Helvetica-Eintrag zu Knoten 3 hinzu, korrektes Verhalten und kein Leak. Deshalb läuft die GetObjectToString(3)-Prüfung vor SelectPage(1); vertauscht man die beiden, scheitert der Test, selbst wenn kein Alias existiert

Diese Regel markiert auch, was PDFlibPas bewusst in Ruhe lässt. Eine Ressource auf eine Seite zu schreiben, die ihr Resources-Dictionary erbt, schreibt in das Dictionary des Ahnen, und jedes Geschwister sieht den neuen Eintrag. Das ist Vererbung, wie sie spezifiziert ist, nicht Instanz-Teilen, und es ist harmlos, denn das Hinzufügen eines Font- oder Bild-Namens zu einem geteilten Dictionary ändert nicht, wie andere Seiten rendern. Soll eine Seite aufhören zu erben, erst ein eigenes Resources-Dictionary geben

Checkliste für PDF-Objektmodell-Code

Die Lektionen verallgemeinern sich auf jedes PDF-Objektmodell, das auf einem Pool und Zeiger-Containern baut, in Delphi oder woanders:

  • Werden geerbte Attribute nach ISO 32000-1 §7.7.3.4 materialisiert, direkte Werte deep-copyen und indirekte Referenzen als neue Referenzen auf dasselbe Objekt belassen
  • Niemals eine bestehende Instanz per Add an einen zweiten Container hängen, außer das Teilen ist beabsichtigt und dokumentiert; das Eigentum eines Pools bedeutet, dass die Runtime sich nie beschwert
  • Nur das an Ort und Stelle editieren, was der aktuelle Knoten als direktes Objekt besitzt; indirekte oder geerbte Werte durch ein frisches direktes Objekt ersetzen (Copy-on-Write)
  • Standardwerte, die aus einem anderen Eintrag abgeleitet sind, etwa eine CropBox aus einer MediaBox, brauchen ihre eigene Instanz
  • Aliasing mit Mutieren-dann-Prüfen-Sequenzen am anderen Halter testen, und die Reihenfolge von Aufrufen prüfen, die zwischendurch legitim schreiben könnten
  • Gespeicherte Ausgabe zu vergleichen beweist hier nichts: geteilte und kopierte Werte serialisieren identisch, bis zur ersten Änderung

PDFlibPas exponiert Seitenbaum-Editing, dokumentübergreifendes Kopieren und Seitenbox-Steuerung über eine einzige TPDFlib-Klasse für Delphi, C++Builder und Free Pascal. Editionen, Plattformen und die vollständige API-Referenz finden Sie auf der Produktseite der PDFlibPas-Delphi-PDF-Bibliothek