Artículo técnico

PDFlibPas MovePage: cajas heredadas que comparten instancias

En PDFlibPas, la biblioteca 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. Entregarle a la página movida los mismos objetos que sostiene el viejo nodo Pages es la implementación obvia, y significa que un SetPageBox o DrawText posterior sobre la página movida reescribe en silencio ese nodo y cada hermana que todavía herede de él. La misma regla de copiar-no-compartir cubre dos rutas relacionadas: SetPageBox sobre una caja indirecta que varias páginas comparten, y CopyPageRanges, que materializa los valores heredados en las páginas del documento de origen

Los síntomas de este tipo de aliasing jamás 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 confusa, «copié una página a un documento nuevo y el archivo original cambió». Nada crashea, nada pierde memoria, y el archivo guardado es PDF perfectamente válido. Solo contiene 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 arreglo en memoria y SetPageBox edita su arreglo objetivo en el lugar: cualquier página o nodo Pages que sostenga la misma instancia ve la edición. Tres rutas de código en un editor de árboles de páginas pueden producir ese compartir:

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

La materialización en sí no es opcional. Cargar solo /Resources a través hace que una página movida bajo un padre distinto adopte en silencio el tamaño y rotación de ese padre, así que MovePage también carga MediaBox, CropBox y Rotate, que es de lo que depende 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 la propia 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, es compartido 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, agrega un tercer caso. Resources, MediaBox, CropBox y Rotate pueden sentarse en un nodo Pages y aplicar a cada página descendiente que no defina los suyos. La página no sostiene el valor; lo busca a través de /Parent. Esa cadena de búsqueda se rompe en el momento en que una página cambia de padre, por eso MovePage y BalancePageTree deben escribir primero los valores efectivos sobre la propia página. La pregunta 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 arreglos almacenan punteros planos a sus entradas. TPDFDictionary.Add registra el puntero y nada más. Agregar una instancia a dos contenedores padres es por tanto legal en cada nivel que el runtime puede verificar: ningún double free al desmontar, ningún conteo de referencias que salga mal, ninguna excepción. La serialización es igual de permisiva, ya que cada contenedor escribe el valor actual de la instancia compartida en línea, y antes de cualquier edición la salida es byte a byte lo que una copia correcta produciría

El aliasing solo sale a la luz cuando alguien muta la instancia compartida en el lugar. SetPageBox hace exactamente eso a través de un wrapper de rectángulo sobre el arreglo existente, y dibujar en una página lo hace al diccionario Resources cuando se registra una fuente o imagen. La edición aterriza, en silencio, en cada otro contenedor que sostenga el puntero

Cómo PDFlibPas copia en lugar de compartir

PDFlibPas maneja el problema por ambos extremos: la materialización adjunta copias, y las escrituras de cajas editan solo un arreglo que la página posee. Cada regla cubre un caso que la otra no puede

El helper de materialización, PLInheritPageAttributes, adjunta Page.Owner.Decode(Value.Output) en lugar del Value mismo. El round trip por el serializador es una forma contundente pero exacta de obtener gratis la semántica PDF. Un arreglo o diccionario directo se serializa a su texto literal y se decodifica en una instancia fresca e independiente. Una referencia indirecta se serializa a 11 0 R y se decodifica en un nuevo objeto de referencia apuntando al mismo objeto 11, así que la página sigue refiriéndose al objeto compartido en lugar de recibir una copia en línea. La copia es exactamente tan profunda como la estructura directa: cualquier cosa alcanzada a través de una referencia dentro de un diccionario copiado permanece compartida, como el formato de archivo lo concibe. BalancePageTree llama al mismo helper para cada página que re-parenta, así que las páginas materializadas ahí también reciben instancias separadas

Round trip de materialización de PDFlibPas donde PLInheritPageAttributes adjunta Page.Owner.Decode(Value.Output): un arreglo directo se serializa a texto literal y se decodifica en una instancia fresca, mientras un 11 0 R indirecto se serializa y decodifica en una referencia nueva que todavía apunta al objeto 11 compartido
Serializar y volver a parsear le da gratis la semántica de objetos PDF: los valores directos se copian, las referencias siguen siendo referencias, exactamente como ISO 32000-1 lo concibe

Copiar solo no basta, porque el caso de referencia todavía apunta a un objeto compartido. Si SetPageBox siguiera esa referencia y editara el objeto 11, la página movida otra vez redimensionaría al padre viejo y a sus otros hijos. Así que el escritor de cajas aplica copy-on-write: edita en el lugar solo cuando la entrada propia de la página es un arreglo directo, y reemplaza una caja indirecta o ausente con un nuevo arreglo directo. El objeto 11 se deja intacto para cada otra página que lo cite

Decisión copy-on-write de SetPageBox en PDFlibPas: cuando la entrada propia de la página es un arreglo directo se edita en el lugar, y cuando es una referencia indirecta o falta, el escritor la reemplaza con un nuevo arreglo directo para que el objeto 11 compartido conserve su valor para cada otra página que lo cite
Copiar en la materialización no basta mientras las referencias todavía apunten a objetos compartidos, así que el escritor de cajas edita solo lo que la página posee
Ruta de códigoCompartir instancias (la trampa)PDFlibPas
MovePage materializaciónLa página sostiene las instancias directas propias del ancestroLa página sostiene copias decodificadas; las referencias siguen siendo referencias
SetPageBoxSigue una referencia y edita el arreglo compartidoEdita solo un arreglo directo en la página, si no, escribe uno nuevo
Página de origen de CopyPageRangesComparte las cajas del nodo Pages; la CropBox es la instancia MediaBoxCada valor materializado en la página de origen es una copia
Cajas por defecto al clonar recursos de páginaCropBox, BleedBox, TrimBox y ArtBox comparten un arregloCada caja por defecto recibe su propio arreglo

La última fila es la sutil. Cuando la biblioteca clona los recursos de una página para captura o combinación de páginas, rellena las entradas CropBox, BleedBox, TrimBox y ArtBox que falten, y rellenar las cuatro desde una instancia de arreglo dejaría un alias esperando al primer llamador 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 de valores por defecto de TrimBox, BleedBox y CropBox

Reproducir el aliasing de MovePage con un PDF hecho a mano

La forma más rápida de probar código de edición de árboles de páginas contra aliasing es un pequeño PDF escrito a mano cargado con LoadFromString, donde cada número de objeto se conoce de antemano. El helper de abajo escribe una tabla de referencias cruzadas clásica con desplazamientos 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);   // desplazamiento 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 es 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 prueba tiene dos nodos Pages intermedios. El nodo 3 carga una MediaBox indirecta (objeto 11, 400 por 300 puntos), una CropBox directa y un diccionario Resources directo, y posee dos páginas. El nodo 4 tiene una 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 exactamente 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 viejo 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);                       // la antes 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 ancho. Con el origen por defecto abajo-izquierda, 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 verificaciones de hermanas fallan: la edición de la CropBox aterriza en el arreglo directo del nodo 3, y un escritor de cajas que sigue referencias reescribe el objeto 11

¿Cambia CopyPageRanges al documento de origen?

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

La salida guardada jamás lo muestra. Compartidos o copiados, los valores materializados se serializan idénticos, así que ambos documentos guardan byte a byte lo mismo de cualquier manera. Solo una edición al documento de origen después de 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;             // se vuelve el documento seleccionado
    Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');

    Lib.SelectDocument(SourceID);
    Lib.SelectPage(1);
    Lib.SetPageBox(2, 50, 250, 100, 100);    // estreche solo la 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 aquí heredan la MediaBox directa del nodo raíz. Un paso de copia que adjuntara esa instancia a la página de origen 1, y la adjuntara otra vez como CropBox de la página 1, haría que estrechar la CropBox estreche la MediaBox, y que redimensionar la MediaBox redimensione la página 2 a través del nodo raíz. Los flujos que copian páginas fuera y luego siguen editando el origen, como colacionar escaneos dúplex en un solo PDF antes de recortar los originales, son donde este tipo de alias aparece

¿Por qué el aliasing de instancias es tan difícil de probar?

El aliasing de instancias es difícil de probar porque el efecto observable necesita tres pasos en un orden específico: crear el alias, mutar un lado, y luego inspeccionar el otro lado antes de que cualquier otra cosa lo toque. La mayoría de los tests solo hacen el primer paso y comparan la salida guardada, que es idéntica exista o no el alias

La trampa de orden en PDFlibPas es SelectPage. Seleccionar una página re-aplica la fuente actual vía SelectFont, que registra esa fuente en los recursos de la página. Una página sin /Resources propia se resuelve al diccionario de su padre, así que simplemente seleccionar una página así agrega legítimamente /Font al nodo Pages. En el test de MovePage de arriba, seleccionar la antes página 2 agrega la entrada Helvetica al nodo 3, que es comportamiento correcto y no un leak. Por eso la verificación GetObjectToString(3) corre antes de SelectPage(1); intercambie las dos y el test falla incluso cuando no existe ningún alias

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

Checklist para código de 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 en otro lado:

  • Al materializar atributos heredados según ISO 32000-1 §7.7.3.4, copie en profundidad los valores directos y conserve las referencias indirectas como nuevas referencias al mismo objeto
  • Jamás haga Add de una instancia existente a un segundo contenedor a menos que el compartir esté previsto y documentado; la propiedad por un pool significa que el runtime jamás se quejará
  • Edite en el lugar solo lo que el nodo actual posee como objeto directo; reemplace valores indirectos o heredados con un objeto directo fresco (copy-on-write)
  • Los valores por defecto derivados de otra entrada, como una CropBox desde una MediaBox, necesitan su propia instancia
  • Pruebe el aliasing con secuencias de mutar-y-luego-inspeccionar sobre el otro portador, y verifique el orden de las llamadas que podrían escribir legítimamente en medio
  • Comparar la salida guardada no prueba nada aquí: los valores compartidos y 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 sola clase TPDFlib para Delphi, C++Builder y Free Pascal. Vea la página del producto de la biblioteca PDF PDFlibPas para Delphi para ediciones, plataformas y la referencia completa de la API