No HotPDF Component, a THotPDF.Resolution define a unidade de desenho: toda coordenada X e Y, toda margem, o tamanho passado ao SetFont, e os resultados de TextWidth e GetWideTextWidth são medidos em 1/Resolution inch. THPDFPage.Width e Height não a seguem e ficam em points, então os limites de layout precisam vir da UserWidth e da UserHeight somente leitura. O motivo habitual para mexer na Resolution é um port: um motor de relatórios que já pensa em 1/96 ou 1/144 inch é mais fácil de mover quando o lado do PDF fala a mesma unidade do que quando todo call site ganha um fator de conversão. Isso funciona bem, desde que você saiba quais números se mudaram para a unidade nova e quais ficaram para trás
O que a THotPDF.Resolution muda de fato?
A THotPDF.Resolution muda só como o HotPDF lê os números que você passa; o PDF que ele grava é o mesmo. O setter tem duas linhas: SetResolution guarda o valor e define DocScale := Value / 72. De então em diante, XProjection e YProjection dividem toda coordenada pelo DocScale a caminho do content stream, e o SetFont divide o tamanho do mesmo jeito antes de registrá-lo. O user space do PDF tem default de 1/72 inch (ISO 32000-1 §8.3.2.3), então na Resolution default de 72 a projeção é a identidade e a 144 uma unidade de desenho é meio point. Nenhuma entrada de /UserUnit é gravada. Esse atributo de página, acrescentado no PDF 1.6, é uma coisa separada que o HotPDF expõe como THPDFPage.SetUserUnit. Um detalhe que pega quem vem dos tutoriais de TextOut: as coordenadas de página correm do canto superior esquerdo com Y crescendo para baixo, porque o YProjection computa o topo da MediaBox menos o Y escalado, e isso vale em toda Resolution
var
Pdf: THotPDF;
Page: THPDFPage;
Margin: Single;
Title: WideString;
begin
Pdf := THotPDF.Create(nil);
try
Pdf.FileName := 'invoice.pdf';
Pdf.Resolution := 144; // 1 unidade de desenho = 1/144 inch
Pdf.BeginDoc;
Page := Pdf.CurrentPage; // A4: Width = 595, UserWidth = 1190
Margin := 144; // um inch em unidades de desenho
Page.SetFont('Arial', [fsBold], 28); // 28/144 inch, uma fonte de 14 pt
Title := 'INVOICE 2026-0417';
// Alinhe à direita contra a borda da página medida na mesma unidade
Page.TextOut(Page.UserWidth - Margin - Page.GetWideTextWidth(Title),
Margin, 0, Title);
Page.SetLineWidth(2); // linha de 1 pt
Page.MoveTo(Margin, Margin + 48);
Page.LineTo(Page.UserWidth - Margin, Margin + 48);
Page.Stroke;
Pdf.EndDoc;
finally
Pdf.Free;
end;
end;
Por que o Page.Width discorda das minhas coordenadas na Resolution 144?
A THPDFPage.Width e a Height reportam a página em points não importa qual seja a Resolution do documento, enquanto suas coordenadas estão em 1/Resolution inch, então a 144 a página parece ter metade da largura real. Uma página A4 lê Width = 595 e Height = 842 na Resolution 72 e ainda lê 595 e 842 a 144, onde a borda direita está de fato em X = 1190. UserWidth e UserHeight, disponíveis desde a v2.766.0, retornam Width * DocScale, que é o tamanho da página na unidade em que você desenha. Misturar as duas e os sintomas na Resolution 144 são dramáticos: parágrafos quebram após cada caractere, uma tabela empurra cada row para uma página nova, e conteúdo importado ou achatado desenha com metade do tamanho, amontoado no canto superior esquerdo. É por isso que layout de parágrafo, renderização de tabelas, importação de HTML, centralização de EMF, o clip de página de WMF e diagnósticos de layout todos leem o tamanho em user unit. Seu próprio código de layout deveria fazer o mesmo: qualquer coisa que compare contra uma coordenada de desenho (uma margem direita, um teste de quebra de página, um cálculo de centralização) pertence à UserWidth e à UserHeight, nunca à Width e à Height
Armadilha um: atribuir Width ou Height muda a página para points
Atribuir à Page.Width ou à Page.Height muda a página silenciosamente para UserDefined, e uma página UserDefined ignora o DocScale por completo, então tudo o que você desenhar nela depois fica em points, não em 1/Resolution inch. O setter recebe points por design. A projeção para uma página UserDefined é X + MinX simples, e o SetFont armazena o tamanho sem alteração. Na Resolution 144 o resultado é uma página cujo conteúdo de repente sai duas vezes maior que o da página anterior. A mesma armadilha espera qualquer código que clona uma página: copiar o tamanho da página anterior através de Width e toda cópia vira uma página em points. As páginas de continuação de parágrafo do HotPDF copiam Size, Orientation e a Resolution da página em vez disso, e só recuam para Width e Height quando a página original já era UserDefined
Duas saídas, dependendo do que você precisa. Se uma folha padrão serve, defina Page.Size e Page.Orientation e continue desenhando na sua unidade de Resolution. Se você realmente precisa de um tamanho de página personalizado, aceite que ela é uma página em points e desenhe em points; UserWidth iguala Width ali, então código de layout que sempre lê UserWidth continua funcionando nos dois tipos de página. Uma checagem rápida mostra: na Resolution 144 uma página A4 reporta UserWidth de 1190, mas depois de Width := 500 e Height := 400 ela reporta 500 e 400. Páginas carregadas se comportam do mesmo jeito, porque uma página reconstruída de um PDF existente só conhece a MediaBox dela em points e desenha em points. Páginas que este documento criou mantêm as próprias unidades quando você sai delas e volta pela CurrentPageNumber
Armadilha dois: por que tamanhos de fonte saem com metade do tamanho?
Um tamanho de fonte que começou como points sai com metade do tamanho na Resolution 144 porque o SetFont trata o argumento de tamanho dele como unidades de desenho e o converte para points antes de armazenar. Internamente, o SetFont guarda ASize / DocScale * DPI no objeto de fonte atual, então o valor armazenado é sempre points. Devolva esse valor em points armazenado ao SetFont e ele é escalado uma segunda vez, reduzindo o texto à metade, que é exatamente o que qualquer caminho que reaplica uma fonte, como um font fallback ou uma página de continuação, precisa evitar. Seu código não consegue ler o tamanho armazenado, mas a mesma armadilha aparece sempre que um valor em points de outro lugar chega ao SetFont: um TFont.Size de um form VCL, um tamanho numa definição de relatório, um comprimento pt de CSS. Converta-o primeiro, e inclua a Resolution da própria página e o caso UserDefined no fator, como o playback de metafile faz quando repete o Canvas da página (veja como o HotPDF importa gráficos vetoriais EMF e WMF para esse caminho):
// Unidades de desenho por point na página atual. Espelha a projeção
// que o HotPDF usa: 1 numa página dimensionada por Width/Height, caso contrário
// (document Resolution / 72) * (page Resolution / 72)
function UnitsPerPoint(Pdf: THotPDF): Single;
begin
if Pdf.CurrentPage.Size = UserDefined then
Result := 1
else
Result := (Pdf.Resolution / 72) * (Pdf.CurrentPage.Resolution / 72);
end;
procedure SetFontFromVcl(Pdf: THotPDF; Font: TFont);
begin
// TFont.Size está em points; SetFont espera unidades de desenho
Pdf.CurrentPage.SetFont(AnsiString(Font.Name), Font.Style,
Font.Size * UnitsPerPoint(Pdf));
end;
A biblioteca aplica a mesma regra às próprias constantes em points dela. A fonte de 12 points com que toda página nova começa é multiplicada pelo fator interno de unidades-por-point, então ela tem 12 points em qualquer Resolution. O DrawChart, cujas margens, tamanhos de rótulo e larguras de linha são todos points fixados no código, roda com a escala temporariamente definida como 1. O que fica em unidades de desenho, de propósito, são defaults de parâmetros públicos como o tamanho de módulo do DrawQRCode e o tamanho de fonte default de tabela: eles fazem parte do contrato da API, então na Resolution 144 significam metade do que significam a 72. Se você dimensiona relatórios a partir de um template, o guia de saída de relatórios com fontes e imagens no HotPDF cobre de onde esses valores geralmente vêm
Como você verifica que um layout é independente de Resolution?
A checagem mais confiável é uma comparação de bytes: renderize a mesma página na Resolution 72 e de novo a 144 com toda coordenada e tamanho dobrados, e os content streams descomprimidos precisam ser idênticos. As duas execuções caem nos mesmos valores em points depois da projeção, então qualquer diferença é um valor que pulou a conversão. A técnica funciona para o seu próprio código de relatório com quase nenhum harness:
procedure RenderPage(const FileName: string; Res: Integer; K: Single);
var
Pdf: THotPDF;
begin
Pdf := THotPDF.Create(nil);
try
Pdf.AutoLaunch := False;
Pdf.Compression := cmNone; // content streams legíveis
Pdf.FileName := FileName;
Pdf.Resolution := Res;
Pdf.BeginDoc;
Pdf.CurrentPage.SetFont('Arial', [], 10 * K);
Pdf.CurrentPage.TextOut(36 * K, 36 * K, 0, 'Line 1');
Pdf.CurrentPage.Rectangle(36 * K, 60 * K, 200 * K, 40 * K);
Pdf.CurrentPage.Stroke;
Pdf.EndDoc;
finally
Pdf.Free;
end;
end;
// RenderPage('r72.pdf', 72, 1) e RenderPage('r144.pdf', 144, 2)
// precisam produzir content streams de página idênticos byte a byte
Confira os operadores que carregam números: Td, Tm, Tf, re, w e os arrays de TJ. Bytes a nível de arquivo ainda vão divergir na data de criação e no /ID, então compare os streams, não arquivos inteiros. Uma divergência quase sempre aponta para uma das duas armadilhas acima: uma página redimensionada pelo Width, ou um valor em points passado direto ao SetFont. Se você é novo nas chamadas de desenho em si, comece pelo passo a passo de TextOut do HotPDF para tamanho, estilo e rotação, depois volte e mude a Resolution quando o seu layout ler UserWidth. Detalhes completos de API e downloads de teste estão na página do componente HotPDF Delphi PDF