Article technique

PDFlibPas : règles EMF PolyDraw, Polyline et Bézier

Dessinez un V de trois points avec Canvas.Polyline pendant qu’une brosse jaune est sélectionnée, convertissez le métafichier en PDF, et un convertisseur naïf vous rend un triangle jaune plein. Le même convertisseur peut plier une Bézier vers le mauvais point de contrôle et laisser un rectangle PolyDraw avec trois côtés. Chaque cas remonte à une règle de [MS-EMF] : EMR_POLYBEZIER démarre au point 0, les polylines sont ouvertes et seulement tracées au trait, PT_CLOSEFIGURE est un bit de drapeau, et les comptes de points doivent tenir dans la taille de l’enregistrement

Un device context a un état qu’un path PDF n’a pas

Un métafichier enrichi est un enregistrement d’appels GDI passés à un device context, et la moitié de ce que signifie un enregistrement Poly* vit en dehors de ses points : la figure est-elle ouverte, démarre-t-elle à la position courante, quels crayon et brosse sont sélectionnés, et à quel offset d’octet commencent les points. PDF n’a rien de tout cela. Il a un path, un point courant dedans, et un opérateur de peinture qui choisit stroke (S), fill (f) ou les deux (B). L’importeur EMF vectoriel de PDFlibPas, la bibliothèque PDF losLab pour Delphi, rejoue cet état de device context à côté des coordonnées, et les règles ci-dessous décrivent comment il mappe chaque enregistrement

La famille Poly* existe aussi en deux largeurs. Chaque enregistrement 32 bits comme EMR_POLYLINE a un jumeau 16 bits comme EMR_POLYLINE16 qui stocke les points en paires de SmallInt, et GDI écrit la forme compacte dès que chaque coordonnée tient. Les dessins du quotidien n’atteignent donc rarement les gestionnaires 32 bits d’un convertisseur. Passez les mêmes points par les deux largeurs et comparez les tracés ; c’est l’audit le moins cher qui soit. Tous les enregistrements traités ici appartiennent au groupe des enregistrements de dessin de [MS-EMF] 2.3.5

EnregistrementDémarre àFermé ?Position courante
EMR_POLYBEZIERPoint 0NonNon utilisée, non mise à jour
EMR_POLYLINEPoint 0Non (crayon seul)Non utilisée, non mise à jour
EMR_POLYLINETOPosition couranteNon (crayon seul)Utilisée et mise à jour
EMR_POLYPOLYLINEPremier point de chaque polylineNon (crayon seul)Non utilisée, non mise à jour
EMR_POLYDRAWPremier PT_MOVETO, ou position couranteLà où PT_CLOSEFIGURE est poséUtilisée et mise à jour

Où une courbe EMR_POLYBEZIER démarre-t-elle réellement ?

Une courbe EMR_POLYBEZIER démarre au point 0, et seuls les points à partir de l’index 1 sont groupés par trois en point de contrôle, point de contrôle, point final. Un enregistrement de 7 points dessine deux segments cubiques : le point 0 est le départ, les points 1 à 3 forment le premier segment, et 4 à 6 le second. Commencez le groupement au point 0 à la place et le point de départ se fait avaler comme premier point de contrôle. Chaque segment suivant est décalé d’un cran. La sortie reste une courbe lisse, juste pas la bonne. PDFlibPas ouvre le path avec m au point 0, dans les deux largeurs d’enregistrement, et écrit un c par triplet complet ensuite

Schéma PDFlibPas d’un enregistrement EMR_POLYBEZIER de sept points où le point zéro ouvre le path avec m et les points un à trois puis quatre à six forment chacun un segment cubique c, en contraste entre le groupement correct et celui qui avale le point de départ comme point de contrôle
Le point 0 est le point de départ et seuls les triplets complets qui suivent deviennent des segments cubiques, si bien qu’une PolyBezier de sept points se rend en m plus deux opérateurs c

Et un compte qui n’est pas 1 plus un multiple de 3 ? L’enregistrement est mal formé. Notre position est que le ou les deux points traînants doivent être abandonnés. Les recoudre en une courbe en inventant un point de contrôle manquant produit une forme qu’aucun device GDI n’a jamais dessinée, et un lecteur qui compare le PDF à l’original n’a aucun moyen de dire quelle moitié de la courbe est inventée

Octets de type PolyDraw 3 et 5

Dans EMR_POLYDRAW, PT_CLOSEFIGURE (valeur 1) est un bit OUé dans PT_LINETO (2) ou PT_BEZIERTO (4), si bien qu’un octet de type parfaitement valide peut valoir 3 ou 5. Le type du point est l’octet avec ce bit masqué ; le drapeau lui-même signifie « fermer la figure après le segment qui se termine sur ce point ». Un gestionnaire qui compare l’octet à des valeurs simples dans un case Pascal ne voit jamais 3 ni 5 correspondre à quoi que ce soit. Ces points sont sautés. Un rectangle dessiné en PolyDraw perd son côté de fermeture, et un triplet de Bézier dont le dernier point porte le drapeau perd ce point, ce qui désynchronise tous les triplets suivants d’un cran

PDFlibPas dispatche sur Types[i] and not PT_CLOSEFIGURE et ne ferme la figure qu’une fois un segment complet : juste après la ligne pour un PT_LINETO fermé, et après le troisième point d’un groupe de Bézier. Un fichier mal formé qui pose le drapeau sur le premier ou le deuxième point d’un triplet ne ferme donc pas la figure au milieu d’une courbe. Deux autres règles appartiennent au même gestionnaire :

  • Seul le premier PT_MOVETO d’un enregistrement démarre le path ; les moves suivants ouvrent de nouveaux sous-chemins. Un EMR_POLYDRAW16 16 bits portant trois figures doit produire trois sous-chemins, et un gestionnaire qui redémarre le path à chaque move ne garde que la dernière
  • Un enregistrement PolyDraw qui ne commence pas par PT_MOVETO démarre à la position courante, comme le dit la définition de l’enregistrement. Écrire un opérateur l ou c sans m préalable est une erreur de flux de contenu que chaque lecteur PDF résout différemment
Anatomie PDFlibPas d’un octet de type EMR_POLYDRAW où PT_CLOSEFIGURE est le bit de drapeau zéro OUed dans PT_LINETO ou PT_BEZIERTO, donc les octets de type valides 3 et 5 doivent être masqués avec and not PT_CLOSEFIGURE avant le dispatch ; un case simple saute les deux octets et les figures fermées perdent leur dernier côté
Masquez le drapeau de fermeture avant le dispatch et n’émettez la fermeture qu’après une ligne ou un triplet de Bézier terminé, sinon PolyDraw abandonne des points en silence

Le triangle jaune : pourquoi une polyline n’est jamais remplie

EMR_POLYLINE et EMR_POLYPOLYLINE sont des figures ouvertes dessinées au crayon seul, et en PDF un opérateur de remplissage ferme tout sous-chemin ouvert avant de le peindre (ISO 32000-1 §8.5.3). Émettez B ou f pour une polyline de trois points et le lecteur peint un triangle rempli dans la couleur de brosse courante. C’est le V jaune du paragraphe d’ouverture, ou le coin sous une courbe de tendance de graphique. PDFlibPas termine les deux largeurs de polyline par S et ne touche jamais à la brosse, ce qui garde la sémantique GDI intacte : Polygon ferme et remplit, Polyline ne fait ni l’un ni l’autre

Comparaison PDFlibPas d’une polyline en V ouverte exportée depuis EMR_POLYLINE : un convertisseur correct termine le path par l’opérateur de stroke S et ignore la brosse sélectionnée, tandis qu’émettre f ou B ferme implicitement le sous-chemin ouvert selon ISO 32000-1 8.5.3 et peint le coin rempli sous une ligne de graphique
Un opérateur de remplissage ferme tout sous-chemin ouvert avant de peindre, donc les polylines doivent se terminer en S sans h, f ni B sur le sous-chemin

PolylineTo et le crayon qu’elle doit laisser tranquille

EMR_POLYLINETO dessine depuis la position courante à travers chaque point de l’enregistrement, reste ouvert, et laisse la position courante sur le dernier point. L’état du crayon appartient à EMR_SELECTOBJECT et EMR_CREATEPEN, jamais à un gestionnaire d’enregistrement de dessin. Un cas particulier qui éteint le crayon dans un enregistrement n’a rien qui le rallume, donc chaque enregistrement suivant perd son contour. Pour la forme à un seul point, lisez exactement les points que l’enregistrement porte et arrêtez-vous

Les points d’une PolyPolyline se trouvent après le tableau de comptes

Le EMR_POLYPOLYLINE 32 bits stocke nPolys comptes puis cptl points, si bien que les points commencent à l’offset d’octet 32 + nPolys * 4. Le piège est dans la RTL Delphi. L’unité Windows déclare TEMRPolyPolyline avec aPolyCounts et aptl en tableaux à un élément, ce qui fait que aptl[0] n’est le premier point que quand nPolys vaut 1. Indexez aptl directement et chaque enregistrement multi-lignes lit des valeurs de comptes comme coordonnées. Pire, un contrôle de taille bâti sur cet agencement rejette carrément les enregistrements multi-lignes valides. PDFlibPas calcule l’offset de la même façon que pour PolyPolygon et dessine chaque polyline comme son propre sous-chemin ouvert, avec un seul stroke à la fin. Le jumeau 16 bits suit le même motif ; le dessiner segment par segment casserait les jointures de lignes et ignorerait un NULL_PEN sélectionné

Objets par défaut et crochets de path

  • Un device context GDI neuf a déjà BLACK_PEN et WHITE_BRUSH sélectionnés. Un métafichier qui dessine sans un seul EMR_SELECTOBJECT est légal et obtient quand même des contours noirs ; un convertisseur qui part sans crayon écrit n (fin de path, ne peint rien) pour ces enregistrements
  • Dans un crochet BeginPath / EndPath, une Polyline n’utilise ni ne met à jour la position courante, donc elle ouvre un nouveau sous-chemin à son premier point au lieu de rejoindre la figure précédente. Rien n’est peint tant que le crochet n’est pas tracé ou rempli

Enregistrer un métafichier de test avec TMetafileCanvas

Le plus rapide pour passer un convertisseur au banc de ces règles est d’enregistrer les trois appels risqués dans un seul métafichier enrichi avec TMetafileCanvas. La procédure ci-dessous dessine les courbes avec une brosse creuse, puis sélectionne exprès une brosse jaune unie avant la polyline. Un convertisseur correct ignore cette brosse. Tout jaune dans le PDF de sortie signifie que la polyline a été remplie. PolyDraw n’a pas de wrapper TCanvas, il passe donc par l’API Windows sur le handle du canvas, avec des octets de type 3 et 5 pour exercer le drapeau de fermeture

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

procedure BuildPolyTestEmf(const FileName: string);
const
  // Un carré fermé (3 = LINETO + CLOSEFIGURE), puis une figure de Bézier
  // fermée dont le dernier triplet de contrôle finit à 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;    // contours seuls pour les courbes
      // Le point 0 est le départ ; 1..3 et 4..6 sont deux segments cubiques
      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 ouvert avec brosse unie sélectionnée : tracé au trait, jamais
      // fermé en triangle jaune
      Canvas.Brush.Style := bsSolid;
      Canvas.Brush.Color := clYellow;
      Canvas.Polyline([Point(20, 240), Point(120, 160), Point(220, 240)]);
    finally
      Canvas.Free;   // termine l’enregistrement
    end;
    Mf.SaveToFile(FileName);
  finally
    Mf.Free;
  end;
end;

Chaque coordonnée ici tient dans un SmallInt, donc GDI stockera normalement les variantes 16 bits. Atteindre les gestionnaires 32 bits demande un producteur qui les écrit, ou des enregistrements assemblés à la main. Les fichiers faits main ont leur propre piège, et il se manifeste en erreur VCL « Metafile is not valid » : TMetafile.LoadFromStream ne traite le flux comme un EMF que si la longueur restante est strictement supérieure aux 108 octets du TEnhMetaHeader. Un en-tête court, ou un EMF vide d’exactement 108 octets, est pris pour un WMF et rejeté. Écrivez l’en-tête complet de 108 octets, champs d’extension compris, avant le premier enregistrement de test

Importer le métafichier avec ImportEMFFromFile

PDFlibPas importe un EMF au travers de ImportEMFFromFile ou ImportEMFFromStream. Toutes deux renvoient un ID d’image non nul en cas de succès et 0 en cas d’échec. GeneralOptions = 0 garde le tracé vectoriel dont cet article parle, tandis que 1 rastérise le métafichier en bitmap. FontOptions = 1 ajoute les polices que le métafichier emploie et les embarque en subsets. La variante par flux rembobine à la position 0 avant le chargement, donc remettez-lui un flux qui contient le métafichier et rien d’autre

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 en haut à gauche pour DrawImage
    PDF.SetMeasurementUnits(0);    // points
    // FontOptions 1 = ajoute les polices du métafichier en subsets embarqués
    // GeneralOptions 0 = import vectoriel, 1 = bitmap
    ImageID := PDF.ImportEMFFromFile(EmfFile, 1, 0);
    if ImageID = 0 then
      raise Exception.Create('The metafile could not be imported');
    PDF.SelectImage(ImageID);
    // Pour un EMF, ImageWidth / ImageHeight sont la taille du cadre en points
    PDF.DrawImage(36, 36, PDF.ImageWidth, PDF.ImageHeight);

    // La page ne fait qu’invoquer le formulaire importé : q ... cm /Name Do Q
    // (une vérification de cohérence optionnelle à ajouter à votre propre 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;

Un import vectoriel d’EMF devient un form XObject, donc GetPageContentToString ne renvoie que la séquence save, transform, Do et restore. Les opérateurs m, l, c, h et S générés à partir des enregistrements Poly* vivent dans le flux compressé du form XObject. Ouvrez le fichier sauvegardé dans un inspecteur d’objets PDF, décompressez ce flux, et vérifiez trois choses pour le fichier de test ci-dessus : la polyline se termine en S sans h avant, chaque drapeau de fermeture dans les figures PolyDraw a produit un h, et aucun f ni B n’apparaît sur ces sous-chemins. DrawImage met à l’échelle un EMF importé de façon uniforme selon le plus petit de Width et Height, donc le dessin garde son ratio même quand la boîte passée ne le respecte pas

Les utilisateurs de Free Pascal liront comment l’importeur vectoriel EMF de PDFlibPas se compile sous Free Pascal ; la sémantique des enregistrements est identique partout où l’importeur compile

Les comptes de points d’un fichier EMF sont une entrée non fiable

Chaque compte de points d’un métafichier devrait être vérifié contre la taille de l’enregistrement avant de copier le moindre point. EnumEnhMetaFile garantit seulement que le nSize de chaque enregistrement reste dans le fichier. Elle ne vérifie jamais que cptl concorde avec nSize. Un gestionnaire qui copie cptl points avec Move lira joyeusement dans les enregistrements suivants, ou au-delà de la fin du métafichier, dès que le compte est forgé ou corrompu. PDFlibPas compare en-tête fixe plus compte fois octets par point contre nSize pour PolyDraw, PolyBezier, PolyBezierTo, Polyline, PolylineTo et Polygon dans les deux largeurs, en ajoutant un octet par point pour le tableau de types de PolyDraw. Pour les enregistrements PolyPoly, les comptes par figure doivent aussi s’additionner à tout au plus le total déclaré, et les figures à zéro point sont sautées

Nous préférons sauter un enregistrement qui échoue à ce test plutôt que de comprimer le compte à ce qui tient. Un enregistrement comprimé se dessine quand même, et une figure partiellement dessinée dans un rapport est plus difficile à repérer qu’une manquante. Le contrôle est assez court pour se glisser dans votre propre parseur ; cette version valide un EMR_POLYPOLYLINE 32 bits et renvoie un pointeur vers son vrai tableau de points :

uses
  Winapi.Windows;

// Un contrôle à ajouter à votre propre parseur EMF (pas une routine de bibliothèque).
// Renvoie nil sauf si l’enregistrement tient vraiment les points déclarés.
// Les points démarrent après le tableau de comptes : à 32 + nPolys * 4
// octets, pas à aptl[0], que la RTL déclare en tableau à un élément
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;                         // compte forgé ou tronqué
  Total := 0;
  Count := @P^.aPolyCounts[0];    // marche par pointeur : [0..0] déclenche les range checks
  for I := 1 to P^.nPolys do
  begin
    Inc(Total, Count^);
    Inc(Count);
  end;
  if Total > P^.cptl then
    Exit;                         // les figures réclament plus de points qu’il n’y en a
  Result := PPoint(NativeUInt(Rec) + NativeUInt(PointsOffset));
end;

L’ordre compte ici. Le test de tenue des points passe en premier, ce qui prouve que le tableau de comptes se trouve dans l’enregistrement avant que la boucle ne le parcoure. L’arithmétique est en Int64 parce que nPolys * 4 et cptl * 8 calculés en 32 bits peuvent boucler vers un petit nombre et passer la comparaison

La même sémantique d’enregistrements vaut quel que soit le composant qui rend vos rapports. HotPDF EMF et WMF vector import couvre la façon dont ce composant transforme les brosses dégradé et hachure en patterns PDF, et vector graphics, shaders et gradients dans PDFlibPas montre comment dessiner les mêmes formes directement avec l’API de la bibliothèque, sans métafichier du tout

Pour passer vos propres métafichiers de rapports par cet importeur, la page de la bibliothèque PDF PDFlibPas pour Delphi a les détails produit et le téléchargement d’essai