Articolo tecnico

PDFlibPas: import EMF, regole PolyDraw, Polyline, Bezier

Disegna una V di tre punti con Canvas.Polyline mentre è selezionato un pennello giallo, converti il metafile in PDF, e un convertitore ingenuo ti restituisce un triangolo giallo pieno. Lo stesso convertitore può piegare una Bezier verso il punto di controllo sbagliato e lasciare un rettangolo PolyDraw con tre lati. Ogni caso risale a una regola [MS-EMF]: EMR_POLYBEZIER parte dal punto 0, le polilinee sono aperte e tracciate soltanto, PT_CLOSEFIGURE è un bit di flag, e i conteggi dei punti devono stare nella dimensione del record

Un device context ha uno stato che un path PDF non ha

Un metafile enhanced è una registrazione di chiamate GDI fatte contro un device context, e metà di ciò che un record Poly* significa sta fuori dai suoi punti: se la figura è aperta, se parte dalla posizione corrente, quali penna e pennello sono selezionati, e a quale byte offset cominciano i punti. Il PDF non ha nulla di ciò. Ha un path, un punto corrente dentro quel path, e un operatore di pittura che sceglie stroke (S), fill (f) o entrambi (B). L'importer vettoriale EMF di PDFlibPas, la libreria PDF losLab per Delphi, rigioca quello stato del device context accanto alle coordinate, e le regole qui sotto descrivono come mappa ogni record

La famiglia Poly* esiste anche in due larghezze. Ogni record a 32 bit come EMR_POLYLINE ha un gemello a 16 bit come EMR_POLYLINE16 che memorizza i punti come coppie SmallInt, e GDI registra la forma compatta ogni volta che ogni coordinate ci sta. I disegni quotidiani quindi raramente raggiungono gli handler a 32 bit di un convertitore. Dai gli stessi punti in pasto a entrambe le larghezze e confronta i path; è l'audit più economico che ci sia. Tutti i record trattati qui appartengono al gruppo dei record di disegno in [MS-EMF] 2.3.5

RecordInizia aChiuso?Posizione corrente
EMR_POLYBEZIERPunto 0NoNon usata, non aggiornata
EMR_POLYLINEPunto 0No (solo penna)Non usata, non aggiornata
EMR_POLYLINETOPosizione correnteNo (solo penna)Usata e aggiornata
EMR_POLYPOLYLINEPrimo punto di ogni polilineaNo (solo penna)Non usata, non aggiornata
EMR_POLYDRAWPrimo PT_MOVETO, o posizione correnteSolo dove PT_CLOSEFIGURE è impostatoUsata e aggiornata

Dove inizia davvero una curva EMR_POLYBEZIER?

Una curva EMR_POLYBEZIER parte dal punto 0, e solo i punti dall'indice 1 in poi sono raggruppati in terne come punto di controllo, punto di controllo, punto finale. Un record con 7 punti disegna due segmenti cubici: il punto 0 è la partenza, i punti da 1 a 3 formano il primo segmento, e da 4 a 6 il secondo. Parti il raggruppamento dal punto 0 invece e il punto di partenza viene consumato come primo punto di controllo. Ogni segmento successivo slitta di uno. L'output resta una curva morbida, solo quella sbagliata. PDFlibPas apre il path con m al punto 0, in entrambe le larghezze di record, e scrive una c per ogni terna completa dopo di lui

Diagramma PDFlibPas di un record EMR_POLYBEZIER con sette punti dove il punto zero apre il path con m e i punti da uno a tre e da quattro a sei formano ciascuno un segmento cubico c, contrapponendo il raggruppamento corretto a quello che consuma il punto di partenza come punto di controllo
Il punto 0 è il punto di partenza e solo le terne complete dopo di lui diventano segmenti cubici, così una PolyBezier di sette punti si renderizza come m più due operatori c

E un conteggio che non è 1 più un multiplo di 3? Il record è malformato. La nostra posizione è che l'ultimo punto o gli ultimi due punti vadano buttati. Cucirli in una curva inventando un punto di controllo mancante produce una forma che nessun device GDI ha mai disegnato, e un lettore che confronta il PDF con l'originale non ha modo di dire quale metà della curva è inventata

Byte di tipo PolyDraw 3 e 5

In EMR_POLYDRAW, PT_CLOSEFIGURE (valore 1) è un bit che viene messo in OR dentro PT_LINETO (2) o PT_BEZIERTO (4), quindi un byte di tipo perfettamente valido può essere 3 o 5. Il tipo del punto è il byte con quel bit mascherato via; il flag stesso significa "chiudi la figura dopo il segmento che finisce su questo punto". Un handler che confronta il byte con valori singoli in uno case Pascal non vede mai 3 o 5 combaciare con nulla. Quei punti vengono saltati. Un rettangolo disegnato con PolyDraw perde il lato di chiusura, e una terna Bezier il cui ultimo punto porta il flag perde quel punto, il che sbarella di uno tutte le terne successive

PDFlibPas fa dispatch su Types[i] and not PT_CLOSEFIGURE e chiude la figura solo una volta che un segmento è completo: subito dopo la linea per una PT_LINETO chiusa, e dopo il terzo punto di un gruppo Bezier. Un file malformato che mette il flag sul primo o secondo punto di una terna quindi non chiude la figura a metà di una curva. Due regole in più stanno nello stesso handler:

  • Solo il primo PT_MOVETO di un record avvia il path; i move successivi aprono nuovi subpath. Un EMR_POLYDRAW16 a 16 bit che tiene tre figure deve produrre tre subpath, e un handler che riavvia il path a ogni move conserva solo l'ultimo
  • Un record PolyDraw che non comincia con PT_MOVETO parte dalla posizione corrente, come dice la definizione del record. Scrivere un operatore l o c senza m precedente è un errore di content stream che ogni viewer PDF risolve a modo suo
Anatomia PDFlibPas di un byte di tipo EMR_POLYDRAW dove PT_CLOSEFIGURE è il bit flag zero in OR dentro PT_LINETO o PT_BEZIERTO, quindi i byte di tipo validi 3 e 5 vanno mascherati con and not PT_CLOSEFIGURE prima del dispatch; un case semplice salta entrambi i byte e le figure chiuse perdono il loro lato finale
Maschera via il flag di chiusura prima del dispatch e emetti la chiusura solo dopo una linea completata o una terna Bezier, altrimenti PolyDraw butta via punti in silenzio

Il triangolo giallo: perché una polilinea non viene mai riempita

EMR_POLYLINE e EMR_POLYPOLYLINE sono figure aperte disegnate con la sola penna, e in PDF un operatore di riempimento chiude qualsiasi subpath aperto prima di dipingerlo (ISO 32000-1 §8.5.3). Emetti B o f per una polilinea di tre punti e il viewer dipinge un triangolo pieno del colore di pennello corrente. È la V gialla dal paragrafo d'apertura, o il cuneo sotto una linea di tendenza di un grafico. PDFlibPas chiude entrambe le larghezze di polilinea con S e non tocca mai il pennello, il che mantiene intatte le semantiche GDI: Polygon chiude e riempie, Polyline non fa nessuna delle due

Confronto PDFlibPas di una polilinea a V aperta esportata da EMR_POLYLINE: un convertitore corretto chiude il path con l'operatore di tratto S e ignora il pennello selezionato, mentre emettere f o B chiude implicitamente il subpath aperto sotto ISO 32000-1 8.5.3 e dipinge il cuneo pieno sotto la linea di un grafico
Un operatore di riempimento chiude qualsiasi subpath aperto prima di dipingere, quindi le polilinee devono finire in S senza h, f o B sul subpath

PolylineTo e la penna che deve lasciare in pace

EMR_POLYLINETO disegna dalla posizione corrente attraverso ogni punto del record, resta aperta, e lascia la posizione corrente sull'ultimo punto. Lo stato della penna appartiene a EMR_SELECTOBJECT e EMR_CREATEPEN, mai a un handler di record di disegno. Un caso speciale che spegne la penna dentro un record non ha nulla che la riaccenda, quindi ogni record successivo perde il suo contorno. Per la forma a un punto, leggi esattamente i punti che il record tiene e fermati

I punti di PolyPolyline stanno dopo l'array dei conteggi

Il EMR_POLYPOLYLINE a 32 bit memorizza nPolys conteggi e poi cptl punti, quindi i punti cominciano al byte offset 32 + nPolys * 4. La trappola sta nella RTL Delphi. L'unità Windows dichiara TEMRPolyPolyline con aPolyCounts e aptl come array a un elemento, il che significa che aptl[0] è il primo punto solo quando nPolys è 1. Indicizza aptl direttamente e ogni record multilinea legge valori di conteggio come coordinate. Peggio, un controllo sulla dimensione costruito su quel layout rifiuta outright i record multilinea validi. PDFlibPas calcola l'offset come fa per PolyPolygon e disegna ogni polilinea come suo subpath aperto, con un singolo tratto alla fine. Il gemello a 16 bit segue lo stesso schema; disegnarlo segmento per segmento romperebbe le giunzioni di linea e ignorerebbe una NULL_PEN selezionata

Oggetti predefiniti e parentesi di path

  • Un device context GDI fresco ha già BLACK_PEN e WHITE_BRUSH selezionati. Un metafile che disegna senza un solo EMR_SELECTOBJECT è legale e prende comunque i contorni neri; un convertitore che parte senza penna scrive n (fine path, niente pittura) per quei record
  • Dentro una parentesi BeginPath / EndPath, una Polyline non usa né aggiorna la posizione corrente, quindi apre un nuovo subpath al suo primo punto invece di unirsi alla figura precedente. Nulla viene dipinto finché la parentesi non viene tracciata o riempita

Registrare un metafile di test con TMetafileCanvas

Il modo più rapido di mettere un convertitore alla prova con queste regole è registrare le tre chiamate rischiose in un solo metafile enhanced con TMetafileCanvas. La procedura qui sotto disegna le curve con un pennello vuoto, poi seleziona deliberatamente un pennello giallo pieno prima della polilinea. Un convertitore corretto ignora quel pennello. Qualsiasi giallo nel PDF di output significa che la polilinea è stata riempita. PolyDraw non ha un wrapper TCanvas, quindi passa per l'API Windows sull'handle della canvas, con byte di tipo 3 e 5 che esercitano il flag di chiusura

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

procedure BuildPolyTestEmf(const FileName: string);
const
  // Un quadrato chiuso (3 = LINETO + CLOSEFIGURE), poi una figura Bezier
  // chiusa il cui ultimo tratto di controllo finisce con 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;    // solo contorni per le curve
      // Il punto 0 è l'inizio; 1..3 e 4..6 sono due segmenti cubici
      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));
      // Forma a V aperta con pennello pieno selezionato: tracciata, mai chiusa
      // in un triangolo giallo
      Canvas.Brush.Style := bsSolid;
      Canvas.Brush.Color := clYellow;
      Canvas.Polyline([Point(20, 240), Point(120, 160), Point(220, 240)]);
    finally
      Canvas.Free;   // chiude la registrazione
    end;
    Mf.SaveToFile(FileName);
  finally
    Mf.Free;
  end;
end;

Ogni coordinate qui ci sta in un SmallInt, quindi GDI di norma memorizzerà le varianti a 16 bit. Raggiungere gli handler a 32 bit richiede un produttore che li scriva, o record assemblati a mano. I file costruiti a mano hanno la loro trappola, che affiora come un errore VCL "Metafile is not valid": TMetafile.LoadFromStream tratta lo stream come un EMF solo quando la lunghezza restante è strettamente maggiore dei 108 byte del TEnhMetaHeader. Un header corto, o un EMF vuoto di esattamente 108 byte, viene preso per un WMF e rifiutato. Scrivi l'intero header da 108 byte, campi di estensione inclusi, prima del primo record di test

Importare il metafile con ImportEMFFromFile

PDFlibPas importa un EMF attraverso ImportEMFFromFile o ImportEMFFromStream. Entrambe restituiscono un ID immagine non nullo al successo e 0 al fallimento. GeneralOptions = 0 tiene il percorso vettoriale di cui parla questo articolo, mentre 1 rasterizza il metafile in una bitmap. FontOptions = 1 aggiunge i font che il metafile usa e li incorpora come subset. La variante su stream riavvolge alla posizione 0 prima del caricamento, quindi consegnale uno stream che contiene il metafile e nient'altro

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);              // origine in alto a sinistra per DrawImage
    PDF.SetMeasurementUnits(0);    // punti
    // FontOptions 1 = aggiunge i font del metafile come subset incorporati
    // GeneralOptions 0 = import vettoriale, 1 = bitmap
    ImageID := PDF.ImportEMFFromFile(EmfFile, 1, 0);
    if ImageID = 0 then
      raise Exception.Create('The metafile could not be imported');
    PDF.SelectImage(ImageID);
    // Per un EMF, ImageWidth / ImageHeight sono le dimensioni della cornice in punti
    PDF.DrawImage(36, 36, PDF.ImageWidth, PDF.ImageHeight);

    // La pagina invoca solo la form importata: q ... cm /Name Do Q
    // (un controllo di sanità opzionale che puoi aggiungere al tuo codice)
    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;

Un import EMF vettoriale diventa un form XObject, quindi GetPageContentToString restituisce solo la sequenza save, transform, Do e restore. Gli operatori m, l, c, h e S generati dai record Poly* vivono nello stream compresso del form XObject. Apri il file salvato in un ispettore di oggetti PDF, decomprimi quello stream, e controlla tre cose per il file di test qui sopra: la polilinea finisce in S senza h prima, ogni flag di chiusura nelle figure PolyDraw ha prodotto una h, e nessuna f o B compare su nessuno di quei subpath. DrawImage scala un EMF importato uniformemente secondo il minore tra Width e Height, quindi il disegno conserva il suo rapporto d'aspetto anche quando la box che passi non lo rispetta

Gli utenti Free Pascal possono leggere come l'importer vettoriale EMF di PDFlibPas si costruisce sotto Free Pascal; le semantiche dei record sono identiche ovunque l'importer compili

I conteggi di punti in un file EMF sono input non fidato

Ogni conteggio di punti in un metafile andrebbe controllato contro la dimensione del record prima che un solo punto venga copiato. EnumEnhMetaFile garantisce solo che il nSize di ogni record stia dentro il file. Non controlla mai che cptl sia d'accordo con nSize. Un handler che copia cptl punti con Move leggerà volentieri nei record seguenti, o oltre la fine del metafile, appena il conteggio è falsificato o corrotto. PDFlibPas confronta header fisso più conteggio per byte per punto con nSize per PolyDraw, PolyBezier, PolyBezierTo, Polyline, PolylineTo e Polygon in entrambe le larghezze, aggiungendo un byte per punto per l'array dei tipi di PolyDraw. Per i record PolyPoly i conteggi per figura devono inoltre sommare a non più del totale dichiarato, e le figure con zero punti vengono saltate

Preferiamo saltare un record che fallisce questo test che limitare il conteggio a ciò che ci sta. Un record limitato disegna comunque, e una figura disegnata parzialmente in un report è più difficile da notare di una mancante. Il controllo è abbastanza corto da cadere nel tuo parser; questa versione valida un EMR_POLYPOLYLINE a 32 bit e restituisce un puntatore al suo vero array di punti:

uses
  Winapi.Windows;

// Un controllo da aggiungere al tuo parser EMF (non una routine della libreria).
// Restituisce nil a meno che il record tenga davvero i punti che dichiara.
// I punti cominciano dopo l'array dei conteggi: 32 + nPolys * 4 byte dentro, non a
// aptl[0], che la RTL dichiara come array a un 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;                         // conteggio falsificato o troncato
  Total := 0;
  Count := @P^.aPolyCounts[0];    // cammina per puntatore: [0..0] fa scattare i range check
  for I := 1 to P^.nPolys do
  begin
    Inc(Total, Count^);
    Inc(Count);
  end;
  if Total > P^.cptl then
    Exit;                         // le figure pretendono più punti di quanti ne esistano
  Result := PPoint(NativeUInt(Rec) + NativeUInt(PointsOffset));
end;

L'ordine conta qui. Il test dei punti-che-ci-stanno gira per primo, il che prova che l'array dei conteggi sta dentro il record prima che il ciclo lo percorra. L'aritmetica usa Int64 perché nPolys * 4 e cptl * 8 calcolati a 32 bit possono andare in wrap-around fino a un numero piccolo e passare il confronto

Le stesse semantiche dei record valgano qualunque componente renderizzi i tuoi report. L'import vettoriale EMF e WMF di HotPDF copre come quel componente trasforma pennelli a gradiente e hatch in pattern PDF, e grafica vettoriale, shader e gradienti in PDFlibPas mostra come disegnare le stesse forme direttamente con l'API della libreria, saltando del tutto il metafile

Per far passare i tuoi metafile di report da questo importer, la pagina della libreria PDF Delphi PDFlibPas ha i dettagli di prodotto e il download della trial