Artigo Técnico

PDFlibPas: regras EMF de PolyDraw, Polyline e Bezier

Desenhe um V de três pontos com Canvas.Polyline enquanto um pincel amarelo está selecionado, converta o metafile para PDF, e um conversor ingênuo devolve um triângulo amarelo sólido. O mesmo conversor pode curvar uma Bezier em direção ao control point errado e deixar um retângulo de PolyDraw com três lados. Cada caso remonta a uma regra do [MS-EMF]: a EMR_POLYBEZIER começa no ponto 0, polylines são abertas e recebem só stroke, PT_CLOSEFIGURE é um bit de flag, e contagens de pontos precisam caber no tamanho do record

Um device context tem estado que um path de PDF não tem

Um enhanced metafile é uma gravação de chamadas GDI feitas contra um device context, e metade do que um record Poly* significa vive fora dos pontos dele: se a figura é aberta, se ela começa na posição atual, quais caneta e pincel estão selecionados, e em qual offset de byte os pontos começam. O PDF não tem nada disso. Ele tem um path, um current point dentro desse path, e um operador de pintura que escolhe stroke (S), fill (f) ou ambos (B). O importer de EMF vetorial do PDFlibPas, a biblioteca de PDF losLab para Delphi, repõe esse estado de device context junto com as coordenadas, e as regras abaixo descrevem como ele mapeia cada record

A família Poly* também vem em duas larguras. Cada record de 32 bits como a EMR_POLYLINE tem um gêmeo de 16 bits como a EMR_POLYLINE16 que armazena pontos como pares de SmallInt, e o GDI grava a forma compacta sempre que toda coordenada cabe. Desenhos do dia a dia portanto raramente chegam aos handlers de 32 bits de um conversor. Alimente os mesmos pontos pelas duas larguras e compare os paths; essa é a auditoria mais barata que existe. Todos os records cobertos aqui pertencem ao grupo de records de desenho em [MS-EMF] 2.3.5

RecordComeça emFechada?Posição atual
EMR_POLYBEZIERPonto 0NãoNão usada, não atualizada
EMR_POLYLINEPonto 0Não (só caneta)Não usada, não atualizada
EMR_POLYLINETOPosição atualNão (só caneta)Usada e atualizada
EMR_POLYPOLYLINEPrimeiro ponto de cada polylineNão (só caneta)Não usada, não atualizada
EMR_POLYDRAWPrimeiro PT_MOVETO, ou posição atualSó onde PT_CLOSEFIGURE está setadoUsada e atualizada

Onde uma curva EMR_POLYBEZIER realmente começa?

Uma curva EMR_POLYBEZIER começa no ponto 0, e só os pontos do índice 1 em diante são agrupados em trios de control point, control point, end point. Um record com 7 pontos desenha dois segmentos cúbicos: o ponto 0 é o início, os pontos 1 a 3 formam o primeiro segmento, e 4 a 6 formam o segundo. Comece o agrupamento no ponto 0 e o start point é consumido como o primeiro control point. Todo segmento posterior se desloca em um. A saída ainda é uma curva suave, só que a errada. O PDFlibPas abre o path com m no ponto 0, nas duas larguras de record, e grava um c por trio completo depois dele

Diagrama do PDFlibPas de um record EMR_POLYBEZIER com sete pontos em que o ponto zero abre o path com m e os pontos um a três e quatro a seis formam cada um um segmento cúbico c, contrastando o agrupamento correto com um que consome o start point como control point
O ponto 0 é o start point e só os trios completos depois dele viram segmentos cúbicos, então um PolyBezier de sete pontos renderiza como m mais dois operadores c

E uma contagem que não é 1 mais um múltiplo de 3? O record está malformado. Nossa posição é que o ponto ou os dois pontos finais devem ser descartados. Emendá-los numa curva inventando um control point ausente produz uma forma que nenhum device GDI jamais desenhou, e um reader comparando o PDF com o original não tem como dizer qual metade da curva é inventada

Bytes de tipo 3 e 5 do PolyDraw

Na EMR_POLYDRAW, PT_CLOSEFIGURE (valor 1) é um bit que é operado com OR em PT_LINETO (2) ou PT_BEZIERTO (4), então um byte de tipo perfeitamente válido pode ser 3 ou 5. O tipo do ponto é o byte com esse bit mascarado; a flag em si significa "feche a figura depois do segmento que termina neste ponto". Um handler que compara o byte com valores únicos num case Pascal jamais vê 3 ou 5 casar com algo. Esses pontos são pulados. Um retângulo desenhado com PolyDraw perde o lado de fechamento, e um trio Bezier cujo último ponto carrega a flag perde esse ponto, o que joga todo trio posterior fora de passo em um

Anatomia no PDFlibPas de um byte de tipo de EMR_POLYDRAW em que PT_CLOSEFIGURE é o bit de flag zero operado com OR em PT_LINETO ou PT_BEZIERTO, então os bytes de tipo válidos 3 e 5 precisam ser mascarados com and not PT_CLOSEFIGURE antes do dispatch; um case statement simples pula os dois bytes e figuras fechadas perdem o último lado
Mascare a flag de fechamento antes do dispatch e emita o fechamento só depois de uma linha ou de um trio Bezier completos, ou o PolyDraw descarta pontos em silêncio

O PDFlibPas despacha sobre Types[i] and not PT_CLOSEFIGURE e fecha a figura só quando um segmento está completo: logo depois da linha para um PT_LINETO fechado, e depois do terceiro ponto de um grupo Bezier. Um arquivo malformado que defina a flag no primeiro ou segundo ponto de um trio portanto não fecha a figura no meio de uma curva. Mais duas regras pertencem ao mesmo handler:

  • Só o primeiro PT_MOVETO num record inicia o path; moves posteriores abrem novos subpaths. Uma EMR_POLYDRAW16 de 16 bits guardando três figuras precisa produzir três subpaths, e um handler que reinicia o path a cada move mantém só a última
  • Um record PolyDraw que não começa com PT_MOVETO começa na posição atual, como a definição do record diz. Gravar um operador l ou c sem um m precedente é um erro de content stream que cada viewer de PDF resolve de um jeito
Comparação no PDFlibPas de uma polyline em V aberta exportada do EMR_POLYLINE: um conversor correto termina o path com o operador de stroke S e ignora o pincel selecionado, enquanto emitir f ou B fecha o subpath aberto implicitamente sob a ISO 32000-1 8.5.3 e pinta a fatia preenchida sob uma linha de gráfico
Um operador de fill fecha qualquer subpath aberto antes de pintar, então polylines precisam terminar em S sem h, f ou B no subpath

O triângulo amarelo: por que uma polyline nunca é preenchida

A EMR_POLYLINE e a EMR_POLYPOLYLINE são figuras abertas desenhadas só com a caneta, e no PDF um operador de fill fecha qualquer subpath aberto antes de pintá-lo (ISO 32000-1 §8.5.3). Emita B ou f para uma polyline de três pontos e o viewer pinta um triângulo preenchido na cor de pincel que estiver corrente. Esse é o V amarelo do parágrafo de abertura, ou a fatia sob a linha de tendência de um gráfico. O PDFlibPas termina as duas larguras de polyline com S e nunca toca no pincel, o que mantém a semântica GDI intacta: Polygon fecha e preenche, Polyline não faz nenhum dos dois

PolylineTo e a caneta que ele precisa deixar em paz

A EMR_POLYLINETO desenha da posição atual através de todo ponto do record, fica aberta, e deixa a posição atual no último ponto. O estado da caneta é propriedade de EMR_SELECTOBJECT e EMR_CREATEPEN, nunca de um handler de record de desenho. Um caso especial que desliga a caneta dentro de um record não tem nada que a ligue de volta, então todo record posterior perde o contorno dele. Para a forma de um ponto, leia exatamente os pontos que o record guarda e pare

Os pontos do PolyPolyline ficam depois do array de contagens

A EMR_POLYPOLYLINE de 32 bits guarda nPolys contagens e então cptl pontos, então os pontos começam no offset de byte 32 + nPolys * 4. A armadilha está na RTL do Delphi. A unit Windows declara a TEMRPolyPolyline com aPolyCounts e aptl como arrays de um elemento, o que significa que aptl[0] é o primeiro ponto só quando nPolys é 1. Indexe aptl direto e todo record multi-linha lê valores de contagem como coordenadas. Pior, uma checagem de tamanho construída sobre esse layout rejeita de cara records multi-linha válidos. O PDFlibPas calcula o offset do mesmo jeito que faz para PolyPolygon e desenha cada polyline como o próprio subpath aberto dela, com um único stroke no final. O gêmeo de 16 bits segue o mesmo padrão; desenhá-lo segmento por segmento quebraria as junções de linha e ignoraria um NULL_PEN selecionado

Objetos padrão e brackets de path

  • Um device context GDI recém-criado já tem BLACK_PEN e WHITE_BRUSH selecionados. Um metafile que desenha sem um único EMR_SELECTOBJECT é legal e ainda ganha contornos pretos; um conversor que começa sem caneta grava n (termina o path, não pinta nada) para esses records
  • Dentro de um bracket BeginPath / EndPath, uma Polyline não usa nem atualiza a posição atual, então ela abre um novo subpath no primeiro ponto dela em vez de se juntar à figura anterior. Nada é pintado até o bracket receber stroke ou fill

Gravando um metafile de teste com TMetafileCanvas

O jeito mais rápido de pôr um conversor à prova dessas regras é gravar as três chamadas arriscadas num único enhanced metafile com TMetafileCanvas. O procedimento abaixo desenha as curvas com um pincel vazado, e então deliberadamente seleciona um pincel amarelo sólido antes da polyline. Um conversor correto ignora esse pincel. Qualquer amarelo no PDF de saída significa que a polyline foi preenchida. A PolyDraw não tem wrapper na TCanvas, então ela passa pela API do Windows no handle do canvas, com bytes de tipo 3 e 5 exercitando a flag de fechamento

uses
  Winapi.Windows, System.Types, Vcl.Graphics;

procedure BuildPolyTestEmf(const FileName: string);
const
  // Um quadrado fechado (3 = LINETO + CLOSEFIGURE), depois uma
  // figura Bezier fechada cujo último trio de controle termina em 5 = BEZIERTO + CLOSEFIGURE
  DrawPts: array[0..7] of TPoint = (
    (X: 300; Y: 40), (X: 380; Y: 40), (X: 380; Y: 120), (X: 300; Y: 120),
    (X: 420; Y: 120), (X: 440; Y: 40), (X: 520; Y: 40), (X: 540; Y: 120));
  DrawTypes: array[0..7] of Byte = (
    PT_MOVETO, PT_LINETO, PT_LINETO, PT_LINETO or PT_CLOSEFIGURE,
    PT_MOVETO, PT_BEZIERTO, PT_BEZIERTO, PT_BEZIERTO or PT_CLOSEFIGURE);
var
  Mf: TMetafile;
  Canvas: TMetafileCanvas;
begin
  Mf := TMetafile.Create;
  try
    Mf.Enhanced := True;
    Mf.Width := 600;
    Mf.Height := 260;
    Canvas := TMetafileCanvas.Create(Mf, 0);
    try
      Canvas.Pen.Color := clNavy;
      Canvas.Pen.Width := 2;
      Canvas.Brush.Style := bsClear;    // só contornos para as curvas
      // O ponto 0 é o início; 1..3 e 4..6 são dois segmentos cúbicos
      Canvas.PolyBezier([Point(20, 120), Point(60, 20), Point(100, 220),
        Point(140, 120), Point(180, 20), Point(220, 220), Point(260, 120)]);
      PolyDraw(Canvas.Handle, DrawPts[0], DrawTypes[0], Length(DrawPts));
      // V aberta com pincel sólido selecionado: recebe stroke, nunca é
      // fechada num triângulo amarelo
      Canvas.Brush.Style := bsSolid;
      Canvas.Brush.Color := clYellow;
      Canvas.Polyline([Point(20, 240), Point(120, 160), Point(220, 240)]);
    finally
      Canvas.Free;   // encerra a gravação
    end;
    Mf.SaveToFile(FileName);
  finally
    Mf.Free;
  end;
end;

Toda coordenada aqui cabe num SmallInt, então o GDI normalmente vai armazenar as variantes de 16 bits. Chegar aos handlers de 32 bits exige um produtor que os grave, ou records montados à mão. Arquivos feitos à mão têm armadilha própria, e ela aparece como um erro VCL "Metafile is not valid": a TMetafile.LoadFromStream trata o stream como EMF só quando o comprimento restante é estritamente maior que o TEnhMetaHeader de 108 bytes. Um header curto, ou um EMF vazio de exatamente 108 bytes, é tomado por WMF e rejeitado. Grave o header completo de 108 bytes, campos de extensão incluídos, antes do primeiro record de teste

Importando o metafile com ImportEMFFromFile

O PDFlibPas importa um EMF através de ImportEMFFromFile ou ImportEMFFromStream. Ambos devolvem um ID de imagem não zero em sucesso e 0 em falha. GeneralOptions = 0 mantém o caminho vetorial de que este artigo trata, enquanto 1 rasteriza o metafile para um bitmap. FontOptions = 1 acrescenta as fontes que o metafile usa e as embute como subsets. A variante de stream rebobina para a posição 0 antes de carregar, então entregue a ela um stream que contenha o metafile e nada mais

uses
  System.SysUtils, PDFlibrary;

procedure EmfToPdf(const EmfFile, PdfFile: WideString);
var
  PDF: TPDFlib;
  ImageID: Integer;
  PageOps: AnsiString;
begin
  PDF := TPDFlib.Create;
  try
    PDF.SetOrigin(1);              // origem topo-esquerda para DrawImage
    PDF.SetMeasurementUnits(0);    // pontos
    // FontOptions 1 = acrescenta as fontes do metafile como subsets embutidos
    // GeneralOptions 0 = importação vetorial, 1 = bitmap
    ImageID := PDF.ImportEMFFromFile(EmfFile, 1, 0);
    if ImageID = 0 then
      raise Exception.Create('The metafile could not be imported');
    PDF.SelectImage(ImageID);
    // Para um EMF, ImageWidth / ImageHeight são o tamanho do frame em pontos
    PDF.DrawImage(36, 36, PDF.ImageWidth, PDF.ImageHeight);

    // A página só invoca o form importado: q ... cm /Name Do Q
    // (uma checagem de sanidade opcional que você pode acrescentar ao seu próprio código)
    PageOps := PDF.GetPageContentToString;
    if Pos(AnsiString(' Do'), PageOps) = 0 then
      raise Exception.Create('Expected a form XObject invocation');

    if PDF.SaveToFile(PdfFile) <> 1 then
      raise Exception.Create('The PDF could not be saved');
  finally
    PDF.Free;
  end;
end;

Uma importação de EMF vetorial vira um form XObject, então a GetPageContentToString devolve só a sequência de save, transform, Do e restore. Os operadores m, l, c, h e S gerados dos records Poly* vivem no stream comprimido do form XObject. Abra o arquivo salvo num inspetor de objetos PDF, descomprima esse stream e confira três coisas para o arquivo de teste acima: a polyline termina em S sem nenhum h antes dela, cada flag de fechamento nas figuras do PolyDraw produziu um h, e nenhum f ou B aparece em nenhum desses subpaths. A DrawImage escala um EMF importado uniformemente pelo menor entre Width e Height, então o desenho mantém a proporção dele mesmo quando a caixa que você passar não casa com ela

Usuários de Free Pascal podem ler como o importer vetorial EMF do PDFlibPas compila sob Free Pascal; a semântica dos records é idêntica onde quer que o importer compile

Contagens de pontos num arquivo EMF são entrada não confiável

Toda contagem de pontos num metafile deveria ser conferida contra o tamanho do record antes de um único ponto ser copiado. A EnumEnhMetaFile garante só que o nSize de cada record fique dentro do arquivo. Ela nunca confere que cptl concorda com nSize. Um handler que copia cptl pontos com Move vai ler contente os records seguintes, ou além do fim do metafile, assim que a contagem for forjada ou estiver corrompida. O PDFlibPas compara header fixo mais contagem vezes bytes por ponto contra o nSize para PolyDraw, PolyBezier, PolyBezierTo, Polyline, PolylineTo e Polygon nas duas larguras, somando um byte por ponto para o array de tipos do PolyDraw. Para os records PolyPoly as contagens por figura também precisam somar no máximo o total declarado, e figuras com zero pontos são puladas

Nós preferimos pular um record que falhe nesse teste a limitar a contagem ao que couber. Um record limitado ainda desenha, e uma figura parcialmente desenhada num relatório é mais difícil de notar que uma ausente. A checagem é curta o suficiente para entrar no seu próprio parser; esta versão valida uma EMR_POLYPOLYLINE de 32 bits e devolve um pointer para o array real de pontos dela:

uses
  Winapi.Windows;

// Uma checagem para acrescentar ao seu próprio parser EMF (não é uma rotina da biblioteca).
// Devolve nil a menos que o record realmente guarde os pontos que declara.
// Os pontos começam depois do array de contagens: 32 + nPolys * 4 bytes adentro, não em
// aptl[0], que a RTL declara como array de um elemento
function PolyPolylinePoints(Rec: PEnhMetaRecord): PPoint;
var
  P: PEMRPolyPolyline;
  Count: PDWORD;
  PointsOffset, Total: Int64;
  I: Cardinal;
begin
  Result := nil;
  if (Rec^.iType <> EMR_POLYPOLYLINE) or (Rec^.nSize < 32) then
    Exit;
  P := PEMRPolyPolyline(Rec);
  if P^.nPolys = 0 then
    Exit;
  PointsOffset := 32 + Int64(P^.nPolys) * SizeOf(DWORD);
  if PointsOffset + Int64(P^.cptl) * SizeOf(TPoint) > Rec^.nSize then
    Exit;                         // contagem forjada ou truncada
  Total := 0;
  Count := @P^.aPolyCounts[0];    // caminhe por pointer: [0..0] dispara range checks
  for I := 1 to P^.nPolys do
  begin
    Inc(Total, Count^);
    Inc(Count);
  end;
  if Total > P^.cptl then
    Exit;                         // figuras reivindicam mais pontos do que existem
  Result := PPoint(NativeUInt(Rec) + NativeUInt(PointsOffset));
end;

A ordem importa aqui. O teste de pontos-cabem roda primeiro, o que prova que o array de contagens está dentro do record antes de o loop caminhar por ele. A aritmética usa Int64 porque nPolys * 4 e cptl * 8 calculados em 32 bits podem dar wrap para um número pequeno e passar na comparação

As mesmas semânticas de record valem não importa qual componente renderize os seus relatórios. A importação vetorial EMF e WMF do HotPDF cobre como aquele componente transforma pincéis de gradiente e hatch em patterns de PDF, e gráficos vetoriais, shaders e gradientes no PDFlibPas mostra como desenhar as mesmas formas direto com a API da biblioteca, pulando o metafile por completo

Para rodar os seus próprios metafiles de relatório por este importer, a página da biblioteca de PDF PDFlibPas para Delphi tem detalhes do produto e o download de trial