Artículo técnico

PDFlibPas MovePage: cajas heredadas que comparten instancias

En PDFlibPas, la librería PDF para Delphi, una página movida con MovePage recibe copias propias de los valores MediaBox, CropBox y Resources que heredó de su viejo nodo Pages, y una referencia indirecta se queda siendo referencia. Entregar a la página movida los mismos objetos que sostiene el viejo nodo Pages es la implementación obvia, y significa que un posterior SetPageBox o DrawText sobre la página movida reescribe en silencio ese nodo y cada hermana que aún herede de él. La misma regla de copiar-en-lugar-de-compartir cubre dos caminos relacionados: SetPageBox sobre una caja indirecta que varias páginas comparten, y CopyPageRanges, que materializa los valores heredados sobre las páginas del documento fuente

Los síntomas de este tipo de aliasing nunca mencionan identidad de objetos. Suenan como «recorté la página 7 y las páginas 8 a 12 se recortaron también», o «estreché la CropBox y la MediaBox se movió con ella», o, la más desconcertante, «copié una página a un documento nuevo y el archivo original cambió». Nada crashea, nada fuga, y el archivo guardado es PDF perfectamente válido. Solo contiene una geometría que nadie pidió

¿Cómo puede SetPageBox en una página redimensionar a sus hermanas?

Pasa cuando dos entradas del árbol de páginas apuntan a un mismo array en memoria y SetPageBox edita su array objetivo en el sitio: cualquier página o nodo Pages que sostenga la misma instancia ve la edición. Tres caminos de código en un editor de árboles de páginas pueden producir ese compartimiento:

  • MovePage materializa los atributos heredables sobre la página antes de despegarla de su padre; colgar los objetos del ancestro en lugar de copias deja a la página movida y a sus antiguas hermanas compartiendo un array de caja y un diccionario Resources
  • Un escritor de cajas que sigue las referencias indirectas y edita el array referenciado redimensiona cada página que apunte a un objeto /MediaBox 11 0 R con una sola llamada, haya intervenido MovePage o no
  • CopyPageRanges materializa los valores heredados sobre la página fuente antes de clonarla al documento destino; colgar las instancias del nodo Pages sobre la página fuente, más la propia instancia del MediaBox como CropBox por defecto, ata todas entre sí
Peligro de aliasing de MovePage donde una página movida y su antigua hermana sostienen ambas la instancia del array MediaBox del ancestro, así que SetPageBox edita una página y redimensiona la otra; la materialización de PDFlibPas cuelga copias decodificadas para que las ediciones se queden locales en la página que tocas
Dos entradas del árbol de páginas apuntando a un mismo array en memoria hacen que cada edición aterrice en todos los portadores, y el PDF guardado sigue siendo válido todo el tiempo

La materialización en sí no es opcional. Cargar solo /Resources hace que una página movida bajo otro padre adopte en silencio el tamaño y la rotación de ese padre, así que MovePage lleva también MediaBox, CropBox y Rotate, que es en lo que se apoya CollateDocumentsEx cuando reordena páginas. La única pregunta es si esos valores llegan como copias o como instancias compartidas

Valores directos, referencias indirectas y herencia de atributos de página

Una copia correcta de un atributo de página heredado duplica los valores directos y conserva las referencias indirectas como referencias, porque esa es la distinción que el propio ISO 32000-1 traza. Un objeto directo como [0 0 400 300] escrito dentro de un diccionario pertenece solo a ese diccionario. Un objeto indirecto, definido una vez como 11 0 obj y citado como 11 0 R, se comparte por diseño: ISO 32000-1 §7.3.10 lo hace direccionable desde cualquier parte del archivo, y cada 11 0 R significa el mismo objeto

La herencia de atributos de página, ISO 32000-1 §7.7.3.4, añade un tercer caso. Resources, MediaBox, CropBox y Rotate pueden sentarse en un nodo Pages y aplicarse a toda página descendiente que no defina los suyos. La página no sostiene el valor; lo consulta a través de /Parent. Esa cadena de consulta se rompe en cuanto una página cambia de padre, que es por lo que MovePage y BalancePageTree deben escribir primero los valores efectivos sobre la propia página. La cuestión es solo cómo escribirlos

Por qué un pool de objetos esconde el error

En PDFlibPas cada objeto PDF parseado o creado es propiedad del pool TPDFStructure del documento, y los diccionarios y arrays guardan punteros simples a sus entradas. TPDFDictionary.Add registra el puntero y nada más. Añadir una instancia a dos contenedores padre es por tanto legal en todos los niveles que el runtime puede comprobar: sin doble liberación al desmontar, sin recuento de referencias que se equivoque, sin excepción. La serialización es igual de indulgente, pues cada contenedor escribe el valor actual de la instancia compartida en línea, y antes de cualquier edición el resultado es byte a byte lo que produciría una copia correcta

El aliasing solo sale a la luz cuando alguien muta la instancia compartida en el sitio. SetPageBox hace exactamente eso a través de un envoltorio rectángulo sobre el array existente, y dibujar en una página lo hace con el diccionario Resources cuando se registra una fuente o una imagen. La edición aterriza, en silencio, en todos los demás contenedores que sostienen el puntero

Cómo copia PDFlibPas en lugar de compartir

PDFlibPas trata el problema por los dos extremos: la materialización cuelga copias, y las escrituras de cajas editan solo un array que la página posee. Cada regla cubre un caso que la otra no puede

El ayudante de materialización, PLInheritPageAttributes, cuelga Page.Owner.Decode(Value.Output) en lugar del propio Value. El viaje de ida y vuelta por el serializador es una forma contundente pero exacta de conseguir la semántica PDF gratis. Un array o diccionario directo se serializa a su texto literal y se decodifica en una instancia nueva e independiente. Una referencia indirecta se serializa a 11 0 R y se decodifica en un objeto de referencia nuevo que apunta al mismo objeto 11, así que la página sigue refiriendo al objeto compartido en lugar de recibir una copia incrustada. La copia es exactamente tan profunda como la estructura directa: lo que se alcance a través de una referencia dentro de un diccionario copiado sigue compartido, como pretende el formato de archivo. BalancePageTree llama al mismo ayudante por cada página que re-engancha, así que las páginas materializadas allí también obtienen instancias separadas

Viaje de ida y vuelta de la materialización en PDFlibPas donde PLInheritPageAttributes cuelga Page.Owner.Decode(Value.Output): un array directo se serializa a texto literal y se decodifica en una instancia nueva, mientras que una referencia indirecta 11 0 R se serializa y decodifica en una referencia nueva que sigue apuntando al objeto 11 compartido
Serializar y re-parsear consigue gratis la semántica de objetos PDF: los valores directos se copian, las referencias siguen siendo referencias, exactamente como pretende ISO 32000-1

Copiar solo no basta, porque el caso de la referencia sigue apuntando a un objeto compartido. Si SetPageBox siguiera esa referencia y editara el objeto 11, la página movida volvería a redimensionar al viejo padre y a sus demás hijos. Así que el escritor de cajas aplica copy-on-write: edita en el sitio solo cuando la entrada propia de la página es un array directo, y reemplaza una caja indirecta o ausente con un nuevo array directo. El objeto 11 queda intacto para todas las demás páginas que lo citen

Decisión copy-on-write de SetPageBox en PDFlibPas: cuando la entrada propia de la página es un array directo se edita en el sitio, y cuando es una referencia indirecta o falta el escritor la sustituye por un array directo nuevo de modo que el objeto 11 compartido conserva su valor para las demás páginas que lo citan
Copiar en la materialización no basta mientras haya referencias apuntando a objetos compartidos, así que el escritor de cajas edita solo lo que la página posee
Camino de códigoCompartir instancias (la trampa)PDFlibPas
Materialización de MovePageLa página sostiene las instancias directas del ancestroLa página sostiene copias decodificadas; las referencias se quedan siendo referencias
SetPageBoxSigue una referencia y edita el array compartidoEdita solo un array directo de la página, si no escribe uno nuevo
Página fuente de CopyPageRangesComparte las cajas del nodo Pages; la CropBox es la instancia del MediaBoxCada valor materializado en la página fuente es una copia
Cajas por defecto al clonar recursos de páginaCropBox, BleedBox, TrimBox y ArtBox comparten un arrayCada caja por defecto obtiene su propio array

La última fila es la sutil. Cuando la librería clona los recursos de una página para captura de páginas o fusión, rellena las entradas CropBox, BleedBox, TrimBox y ArtBox ausentes, y rellenar las cuatro desde una instancia de array dejaría un alias esperando al primer caller que edite una de ellas. Cómo se eligen esos valores de caja por defecto es tema propio, cubierto en la guía de PDFlibPas sobre los valores por defecto de TrimBox, BleedBox y CropBox

Reproducir el aliasing de MovePage con un PDF escrito a mano

La manera más rápida de comprobar código de edición de árboles de páginas contra el aliasing es un pequeño PDF escrito a mano y cargado con LoadFromString, donde cada número de objeto se conoce de antemano. El ayudante de abajo escribe una tabla de referencias cruzadas clásica con offsets de byte calculados correctamente, así que el test no depende del comportamiento de recuperación del parser para archivos dañados

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 de byte 0-based 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      // cada entrada mide exactamente 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;

El documento de test tiene dos nodos Pages intermedios. El nodo 3 lleva un MediaBox indirecto (objeto 11, 400 por 300 puntos), un CropBox directo y un diccionario Resources directo, y posee dos páginas. El nodo 4 tiene un MediaBox tamaño Letter y posee la tercera página. Mover la página 1 a la posición 3 la re-parenta bajo el nodo 4, que es justo el movimiento que necesita materialización: sin ella, la página se convertiría en una página 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 página que acabamos de mover
    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');

    // Inspeccione el padre antiguo ANTES de seleccionar otra página (ver abajo)
    Check(Pos(AnsiString('/Font'), Lib.GetObjectToString(3)) = 0,
      'font registered in the old Pages node');

    Lib.SelectPage(1);                       // antigua página 2, todavía bajo el nodo 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) toma tipo de caja 1 para MediaBox y 2 para CropBox, y dimensión 2 para la anchura. Con el origen abajo-izquierda por defecto, SetPageBox(1, 0, 200, 200, 200) significa izquierda 0, arriba 200, 200 de ancho y 200 de alto. Con un materializador que comparte instancias, las comprobaciones de las hermanas fallan: la edición de la CropBox aterriza en el array directo del nodo 3, y un escritor de cajas que sigue referencias reescribe el objeto 11

¿Cambia CopyPageRanges el documento fuente?

CopyPageRanges sí escribe sobre las páginas fuente, pero cada valor que escribe es una copia separada, así que las ediciones posteriores sobre el fuente se quedan locales en la página que editas. La escritura en sí es intencionada: la página fuente necesita MediaBox, CropBox, Rotate y Resources explícitos antes de que su diccionario se clone al destino, si no la copia perdería todo lo que heredaba. La renumeración y la copia de la página al destino están cubiertas en la copia profunda de objetos entre documentos en PDFlibPas; la trampa aquí se sienta en el lado del fuente, que la mayoría asume que una copia solo lee

La salida guardada nunca lo delata. Compartidos o copiados, los valores materializados se serializan idénticos, así que ambos documentos se guardan byte a byte iguales de cualquier manera. Solo una edición sobre el documento fuente tras la copia revela 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;             // pasa a ser el documento seleccionado
    Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');

    Lib.SelectDocument(SourceID);
    Lib.SelectPage(1);
    Lib.SetPageBox(2, 50, 250, 100, 100);    // estrecha solo el 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 copia conserva su tamaño original
    Lib.SelectPage(Lib.PageCount);
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'copied page resized');
  finally
    Lib.Free;
  end;
end;

Ambas páginas de aquí heredan el MediaBox directo del nodo raíz. Un paso de copia que colgara esa instancia sobre la página fuente 1, y la colgara otra vez como CropBox de la página 1, haría que estrechar la CropBox estrechara la MediaBox, y que redimensionar la MediaBox redimensionara la página 2 a través del nodo raíz. Los flujos que copian páginas fuera y siguen editando el fuente, como colateralizar escaneos dúplex en un PDF antes de recortar los originales, son donde este tipo de alias asoma

¿Por qué cuesta tanto testear el aliasing de instancias?

El aliasing de instancias cuesta de testear porque el efecto observable necesita tres pasos en un orden concreto: crear el alias, mutar un lado y luego inspeccionar el otro antes de que nada más lo toque. La mayoría de los tests hacen solo el primer paso y comparan el resultado guardado, que es idéntico exista o no el alias

La trampa de ordenación en PDFlibPas es SelectPage. Seleccionar una página vuelve a aplicar la fuente actual mediante SelectFont, que registra esa fuente en los recursos de la página. Una página sin /Resources propio resuelve al diccionario de su padre, así que simplemente seleccionar tal página añade legítimamente /Font al nodo Pages. En el test de MovePage de arriba, seleccionar la antigua página 2 añade la entrada Helvetica al nodo 3, lo cual es comportamiento correcto y no una fuga. Por eso la comprobación GetObjectToString(3) corre antes de SelectPage(1); intercambia las dos y el test falla aunque no exista ningún alias

Esa regla marca también lo que PDFlibPas deja deliberadamente quieto. Escribir un recurso en una página que hereda su diccionario Resources escribe en el diccionario del ancestro, y cada hermana ve la entrada nueva. Eso es la herencia funcionando según especificación, no compartimiento de instancias, y es inofensivo porque añadir un nombre de fuente o imagen a un diccionario compartido no cambia cómo renderizan las demás páginas. Si necesitas que una página deje de heredar, dale primero su propio diccionario Resources

Lista de comprobación para código con modelo de objetos PDF

Las lecciones se generalizan a cualquier modelo de objetos PDF construido sobre un pool y contenedores de punteros, en Delphi o donde sea:

  • Al materializar atributos heredados según ISO 32000-1 §7.7.3.4, copia en profundidad los valores directos y conserva las referencias indirectas como referencias nuevas al mismo objeto
  • Nunca hagas Add de una instancia existente a un segundo contenedor salvo que el compartimiento esté previsto y documentado; la propiedad por un pool significa que el runtime jamás se quejará
  • Edita en el sitio solo lo que el nodo actual posee como objeto directo; reemplaza los valores indirectos o heredados con un objeto directo nuevo (copy-on-write)
  • Los valores por defecto derivados de otra entrada, como una CropBox a partir de una MediaBox, necesitan su propia instancia
  • Comprueba el aliasing con secuencias de mutar-y-luego-inspeccionar sobre el otro portador, y mira el orden de las llamadas que puedan escribir legítimamente en medio
  • Comparar la salida guardada no prueba nada aquí: los valores compartidos y los copiados se serializan idénticos hasta la primera edición

PDFlibPas expone la edición del árbol de páginas, la copia entre documentos y el control de cajas de página a través de una única clase TPDFlib para Delphi, C++Builder y Free Pascal. Vea la página de producto de la biblioteca PDF PDFlibPas para Delphi para ediciones, plataformas y la referencia completa de la API