Dans PDFlibPas, la bibliothèque PDF Delphi, une page déplacée avec MovePage obtient ses propres copies des valeurs MediaBox, CropBox et Resources qu'elle a héritées de son ancien nœud Pages, et une référence indirecte reste une référence. Remettre à la page déplacée les objets mêmes que détient l'ancien nœud Pages est l'implémentation évidente, et cela signifie qu'un SetPageBox ou DrawText ultérieur sur la page déplacée réécrit en silence ce nœud et chaque frère qui en hérite encore. La même règle copier-sans-partager couvre deux chemins liés : SetPageBox sur une box indirecte que plusieurs pages partagent, et CopyPageRanges, qui matérialise les valeurs héritées sur les pages du document source
Les symptômes de ce genre d'aliasing ne mentionnent jamais l'identité d'objets. Ils sonnent comme « j'ai rogné la page 7 et les pages 8 à 12 se sont rognées aussi », ou « j'ai rétréci le CropBox et le MediaBox a bougé avec », ou, le plus déroutant, « j'ai copié une page dans un nouveau document et le fichier d'origine a changé ». Rien ne plante, rien ne fuit, et le fichier sauvegardé est un PDF parfaitement valide. Il contient juste de la géométrie que personne n'a demandée
Comment un SetPageBox sur une page peut-il redimensionner ses frères ?
Cela arrive quand deux entrées de l'arbre de pages pointent un seul tableau en mémoire et que SetPageBox édite son tableau cible sur place : toute page ou nœud Pages détenant la même instance voit l'édition. Trois chemins de code d'un éditeur d'arbre de pages peuvent produire ce partage :
MovePagematérialise les attributs héritables sur la page avant de la détacher de son parent ; attacher les objets propres de l'ancêtre plutôt que des copies laisse la page déplacée et ses anciens frères partager un tableau de box et un dictionnaire Resources- Un écrivain de box qui suit les références indirectes et édite le tableau référencé redimensionne chaque page qui pointe un objet
/MediaBox 11 0 Ren un seul appel, queMovePageait jamais joué ou non CopyPageRangesmatérialise les valeurs héritées sur la page source avant de la cloner dans le document cible ; attacher les instances de nœuds Pages à la page source, plus l'instance MediaBox elle-même comme CropBox par défaut, les noue tous ensemble
La matérialisation elle-même n'est pas optionnelle. Ne porter que /Resources et une page déplacée sous un parent différent prend en silence la taille et la rotation de ce parent, donc MovePage porte aussi MediaBox, CropBox et Rotate, ce sur quoi compte aussi CollateDocumentsEx quand il réordonne des pages. La seule question est de savoir si ces valeurs arrivent en copies ou en instances partagées
Valeurs directes, références indirectes et héritage des attributs de page
Une copie correcte d’un attribut de page hérité duplique les valeurs directes et garde les références indirectes comme références, parce que c’est la distinction que ISO 32000-1 lui-même trace. Un objet direct tel que [0 0 400 300] écrit dans un dictionnaire n’appartient qu’à ce dictionnaire. Un objet indirect, défini une fois en 11 0 obj et cité en 11 0 R, est partagé par conception : ISO 32000-1 §7.3.10 le rend adressable depuis n’importe où dans le fichier, et chaque 11 0 R désigne le même objet
L’héritage des attributs de page, ISO 32000-1 §7.7.3.4, ajoute un troisième cas. Resources, MediaBox, CropBox et Rotate peuvent siéger sur un nœud Pages et s’appliquer à toute page descendante qui ne définit pas les siens. La page ne détient pas la valeur ; elle la cherche à travers /Parent. Cette chaîne de recherche casse dès qu’une page change de parent, c’est pourquoi MovePage et BalancePageTree doivent d’abord écrire les valeurs effectives sur la page elle-même. La seule question est de savoir comment les écrire
Pourquoi un pool d’objets cache l’erreur
Dans PDFlibPas, chaque objet PDF analysé ou créé est possédé par le pool TPDFStructure du document, et les dictionnaires et tableaux stockent de simples pointeurs vers leurs entrées. TPDFDictionary.Add enregistre le pointeur et rien d’autre. Ajouter une instance à deux conteneurs parents est donc légal à chaque niveau que le runtime peut vérifier : pas de double libération au démontage, pas de comptage de références qui puisse dérailler, pas d’exception. La sérialisation est tout aussi conciliante, puisque chaque conteneur écrit en ligne la valeur courante de l’instance partagée, et avant toute modification la sortie est octet pour octet ce qu’une copie correcte produirait
L’aliasing ne se manifeste que quand quelqu’un mute l’instance partagée sur place. SetPageBox fait exactement ça par un wrapper rectangle au-dessus du tableau existant, et dessiner sur une page le fait au dictionnaire Resources quand une police ou une image est enregistrée. La modification atterrit, en silence, dans tous les autres conteneurs qui détiennent le pointeur
Comment PDFlibPas copie au lieu de partager
PDFlibPas traite le problème aux deux bouts : la matérialisation attache des copies, et les écritures de box n'éditent qu'un tableau que la page possède. Chaque règle couvre un cas que l'autre ne peut pas
Le helper de matérialisation, PLInheritPageAttributes, attache Page.Owner.Decode(Value.Output) plutôt que Value lui-même. Faire l'aller-retour par le sérialiseur est une manière brutale mais exacte d'obtenir la sémantique PDF gratuitement. Un tableau ou dictionnaire direct se sérialise en son texte littéral et se décode en une instance fraîche et indépendante. Une référence indirecte se sérialise en 11 0 R et se décode en un nouvel objet référence pointant le même objet 11, donc la page se réfère toujours à l'objet partagé au lieu de recevoir une copie inlinée. La copie est exactement aussi profonde que la structure directe : tout ce qui est atteint par une référence à l'intérieur d'un dictionnaire copié reste partagé, comme le format de fichier le veut. BalancePageTree appelle le même helper pour chaque page qu'il reparente, donc les pages matérialisées là obtiennent aussi des instances séparées
Copier seul ne suffit pas, parce que le cas référence pointe toujours un objet partagé. Si SetPageBox suivait cette référence et éditait l'objet 11, la page déplacée redimensionnerait de nouveau l'ancien parent et ses autres enfants. Donc l'écrivain de box applique le copy-on-write : il n'édite sur place que quand l'entrée propre de la page est un tableau direct, et remplace une box indirecte ou manquante par un nouveau tableau direct. L'objet 11 reste intact pour toute autre page qui le cite
| Chemin de code | Instances partagées (le piège) | PDFlibPas |
|---|---|---|
Matérialisation MovePage | La page tient les instances directes propres de l'ancêtre | La page tient des copies décodées ; les références restent des références |
SetPageBox | Suit une référence et édite le tableau partagé | N'édite qu'un tableau direct sur la page, sinon en écrit un nouveau |
Page source de CopyPageRanges | Partage les boxes du nœud Pages ; le CropBox est l'instance MediaBox | Chaque valeur matérialisée sur la page source est une copie |
| Boxes par défaut au clonage des ressources de page | CropBox, BleedBox, TrimBox et ArtBox partagent un tableau | Chaque box par défaut obtient son propre tableau |
La dernière ligne est la subtile. Quand la bibliothèque clone les ressources d'une page pour capture ou fusion de pages, elle remplit les entrées CropBox, BleedBox, TrimBox et ArtBox manquantes, et remplir les quatre depuis une instance de tableau laisserait un alias qui attend le premier appelant qui en éditerait une. Comment ces valeurs de box par défaut sont choisies est un sujet à part, couvert dans le guide PDFlibPas des défauts TrimBox, BleedBox et CropBox
Reproduire l’aliasing MovePage avec un PDF fait main
La manière la plus rapide de tester du code d'édition d'arbre de pages contre l'aliasing est un petit PDF écrit à la main chargé avec LoadFromString, où chaque numéro d'objet est connu d'avance. Le helper ci-dessous écrit une table de références croisées classique avec des décalages d'octets correctement calculés, pour que le test ne dépende pas du comportement de récupération de l'analyseur sur les fichiers endommagés
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); // offset d’octet base 0 de "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 // chaque entrée fait exactement 20 octets
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;
Le document de test a deux nœuds Pages intermédiaires. Le nœud 3 porte un MediaBox indirect (objet 11, 400 par 300 points), un CropBox direct et un dictionnaire Resources direct, et possède deux pages. Le nœud 4 a un MediaBox format Letter et possède la troisième page. Déplacer la page 1 en position 3 la reparente sous le nœud 4, exactement le déplacement qui exige une matérialisation : sans elle, la page deviendrait une page Letter
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); // la page qu’on vient de déplacer
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');
// Inspectez l’ancien parent AVANT de sélectionner une autre page (voir plus bas)
Check(Pos(AnsiString('/Font'), Lib.GetObjectToString(3)) = 0,
'font registered in the old Pages node');
Lib.SelectPage(1); // ancienne page 2, toujours sous le nœud 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) prend le type de box 1 pour MediaBox et 2 pour CropBox, et la dimension 2 pour la largeur. Avec l'origine bas-gauche par défaut, SetPageBox(1, 0, 200, 200, 200) signifie gauche 0, haut 200, 200 de large et 200 de haut. Avec un matérialiseur qui partage des instances, les contrôles de frères échouent : l'édition du CropBox atterrit dans le tableau direct du nœud 3, et un écrivain de box qui suit les références réécrit l'objet 11
CopyPageRanges modifie-t-il le document source ?
CopyPageRanges écrit bien sur les pages sources, mais chaque valeur qu'il écrit est une copie séparée, donc les éditions ultérieures sur la source restent locales à la page que vous éditez. L'écriture elle-même est intentionnelle : la page source a besoin de MediaBox, CropBox, Rotate et Resources explicites avant que son dictionnaire soit cloné dans la cible, sinon la copie perdrait tout ce qu'elle avait hérité. La renumérotation et la copie de la page dans la cible sont couvertes dans la copie profonde d'objets entre documents dans PDFlibPas ; le piège ici siège du côté source, que la plupart des gens supposent qu'une copie ne fait que lire
La sortie sauvegardée ne le montre jamais. Partagées ou copiées, les valeurs matérialisées se sérialisent à l'identique, donc les deux documents se sauvegardent octet pour octet de la même manière dans tous les cas. Seule une édition du document source après la copie révèle un 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; // devient le document sélectionné
Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');
Lib.SelectDocument(SourceID);
Lib.SelectPage(1);
Lib.SetPageBox(2, 50, 250, 100, 100); // ne rétrécit que le CropBox
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); // la copie garde sa taille d’origine
Lib.SelectPage(Lib.PageCount);
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'copied page resized');
finally
Lib.Free;
end;
end;
Les deux pages ici héritent du MediaBox direct du nœud racine. Une étape de copie qui attacherait cette instance à la page source 1, et l'attacherait de nouveau comme CropBox de la page 1, ferait que rétrécir le CropBox rétrécit le MediaBox, et que redimensionner le MediaBox redimensionne la page 2 à travers le nœud racine. Les flux qui copient des pages puis continuent d'éditer la source, comme la collation de scans duplex en un seul PDF avant de rogner les originaux, sont l'endroit où ce genre d'alias surgit
Pourquoi l’aliasing d’instances est-il si difficile à tester ?
L’aliasing d’instances est difficile à tester parce que l’effet observable exige trois étapes dans un ordre précis : créer l’alias, muter un côté, puis inspecter l’autre côté avant que quoi que ce soit d’autre n’y touche. La plupart des tests ne font que la première étape et comparent la sortie sauvegardée, identique que l’alias existe ou non
Le piège d'ordre dans PDFlibPas est SelectPage. Sélectionner une page réapplique la police courante via SelectFont, qui enregistre cette police dans les ressources de la page. Une page sans /Resources propre se résout au dictionnaire de son parent, donc simplement sélectionner une telle page ajoute légitimement /Font au nœud Pages. Dans le test MovePage ci-dessus, sélectionner l'ancienne page 2 ajoute l'entrée Helvetica au nœud 3, ce qui est un comportement correct et pas une fuite. Voilà pourquoi le contrôle GetObjectToString(3) tourne avant SelectPage(1) ; échangez les deux et le test échoue même sans aucun alias
Cette règle marque aussi ce que PDFlibPas laisse délibérément tranquille. Écrire une ressource sur une page qui hérite son dictionnaire Resources écrit dans le dictionnaire de l'ancêtre, et chaque frère voit la nouvelle entrée. C'est l'héritage qui marche comme spécifié, pas du partage d'instances, et c'est inoffensif car ajouter un nom de police ou d'image à un dictionnaire partagé ne change pas le rendu des autres pages. Si vous avez besoin qu'une page cesse d'hériter, donnez-lui d'abord son propre dictionnaire Resources
Checklist pour le code de modèle objet PDF
Les leçons se généralisent à tout modèle objet PDF bâti sur un pool et des conteneurs de pointeurs, en Delphi ou ailleurs :
- En matérialisant les attributs hérités selon ISO 32000-1 §7.7.3.4, copiez en profondeur les valeurs directes et gardez les références indirectes comme nouvelles références vers le même objet
- Ne faites jamais
Addd'une instance existante dans un second conteneur sauf si le partage est voulu et documenté ; la possession par un pool signifie que le runtime ne se plaindra jamais - N'éditez sur place que ce que le nœud courant possède comme objet direct ; remplacez les valeurs indirectes ou héritées par un objet direct frais (copy-on-write)
- Les valeurs par défaut dérivées d'une autre entrée, comme un CropBox depuis un MediaBox, ont besoin de leur propre instance
- Testez l'aliasing avec des séquences muter-puis-inspecter chez l'autre détenteur, et vérifiez l'ordre des appels qui pourraient écrire légitimement entre-temps
- Comparer la sortie sauvegardée ne prouve rien ici : valeurs partagées et copiées se sérialisent à l'identique jusqu'à la première édition
PDFlibPas expose l’édition de l’arbre de pages, la copie entre documents et le contrôle des boxes de page par une seule classe TPDFlib pour Delphi, C++Builder et Free Pascal. Voyez la page produit de la bibliothèque PDF Delphi PDFlibPas pour les éditions, les plateformes et la référence API complète