No PDFlibPas, a biblioteca PDF Delphi, uma página movida com MovePage ganha cópias próprias dos valores MediaBox, CropBox e Resources que herdou do seu antigo node Pages, e uma referência indireta continua referência. Entregar à página movida exatamente os mesmos objetos que o antigo node Pages segura é a implementação óbvia, e significa que um SetPageBox ou DrawText posterior na página movida reescreve silenciosamente aquele node e todo irmão que ainda herda dele. A mesma regra de copiar-e-não-compartilhar cobre dois caminhos relacionados: SetPageBox sobre uma caixa indireta que várias páginas compartilham, e CopyPageRanges, que materializa valores herdados nas páginas do documento de origem
Sintomas desse tipo de aliasing nunca mencionam identidade de objeto. Soam como "cortei a página 7 e as páginas 8 a 12 foram cortadas também", ou "estreitei o CropBox e o MediaBox se moveu junto", ou, a mais confusa, "copiei uma página para um novo documento e o arquivo original mudou". Nada quebra, nada vaza, e o arquivo salvo é PDF perfeitamente válido. Ele só contém geometria que ninguém pediu
Como o SetPageBox em uma página pode redimensionar as irmãs?
Acontece quando duas entradas da árvore de páginas apontam para um mesmo array em memória e o SetPageBox edita o array alvo no lugar: toda página ou node Pages que segura a mesma instância vê a edição. Três caminhos de código em um editor de árvore de páginas podem produzir esse compartilhamento:
- O
MovePagematerializa os atributos herdáveis na página antes de destacá-la do seu pai; anexar os objetos do próprio ancestral em vez de cópias deixa a página movida e os seus ex-irmãos compartilhando um array de caixa e um dicionário Resources - Um escritor de caixas que segue referências indiretas e edita o array referenciado redimensiona toda página que aponta para um único objeto
/MediaBox 11 0 Rcom uma única chamada, tenha oMovePageparticipado ou não - O
CopyPageRangesmaterializa valores herdados na página de origem antes de cloná-la no documento alvo; anexar as instâncias do node Pages à página de origem, mais a própria instância do MediaBox como CropBox padrão, amarra todas elas juntas
A materialização em si não é opcional. Levar apenas /Resources adiante e uma página movida para sob um pai diferente assume silenciosamente o tamanho e a rotação desse pai, então o MovePage leva MediaBox, CropBox e Rotate também, o que é também no que o CollateDocumentsEx se apoia quando reordena páginas. A única questão é se esses valores chegam como cópias ou como instâncias compartilhadas
Valores diretos, referências indiretas e herança de atributos de página
Uma cópia correta de um atributo de página herdado duplica valores diretos e mantém referências indiretas como referências, porque essa é a distinção que a própria ISO 32000-1 traça. Um objeto direto como [0 0 400 300] escrito dentro de um dicionário pertence só a esse dicionário. Um objeto indireto, definido uma vez como 11 0 obj e citado como 11 0 R, é compartilhado por design: a ISO 32000-1 §7.3.10 o torna endereçável de qualquer lugar do arquivo, e todo 11 0 R significa o mesmo objeto
A herança de atributos de página, ISO 32000-1 §7.7.3.4, acrescenta um terceiro caso. Resources, MediaBox, CropBox e Rotate podem morar num Pages node e valer para toda página descendente que não defina os próprios. A página não segura o valor; ela o procura através do /Parent. Essa cadeia de lookup quebra no instante em que uma página troca de pai, e é por isso que o MovePage e o BalancePageTree precisam primeiro gravar os valores efetivos na própria página. A questão é só como gravá-los
Por que um pool de objetos esconde o erro
No PDFlibPas todo objeto de PDF parseado ou criado é de propriedade do pool TPDFStructure do documento, e dicionários e arrays guardam ponteiros crus para as entradas deles. O TPDFDictionary.Add registra o ponteiro e mais nada. Adicionar uma instância a dois containers pais é portanto legal em todo nível que o runtime consegue checar: nenhum double free no teardown, nenhum reference count para dar errado, nenhuma exceção. A serialização é igualmente condescendente, já que cada container grava o valor atual da instância compartilhada inline, e antes de qualquer edição o output é byte a byte o que uma cópia correta produziria
O aliasing só aparece quando alguém muta a instância compartilhada no lugar. O SetPageBox faz exatamente isso através de um wrapper de retângulo sobre o array existente, e desenhar numa página faz isso com o dicionário Resources quando uma fonte ou imagem é registrada. A edição pousa, silenciosamente, em todo outro container que segura o ponteiro
Como o PDFlibPas copia em vez de compartilhar
O PDFlibPas trata o problema nas duas pontas: a materialização anexa cópias, e as escritas de caixa editam apenas um array que a página possui. Cada regra cobre um caso que a outra não consegue
O helper de materialização, o PLInheritPageAttributes, anexa Page.Owner.Decode(Value.Output) em vez do próprio Value. Fazer round-trip pelo serializador é uma forma bruta mas exata de ganhar a semântica de PDF de graça. Um array ou dicionário direto serializa para o seu texto literal e decodifica em uma instância nova e independente. Uma referência indireta serializa para 11 0 R e decodifica em um novo objeto de referência apontando para o mesmo objeto 11, então a página ainda se refere ao objeto compartilhado em vez de receber uma cópia inline. A cópia é exatamente tão profunda quanto a estrutura direta: qualquer coisa alcançada através de uma referência dentro de um dicionário copiado permanece compartilhada, como o formato de arquivo pretende. O BalancePageTree chama o mesmo helper para toda página que ele re-parenta, então páginas materializadas ali também ganham instâncias separadas
Copiar sozinho não basta, porque o caso da referência ainda aponta para um objeto compartilhado. Se o SetPageBox seguisse essa referência e editasse o objeto 11, a página movida novamente redimensionaria o pai antigo e os seus outros filhos. Então o escritor de caixas aplica copy-on-write: ele edita no lugar apenas quando a própria entrada da página é um array direto, e substitui uma caixa indireta ou ausente por um novo array direto. O objeto 11 fica intocado para toda outra página que o cita
| Caminho de código | Compartilhando instâncias (a armadilha) | PDFlibPas |
|---|---|---|
Materialização do MovePage | A página segura as próprias instâncias diretas do ancestral | A página segura cópias decodificadas; referências continuam referências |
SetPageBox | Segue uma referência e edita o array compartilhado | Edita só um array direto na página, caso contrário escreve um novo |
Página de origem do CopyPageRanges | Compartilha as caixas do Pages node; o CropBox é a instância do MediaBox | Todo valor materializado na página de origem é uma cópia |
| Caixas default ao clonar resources de página | CropBox, BleedBox, TrimBox e ArtBox compartilham um array | Cada caixa default ganha o próprio array |
A última linha é a sutil. Quando a biblioteca clona os recursos de uma página para captura de página ou mesclagem, ela preenche as entradas ausentes de CropBox, BleedBox, TrimBox e ArtBox, e preencher as quatro a partir de uma instância de array deixaria um alias esperando o primeiro chamador que editar uma delas. Como esses valores de caixa padrão são escolhidos é um tópico próprio, coberto em o guia do PDFlibPas para padrões de TrimBox, BleedBox e CropBox
Reproduzindo o aliasing do MovePage com um PDF escrito à mão
O caminho mais rápido para testar código de edição de árvore de páginas contra aliasing é um pequeno PDF escrito à mão carregado com LoadFromString, em que cada número de objeto é conhecido de antemão. O helper abaixo escreve uma tabela de cross-reference clássica com offsets de bytes corretamente calculados, então o teste não depende do comportamento de recuperação do parser para arquivos danificados
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 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 // cada entrada tem exatamente 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;
O documento de teste tem dois nodes Pages intermediários. O node 3 carrega um MediaBox indireto (objeto 11, 400 por 300 pontos), um CropBox direto e um dicionário Resources direto, e possui duas páginas. O node 4 tem um MediaBox tamanho Letter e possui a terceira página. Mover a página 1 para a posição 3 a coloca de novo sob o node 4, que é exatamente o movimento que precisa de materialização: sem ela, a página viraria uma 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); // a 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');
// Inspecione o pai antigo ANTES de selecionar outra página (veja abaixo)
Check(Pos(AnsiString('/Font'), Lib.GetObjectToString(3)) = 0,
'font registered in the old Pages node');
Lib.SelectPage(1); // ex-página 2, ainda sob o node 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;
O GetPageBox(BoxType, Dimension) recebe tipo de caixa 1 para MediaBox e 2 para CropBox, e dimensão 2 para largura. Com a origem padrão no canto inferior esquerdo, SetPageBox(1, 0, 200, 200, 200) significa esquerda 0, topo 200, 200 de largura e 200 de altura. Com um materializador que compartilha instâncias, as checagens de irmão falham: a edição do CropBox pousa no array direto do node 3, e um escritor de caixas que segue referências reescreve o objeto 11
O CopyPageRanges muda o documento de origem?
O CopyPageRanges escreve nas páginas de origem sim, mas todo valor que ele escreve é uma cópia separada, então edições posteriores na origem ficam locais à página que você edita. A escrita em si é intencional: a página de origem precisa de MediaBox, CropBox, Rotate e Resources explícitos antes de o seu dicionário ser clonado para o alvo, caso contrário a cópia perderia tudo o que herdou. A renumeração e a cópia da página para o alvo estão cobertas em cópia profunda de objetos entre documentos no PDFlibPas; a armadilha aqui fica do lado da origem, que a maioria assume que uma cópia apenas lê
A saída salva nunca mostra isso. Compartilhado ou copiado, os valores materializados serializam identicamente, então os dois documentos salvam byte a byte iguais de qualquer forma. Só uma edição no documento de origem depois da cópia revela um 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; // vira o documento selecionado
Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');
Lib.SelectDocument(SourceID);
Lib.SelectPage(1);
Lib.SetPageBox(2, 50, 250, 100, 100); // estreita só o 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); // a cópia mantém o tamanho original
Lib.SelectPage(Lib.PageCount);
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'copied page resized');
finally
Lib.Free;
end;
end;
Ambas as páginas aqui herdam o MediaBox direto do node raiz. Um passo de cópia que anexasse essa instância à página de origem 1, e a anexasse de novo como CropBox da página 1, faria estreitar o CropBox estreitar o MediaBox, e redimensionar o MediaBox redimensionar a página 2 através do node raiz. Fluxos de trabalho que copiam páginas para fora e depois continuam editando a origem, como colar varreduras duplex em um único PDF antes de aparar os originais, são onde esse tipo de alias aparece
Por que aliasing de instância é tão difícil de testar?
Aliasing de instância é difícil de testar porque o efeito observável precisa de três passos numa ordem específica: criar o alias, mutar um lado, depois inspecionar o outro lado antes que qualquer outra coisa o toque. A maioria dos testes faz só o primeiro passo e compara o output salvo, que é idêntico exista o alias ou não
A armadilha de ordenação no PDFlibPas é o SelectPage. Selecionar uma página re-aplica a fonte atual via SelectFont, que registra essa fonte nos recursos da página. Uma página sem /Resources próprio resolve para o dicionário do pai, então simplesmente selecionar tal página legitamente adiciona /Font ao node Pages. No teste de MovePage acima, selecionar a ex-página 2 adiciona a entrada Helvetica ao node 3, o que é comportamento correto e não um leak. É por isso que a checagem GetObjectToString(3) roda antes do SelectPage(1); inverta os dois e o teste falha mesmo sem alias nenhum
Essa regra também marca o que o PDFlibPas deliberadamente deixa em paz. Escrever um recurso em uma página que herda o dicionário Resources dela escreve no dicionário do ancestral, e todo irmão vê a nova entrada. Isso é herança funcionando como especificado, não compartilhamento de instância, e é inofensivo porque adicionar um nome de fonte ou imagem a um dicionário compartilhado não muda como outras páginas renderizam. Se você precisa que uma página pare de herdar, dê a ela um dicionário Resources próprio primeiro
Checklist para código de modelo de objetos de PDF
As lições se generalizam para qualquer modelo de objetos de PDF construído sobre um pool e containers de ponteiros, em Delphi ou fora dele:
- Ao materializar atributos herdados conforme a ISO 32000-1 §7.7.3.4, faça deep copy dos valores diretos e mantenha referências indiretas como referências novas para o mesmo objeto
- Nunca faça
Addde uma instância existente a um segundo container a menos que o compartilhamento seja intencional e documentado; a propriedade por um pool significa que o runtime nunca vai reclamar - Edite no lugar só o que o node atual possui como objeto direto; substitua valores indiretos ou herdados por um objeto direto novo (copy-on-write)
- Valores default derivados de outra entrada, como um CropBox de um MediaBox, precisam da própria instância
- Teste aliasing com sequências de mutar-para-inspecionar no outro holder, e confira a ordem de chamadas que podem gravar legitimamente no meio do caminho
- Comparar output salvo não prova nada aqui: valores compartilhados e copiados serializam identicamente até a primeira edição
O PDFlibPas expõe edição de page tree, cópia entre documentos e controle de caixas de página através de uma única classe TPDFlib para Delphi, C++Builder e Free Pascal. Veja a página de produto da biblioteca de PDF PDFlibPas para Delphi para edições, plataformas e a referência completa de API