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:
MovePagematerializa 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 Rcon una sola llamada, haya participadoMovePageo no CopyPageRangesmaterializa 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
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
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
| Ruta de código | Compartir instancias (la trampa) | PDFlibPas |
|---|---|---|
MovePage materialización | La página sostiene las instancias directas propias del ancestro | La página sostiene copias decodificadas; las referencias siguen siendo referencias |
SetPageBox | Sigue una referencia y edita el arreglo compartido | Edita solo un arreglo directo en la página, si no, escribe uno nuevo |
Página de origen de CopyPageRanges | Comparte las cajas del nodo Pages; la CropBox es la instancia MediaBox | Cada valor materializado en la página de origen es una copia |
| Cajas por defecto al clonar recursos de página | CropBox, BleedBox, TrimBox y ArtBox comparten un arreglo | Cada 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
Addde 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