Article technique

MovePage dans PDFlibPas : boxes héritées partagées

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 :

  • MovePage maté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 R en un seul appel, que MovePage ait jamais joué ou non
  • CopyPageRanges maté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
Piège d'aliasing de MovePage où la page déplacée et son ancien frère détiennent tous deux l'instance propre du tableau MediaBox de l'ancêtre, si bien que SetPageBox édite une page et redimensionne l'autre ; la matérialisation PDFlibPas attache des copies décodées pour que les éditions restent locales à la page touchée
Deux entrées d'arbre de pages pointant un seul tableau en mémoire font atterrir chaque édition chez chaque détenteur, et le PDF sauvegardé reste valide tout du long

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

Aller-retour de matérialisation PDFlibPas où PLInheritPageAttributes attache Page.Owner.Decode(Value.Output) : un tableau direct se sérialise en texte littéral et se décode en une instance fraîche, tandis qu’une référence indirecte 11 0 R se sérialise et se décode en une nouvelle référence qui pointe toujours vers l’objet partagé 11
Sérialiser puis reparser donne la sémantique d’objets PDF gratuitement : les valeurs directes se copient, les références restent des références, exactement comme ISO 32000-1 le veut

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

Décision copy-on-write de SetPageBox dans PDFlibPas : quand l’entrée propre de la page est un tableau direct elle est éditée sur place, et quand c’est une référence indirecte ou une absence l’écrivain la remplace par un nouveau tableau direct, si bien que l’objet partagé 11 garde sa valeur pour toute autre page qui le cite
Copier à la matérialisation ne suffit pas tant que des références pointent vers des objets partagés, donc l’écrivain de box n’édite que ce que la page possède
Chemin de codeInstances partagées (le piège)PDFlibPas
Matérialisation MovePageLa page tient les instances directes propres de l'ancêtreLa page tient des copies décodées ; les références restent des références
SetPageBoxSuit 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 CopyPageRangesPartage les boxes du nœud Pages ; le CropBox est l'instance MediaBoxChaque valeur matérialisée sur la page source est une copie
Boxes par défaut au clonage des ressources de pageCropBox, BleedBox, TrimBox et ArtBox partagent un tableauChaque 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 Add d'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