Technischer Artikel

PDFlibPas EMF-Import: PolyDraw-, Polyline- und Bezier-Regeln

Zeichne ein dreipunktiges V mit Canvas.Polyline, während ein gelber Pinsel gewählt ist, wandle das Metafile nach PDF um, und ein naiver Konverter liefert ein massives gelbes Dreieck zurück. Derselbe Konverter kann eine Bezier zum falschen Kontrollpunkt biegen und ein PolyDraw-Rechteck mit drei Seiten zurücklassen. Jeder Fall läuft auf eine [MS-EMF]-Regel hinaus: EMR_POLYBEZIER beginnt bei Punkt 0, Polylines sind offen und werden nur gestrichen, PT_CLOSEFIGURE ist ein Flag-Bit, und Punktanzahlen müssen in die Record-Größe passen

Ein Device Context hat einen Zustand, den ein PDF-Pfad nicht hat

Ein Enhanced Metafile ist eine Aufzeichnung von GDI-Aufrufen gegen einen Device Context, und die halbe Bedeutung eines Poly*-Records liegt außerhalb seiner Punkte: ob die Figur offen ist, ob sie an der aktuellen Position beginnt, welcher Stift und Pinsel gewählt sind und bei welchem Byte-Offset die Punkte beginnen. PDF hat nichts davon. Es hat einen Pfad, einen aktuellen Punkt in diesem Pfad und einen Zeichnungsoperator, der Stroke (S), Fill (f) oder beides (B) wählt. Der Vektor-EMF-Importer in PDFlibPas, der losLab-PDF-Bibliothek für Delphi, wiederholt diesen Device-Context-Zustand zusammen mit den Koordinaten, und die Regeln unten beschreiben, wie er jeden Record mappt

Die Poly*-Familie gibt es zudem in zwei Breiten. Jeder 32-Bit-Record wie EMR_POLYLINE hat einen 16-Bit-Zwilling wie EMR_POLYLINE16, der Punkte als SmallInt-Paare speichert, und GDI zeichnet die kompakte Form auf, wann immer jede Koordinate hineinpasst. Alltägliches Testgut erreicht die 32-Bit-Handler eines Konverters also selten. Dieselben Punkte durch beide Breiten schicken und die Pfade vergleichen; das ist der billigste Audit, den es gibt. Alle hier behandelten Records gehören zur Drawing-Record-Gruppe in [MS-EMF] 2.3.5

RecordBeginnt beiGeschlossen?Aktuelle Position
EMR_POLYBEZIERPunkt 0NeinNicht verwendet, nicht aktualisiert
EMR_POLYLINEPunkt 0Nein (nur Stift)Nicht verwendet, nicht aktualisiert
EMR_POLYLINETOAktuelle PositionNein (nur Stift)Verwendet und aktualisiert
EMR_POLYPOLYLINEErster Punkt jeder PolylineNein (nur Stift)Nicht verwendet, nicht aktualisiert
EMR_POLYDRAWErstes PT_MOVETO oder aktuelle PositionNur wo PT_CLOSEFIGURE gesetzt istVerwendet und aktualisiert

Wo beginnt eine EMR_POLYBEZIER-Kurve tatsächlich?

Eine EMR_POLYBEZIER-Kurve beginnt bei Punkt 0, und erst die Punkte ab Index 1 werden zu Drillingen gruppiert: Kontrollpunkt, Kontrollpunkt, Endpunkt. Ein Record mit 7 Punkten zeichnet zwei kubische Segmente: Punkt 0 ist der Start, die Punkte 1 bis 3 bilden das erste Segment, 4 bis 6 das zweite. Fängt man stattdessen bei Punkt 0 an zu gruppieren, wird der Startpunkt als erster Kontrollpunkt verbraucht. Jedes spätere Segment verschiebt sich um eins. Heraus kommt weiterhin eine glatte Kurve, nur eben die falsche. PDFlibPas öffnet den Pfad mit m bei Punkt 0, in beiden Record-Breiten, und schreibt ein c pro vollständigem Drilling danach

PDFlibPas-Diagramm eines EMR_POLYBEZIER-Records mit sieben Punkten, bei dem Punkt null den Pfad mit m öffnet und die Punkte eins bis drei sowie vier bis sechs jeweils ein kubisches c-Segment bilden, im Kontrast zum seit v3.539.41 korrigierten 32-Bit-Handler mit der alten Gruppierung, die den Startpunkt als Kontrollpunkt verbrauchte
Punkt 0 ist der Startpunkt, und nur vollständige Drillinge danach werden zu kubischen Segmenten, ein PolyBezier mit sieben Punkten rendert also als m plus zwei c-Operatoren

Und eine Anzahl, die nicht 1 plus ein Vielfaches von 3 ist? Der Record ist defekt. Unsere Position: Die ein oder zwei überzähligen Punkte fallen weg. Sie durch Erfinden eines fehlenden Kontrollpunkts in eine Kurve zu vernähen produziert eine Form, die kein GDI-Gerät je gezeichnet hat, und ein Leser, der das PDF mit dem Original vergleicht, kann nicht sagen, welche Hälfte der Kurve erfunden ist

PolyDraw-Typbytes 3 und 5

In EMR_POLYDRAW ist PT_CLOSEFIGURE (Wert 1) ein Bit, das per ODER in PT_LINETO (2) oder PT_BEZIERTO (4) hineinkommt, ein völlig gültiges Typbyte kann also 3 oder 5 sein. Der Punkttyp ist das Byte mit ausmaskiertem Bit; das Flag selbst heißt: schließe die Figur nach dem Segment, das auf diesem Punkt endet. Ein Handler, der das Byte in einer Pascal-case-Anweisung gegen Einzelwerte matcht, sieht 3 oder 5 nie auf irgendetwas passen. Diese Punkte werden übersprungen. Ein mit PolyDraw gezeichnetes Rechteck verliert seine schließende Seite, und ein Bezier-Drilling, dessen letzter Punkt das Flag trägt, verliert diesen Punkt, wodurch jeder spätere Drilling um eins aus dem Tritt gerät

PDFlibPas dispatcht auf Types[i] and not PT_CLOSEFIGURE und schließt die Figur erst, wenn ein Segment komplett ist: direkt nach der Linie bei geschlossenem PT_LINETO und nach dem dritten Punkt einer Bezier-Gruppe. Eine defekte Datei, die das Flag auf dem ersten oder zweiten Punkt eines Drillings setzt, schließt die Figur also nicht mitten in einer Kurve. Zwei weitere Regeln gehören in denselben Handler:

  • Nur das erste PT_MOVETO in einem Record startet den Pfad; spätere Moves öffnen neue Subpaths. Ein 16-Bit-EMR_POLYDRAW16 mit drei Figuren muss drei Subpaths produzieren, und ein Handler, der bei jedem Move den Pfad neu startet, behält nur den letzten
  • Ein PolyDraw-Record, der nicht mit PT_MOVETO beginnt, startet an der aktuellen Position, wie die Record-Definition es vorschreibt. Einen l- oder c-Operator ohne vorausgehendes m zu schreiben ist ein Content-Stream-Fehler, den jeder PDF-Viewer anders auflöst
PDFlibPas-Anatomie eines EMR_POLYDRAW-Typbytes, bei dem PT_CLOSEFIGURE das Flag-Bit null ist, per OR in PT_LINETO oder PT_BEZIERTO eingebracht, sodass gültige Typbytes 3 und 5 vor der Dispatch mit and not PT_CLOSEFIGURE maskiert werden müssen; die alte case-Anweisung übersprang beide Bytes, und geschlossene Figuren verloren ihre letzte Seite
Maskieren Sie das Close-Flag vor der Dispatch aus und geben Sie das Close erst nach einer abgeschlossenen Linie oder einem Bezier-Drilling aus, sonst wirft PolyDraw still Punkte weg

Das gelbe Dreieck: warum eine Polyline nie gefüllt wird

EMR_POLYLINE und EMR_POLYPOLYLINE sind offene Figuren, gezeichnet nur mit dem Stift, und in PDF schließt ein Fill-Operator jeden offenen Subpath, bevor er ihn zeichnet (ISO 32000-1 §8.5.3). Für eine dreipunktige Polyline B oder f auszugeben heißt, der Viewer malt ein gefülltes Dreieck in der aktuellen Pinselfarbe. Das ist das gelbe V aus dem Eingangsabsatz, oder der Keil unter der Trendlinie eines Charts. PDFlibPas beendet beide Polyline-Breiten mit S und fasst den Pinsel nie an, was die GDI-Semantik intakt hält: Polygon schließt und füllt, Polyline tut beides nie

PDFlibPas-Vergleich einer offenen V-Polyline aus EMR_POLYLINE: ein korrekter Konverter beendet den Pfad mit dem Stroke-Operator S und ignoriert den gewählten Pinsel, während f oder B den offenen Subpath gemäß ISO 32000-1 8.5.3 implizit schließt und den gefüllten Keil als Chart-Bug malt
Ein Fill-Operator schließt jeden offenen Subpath vor dem Zeichnen, Polylines müssen also in S enden, ohne h, f oder B auf dem Subpath

PolylineTo und der Stift, den sie in Ruhe lassen muss

EMR_POLYLINETO zeichnet von der aktuellen Position durch jeden Punkt im Record, bleibt offen und lässt die aktuelle Position beim letzten Punkt. Der Stiftzustand gehört EMR_SELECTOBJECT und EMR_CREATEPEN, nie einem Drawing-Record-Handler. Ein Sonderfall, der den Stift innerhalb eines Records abschaltet, hat nichts, das ihn wieder einschaltet, jeder spätere Record verliert also seinen Umriss. Für die Ein-Punkt-Form exakt die Punkte lesen, die der Record hält, und stoppen

PolyPolyline-Punkte sitzen hinter dem Counts-Array

Der 32-Bit-EMR_POLYPOLYLINE speichert nPolys Counts und danach cptl Punkte, die Punkte beginnen also beim Byte-Offset 32 + nPolys * 4. Die Falle sitzt in der Delphi-RTL. Die Unit Windows deklariert TEMRPolyPolyline mit aPolyCounts und aptl als Ein-Element-Arrays, aptl[0] ist also nur dann der erste Punkt, wenn nPolys 1 ist. aptl direkt zu indizieren heißt, bei jedem Mehrfachlinien-Record Count-Werte als Koordinaten zu lesen. Schlimmer noch: Eine an diesem Layout gebaute Größenprüfung weist gültige Mehrfachlinien-Records rundheraus ab. PDFlibPas berechnet den Offset so wie sein PolyPolygon-Handler es immer tat und zeichnet jede Polyline als eigenen offenen Subpath, mit einem einzigen Stroke am Ende. Der 16-Bit-Zwilling folgt demselben Muster; ihn segmentweise zu zeichnen würde Line Joins brechen und einen gewählten NULL_PEN ignorieren

Default-Objekte und Pfad-Klammern

  • Ein frischer GDI-Device Context hat bereits BLACK_PEN und WHITE_BRUSH gewählt. Ein Metafile, das ohne ein einziges EMR_SELECTOBJECT zeichnet, ist legal und bekommt weiterhin schwarze Umrisslinien; ein Konverter, der ohne Stift startet, schreibt für solche Records n (Pfad beenden, nichts zeichnen)
  • Innerhalb einer BeginPath-/EndPath-Klammer verwendet eine Polyline die aktuelle Position weder noch aktualisiert sie, sie öffnet also an ihrem ersten Punkt einen neuen Subpath, statt an die vorherige Figur anzuschließen. Gezeichnet wird nichts, bis die Klammer gestrichen oder gefüllt wird

Eine Test-Metafile mit TMetafileCanvas aufzeichnen

Der schnellste Weg, einen Konverter durch diese Regeln zu schicken, ist, die drei riskanten Aufrufe mit TMetafileCanvas in ein einziges Enhanced Metafile aufzuzeichnen. Die Prozedur unten zeichnet die Kurven mit hohlem Pinsel und wählt dann vor der Polyline bewusst einen massiv gelben Pinsel. Ein korrekter Konverter ignoriert diesen Pinsel. Jedes Gelb im Ausgabe-PDF heißt, die Polyline wurde gefüllt. Für PolyDraw gibt es keinen TCanvas-Wrapper, es geht also über die Windows-API am Canvas-Handle, mit Typbytes 3 und 5, die das Close-Flag üben

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

procedure BuildPolyTestEmf(const FileName: string);
const
  // Ein geschlossenes Quadrat (3 = LINETO + CLOSEFIGURE), dann eine
  // geschlossene Bezier-Figur, deren letzter Drilling mit 5 = BEZIERTO + CLOSEFIGURE endet
  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;    // nur Umrisslinien für die Kurven
      // Punkt 0 ist der Start; 1..3 und 4..6 sind zwei kubische Segmente
      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));
      // Offene V-Form mit gewähltem deckendem Pinsel: gestrichen, nie
      // zu einem gelben Dreieck geschlossen
      Canvas.Brush.Style := bsSolid;
      Canvas.Brush.Color := clYellow;
      Canvas.Polyline([Point(20, 240), Point(120, 160), Point(220, 240)]);
    finally
      Canvas.Free;   // beendet die Aufzeichnung
    end;
    Mf.SaveToFile(FileName);
  finally
    Mf.Free;
  end;
end;

Jede Koordinate hier passt in einen SmallInt, GDI speichert also normalerweise die 16-Bit-Varianten. An die 32-Bit-Handler zu kommen braucht einen Producer, der sie schreibt, oder von Hand zusammengesetzte Records. Handgebaute Dateien haben ihre eigene Falle, und sie zeigt sich als VCL-„Metafile is not valid“-Fehler: Die TMetafile.LoadFromStream behandelt den Stream nur dann als EMF, wenn die verbleibende Länge strikt größer als der 108-Byte-TEnhMetaHeader ist. Ein kurzer Header oder ein leeres EMF, exakt 108 Bytes, wird als WMF genommen und abgelehnt. Den vollen 108-Byte-Header schreiben, Erweiterungsfelder eingeschlossen, bevor der erste Test-Record kommt

Das Metafile mit ImportEMFFromFile importieren

PDFlibPas importiert ein EMF über ImportEMFFromFile oder ImportEMFFromStream. Beide liefern bei Erfolg eine von null verschiedene Image-ID und bei Misserfolg 0. GeneralOptions = 0 hält den Vektorpfad, um den es in diesem Artikel geht, während 1 das Metafile zu einer Bitmap rastert. FontOptions = 1 nimmt die Fonts auf, die das Metafile benutzt, und bettet sie als Subsets ein. Die Stream-Variante spult vor dem Laden auf Position 0 zurück, ihr also einen Stream geben, der das Metafile enthält und nichts sonst

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);              // Ursprung oben links für DrawImage
    PDF.SetMeasurementUnits(0);    // Punkte
    // FontOptions 1 = Metafile-Fonts als eingebettete Subsets aufnehmen
    // GeneralOptions 0 = Vektorimport, 1 = Bitmap
    ImageID := PDF.ImportEMFFromFile(EmfFile, 1, 0);
    if ImageID = 0 then
      raise Exception.Create('The metafile could not be imported');
    PDF.SelectImage(ImageID);
    // Bei einem EMF sind ImageWidth / ImageHeight die Rahmengröße in Punkten
    PDF.DrawImage(36, 36, PDF.ImageWidth, PDF.ImageHeight);

    // Die Seite ruft nur die importierte Form auf: q ... cm /Name Do Q
    // (eine optionale Plausibilitätsprüfung für den eigenen Code)
    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;

Ein Vektor-EMF-Import wird zu einem Form XObject, GetPageContentToString liefert also nur die Save-, Transform-, Do- und Restore-Sequenz. Die aus den Poly*-Records erzeugten m-, l-, c-, h- und S-Operatoren leben im komprimierten Form-XObject-Stream. Die gespeicherte Datei in einem PDF-Objekt-Inspektor öffnen, diesen Stream dekomprimieren und für die Testdatei oben drei Dinge prüfen: Die Polyline endet in S, ohne ein h davor, jedes Close-Flag in den PolyDraw-Figuren hat ein h produziert, und kein f oder B taucht auf einem dieser Subpaths auf. DrawImage skaliert ein importiertes EMF einheitlich mit dem kleineren von Width und Height, die Zeichnung behält also ihr Seitenverhältnis, selbst wenn die übergebene Box nicht dazu passt

Free-Pascal-Nutzer lesen wie der PDFlibPas-EMF-Vektorimporter unter Free Pascal gebaut wird; die Record-Semantik ist identisch, egal wo der Importer kompiliert

Punktanzahlen in einer EMF-Datei sind nicht vertrauenswürdige Eingabe

Jede Punktanzahl in einem Metafile sollte gegen die Record-Größe geprüft werden, bevor ein einziger Punkt kopiert wird. EnumEnhMetaFile garantiert nur, dass das nSize jedes Records innerhalb der Datei bleibt. Es prüft nie, ob cptl zu nSize passt. Ein Handler, der cptl Punkte mit Move kopiert, liest bei gefälschter oder korrupter Anzahl gern in die folgenden Records oder hinter das Ende des Metafiles. PDFlibPas hält für PolyDraw, PolyBezier, PolyBezierTo, Polyline, PolylineTo und Polygon in beiden Breiten festen Header plus Anzahl mal Bytes pro Punkt gegen nSize, mit einem Extrabyte pro Punkt für das PolyDraw-Typarray. Bei den PolyPoly-Records müssen die Counts pro Figur zudem zusammen höchstens die deklarierte Gesamtsumme ergeben, und Figuren mit null Punkten werden übersprungen

Wir ziehen es vor, einen Record, der diese Prüfung nicht besteht, zu überspringen, statt die Anzahl auf das, was passt, zu kappen. Ein gekappter Record zeichnet trotzdem, und eine teilweise gezeichnete Figur in einem Report ist schwerer zu entdecken als eine fehlende. Die Prüfung ist kurz genug für den eigenen Parser; diese Version validiert einen 32-Bit-EMR_POLYPOLYLINE und liefert einen Zeiger auf sein echtes Punktarray:

uses
  Winapi.Windows;

// Eine Prüfung für den eigenen EMF-Parser (keine Bibliotheksroutine).
// Liefert nil, sofern der Record nicht wirklich die deklarierten Punkte hält.
// Die Punkte beginnen nach dem Counts-Array: 32 + nPolys * 4 Bytes hinein,
// nicht bei aptl[0], das die RTL als Ein-Element-Array deklariert
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;                         // gefälschte oder abgeschnittene Anzahl
  Total := 0;
  Count := @P^.aPolyCounts[0];    // per Zeiger gehen: [0..0] löst Range-Checks aus
  for I := 1 to P^.nPolys do
  begin
    Inc(Total, Count^);
    Inc(Count);
  end;
  if Total > P^.cptl then
    Exit;                         // Figuren beanspruchen mehr Punkte, als existieren
  Result := PPoint(NativeUInt(Rec) + NativeUInt(PointsOffset));
end;

Hier zählt die Reihenfolge. Der Punkte-passen-Test läuft zuerst, das Counts-Array liegt also nachweislich im Record, bevor die Schleife es abläuft. Die Arithmetik benutzt Int64, weil nPolys * 4 und cptl * 8 in 32 Bit berechnet überlaufen und als kleine Zahl die Vergleichung passieren können

Dieselbe Record-Semantik gilt, welche Komponente auch immer die Reports rendert. HotPDF EMF- und WMF-Vektorimport behandelt, wie diese Komponente Gradient- und Hatch-Pinsel in PDF-Patterns umsetzt, und Vektorgrafik, Shaders und Gradients in PDFlibPas zeigt, wie man dieselben Formen direkt mit der Bibliotheks-API zeichnet, ganz ohne Metafile

Um eigene Report-Metafiles durch diesen Importer zu schicken, hat die PDFlibPas Delphi PDF Library-Seite Produktdetails und den Trial-Download