技術文章

PDFlibPas EMF 匯入:PolyDraw、Polyline、Bezier 規則

在選了黃色筆刷的狀態下用 Canvas.Polyline 畫一個三點的 V,把中繼檔轉成 PDF,天真的轉換器會交回一個實心黃三角。同一個轉換器還可能把貝茲曲線彎向錯的控制點,讓 PolyDraw 的矩形少一邊。每個案例都追溯到一條 [MS-EMF] 規則:EMR_POLYBEZIER 從點 0 開始、多邊線是開放且只描邊的、PT_CLOSEFIGURE 是旗標位元、點數必須塞得進記錄大小

裝置環境有 PDF 路徑沒有的狀態

增強型中繼檔是對裝置環境發出的 GDI 呼叫的錄製,而 Poly* 記錄的意義有一半活在它的點之外:圖形是開是合、要不要從目前位置起筆、選了哪支畫筆與筆刷、點從哪個位元組偏移開始。PDF 這些都沒有;它有路徑、路徑裡的目前點,以及挑選描邊(S)、填色(f)或兩者(B)的繪製運算子。PDFlibPas——losLab 的 Delphi PDF 程式庫——的向量 EMF 匯入器,讓裝置環境狀態與座標一起重播,下面的規則描述它怎麼映射每種記錄

Poly* 家族還有兩種寬度。每個 32 位元記錄如 EMR_POLYLINE,都有一個 16 位元雙胞胎如 EMR_POLYLINE16,把點存成 SmallInt 對;只要每個座標都塞得下,GDI 就記緊湊形式。日常圖形因此很少走到轉換器的 32 位元處理器。把同一批點分別餵兩種寬度、比較路徑,這是最便宜的稽核。本文涵蓋的所有記錄屬於 [MS-EMF] 2.3.5 的繪圖記錄群組

記錄起點閉合?目前位置
EMR_POLYBEZIER點 0否不使用、不更新
EMR_POLYLINE點 0否(只用畫筆)不使用、不更新
EMR_POLYLINETO目前位置否(只用畫筆)使用並更新
EMR_POLYPOLYLINE每條多邊線的第一點否(只用畫筆)不使用、不更新
EMR_POLYDRAW第一個 PT_MOVETO,或目前位置只有設了 PT_CLOSEFIGURE 處使用並更新

EMR_POLYBEZIER 曲線實際上從哪裡開始?

EMR_POLYBEZIER 曲線從點 0 開始,只有索引 1 起的點才三個一組:控制點、控制點、終點。7 個點的記錄畫兩段三次曲線:點 0 是起點,點 1 到 3 是第一段,4 到 6 是第二段。若從點 0 開始分組,起點就被吞成第一個控制點,之後每一段都位移一位。輸出仍是一條平滑曲線——只是不是那條。PDFlibPas 在兩種記錄寬度下,都以 m 在點 0 開路徑,之後每個完整三元組寫一個 c

PDFlibPas 圖解七點的 EMR_POLYBEZIER 記錄:點零以 m 開路徑,點一到三與四到六各組成一段三次 c;並對照正確分組與把起點吞成控制點的錯誤分組
點 0 是起點,只有它之後的完整三元組才成為三次曲線段,七點 PolyBezier 於是渲染成 m 加兩個 c 運算子

那麼數量不是「1 加 3 的倍數」呢?記錄是畸形的。我們的立場是捨棄尾端那一兩個點。靠發明一個不存在的控制點把它們縫進曲線,產出的是任何 GDI 裝置都沒畫過的形狀,而拿 PDF 與原件對照的讀者無從分辨曲線哪一半是編出來的

PolyDraw 的型別位元組 3 與 5

在 EMR_POLYDRAW 裡,PT_CLOSEFIGURE(值 1)是被 OR 進 PT_LINETO(2)或 PT_BEZIERTO(4)的位元,所以完全合法的型別位元組可以是 3 或 5。點型別是遮掉那個位元之後的位元組;旗標本身的意思是「在以這個點收尾的段之後閉合圖形」。用 Pascal case 對單一值比對位元組的處理器,永遠等不到 3 或 5 命中——那些點被跳過。用 PolyDraw 畫的矩形少了收尾那一邊;尾點帶旗標的貝茲三元組丟了那個點,之後每個三元組就都錯位一個

PDFlibPas 以 Types[i] and not PT_CLOSEFIGURE 分派,而且只在一段完成後才閉合:閉合的 PT_LINETO 緊跟在直線之後、貝茲群組在第三個點之後。因此在三元組的第一或第二點上設旗標的畸形檔案,不會把曲線閉在半路。同一個處理器裡還有兩條規則:

  • 記錄裡只有第一個 PT_MOVETO 起路徑;後面的 move 開新子路徑。帶三個圖形的 16 位元 EMR_POLYDRAW16 必須產出三個子路徑,每個 move 都重啟路徑的處理器只留最後一個
  • 不以 PT_MOVETO 開頭的 PolyDraw 記錄從目前位置起筆,記錄定義是這麼說的。沒有前置 m 就寫 l 或 c 運算子,是內容串流錯誤,每個 PDF 閱讀器各有各的解法
PDFlibPas 解剖 EMR_POLYDRAW 型別位元組:PT_CLOSEFIGURE 是被 OR 進 PT_LINETO 或 PT_BEZIERTO 的旗標位元零,合法型別位元組 3 與 5 必須先以 and not PT_CLOSEFIGURE 遮罩再分派;樸素的 case 敘述跳過兩者,閉合圖形於是少了最後一邊
分派之前先遮掉閉合旗標,完成的直線或貝茲三元組之後才發出閉合,否則 PolyDraw 會悄悄丟點

黃三角:多邊線為什麼永不填色

EMR_POLYLINE 與 EMR_POLYPOLYLINE 是只用畫筆畫的開放圖形,而 PDF 裡填色運算子會在繪製之前先閉合任何開放的子路徑(ISO 32000-1 §8.5.3)。給三點多邊線發 B 或 f,閱讀器就用當前筆刷色塗出一個實心三角——正是開頭那個黃 V,或圖表趨勢線下的楔形。PDFlibPas 對兩種多邊線寬度都以 S 收尾、絕不碰筆刷,GDI 語意因此原封不動:Polygon 閉合且填色,Polyline 兩者都不

PDFlibPas 對照從 EMR_POLYLINE 匯出的開放 V 形多邊線:正確的轉換器以描邊運算子 S 收路徑、無視選中的筆刷;發 f 或 B 則會在 ISO 32000-1 8.5.3 之下隱式閉合開放子路徑,把圖表線下的楔形塗滿
填色運算子繪製前會閉合任何開放子路徑,所以多邊線必須以 S 收尾,子路徑上不得出現 h、f 或 B

PolylineTo 與它不得插手的畫筆

EMR_POLYLINETO 從目前位置畫過記錄裡的每一個點、保持開放,並把目前位置留在最後一個點上。畫筆狀態歸 EMR_SELECTOBJECT 與 EMR_CREATEPEN 管,永遠不歸繪圖記錄處理器管。在某個記錄內部順手把筆關掉的特殊情況,沒有任何東西會把它開回來,之後每個記錄都失去輪廓。單點形式,就精確讀記錄持有的點、然後停手

PolyPolyline 的點坐在計數陣列後面

32 位元的 EMR_POLYPOLYLINE 先存 nPolys 個計數、再存 cptl 個點,所以點從位元組偏移 32 + nPolys * 4 開始。陷阱在 Delphi RTL:Windows 單元把 TEMRPolyPolyline 的 aPolyCounts 與 aptl 宣告成單元素陣列,這意味著 aptl[0] 只有在 nPolys 為 1 時才是第一個點。直接索引 aptl,每個多線記錄都會把計數值當座標讀。更糟的是,建在那個版面上的大小檢查會把合法的多線記錄整個拒收。PDFlibPas 用與 PolyPolygon 相同的方式計算偏移,把每條多邊線畫成自己的開放子路徑、最後一次描邊。16 位元雙胞胎遵循同一模式;一段一段畫會破壞線段接合、也無視選中的 NULL_PEN

預設物件與路徑括號

  • 全新的 GDI 裝置環境已經選好了 BLACK_PEN 與 WHITE_BRUSH。一條 EMR_SELECTOBJECT 都沒發就畫圖的中繼檔是合法的、而且照樣有黑輪廓;以無筆狀態起頭的轉換器,對這些記錄會寫 n(結束路徑、什麼都不畫)
  • 在 BeginPath / EndPath 括號內,Polyline 既不使用也不更新目前位置,所以它在自己的第一點開新子路徑、而不是接上前一個圖形。括號被描邊或填色之前什麼都不畫

用 TMetafileCanvas 錄一份測試中繼檔

把轉換器丟進這些規則裡測,最快的辦法是用 TMetafileCanvas 把三個危險呼叫錄進同一份增強型中繼檔。下面的程序先用鏤空筆刷畫曲線,然後刻意在多邊線之前選上實心黃筆刷。正確的轉換器無視那支筆刷;輸出 PDF 裡出現任何黃色,就代表多邊線被填色了。PolyDraw 沒有 TCanvas 包裝,所以走畫布控制代碼上的 Windows API,型別位元組 3 與 5 正好鍛鍊閉合旗標

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

procedure BuildPolyTestEmf(const FileName: string);
const
  // 一個閉合方形(3 = LINETO + CLOSEFIGURE),然後一個閉合貝茲
  // 圖形,其最後的控制三元組以 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;    // 曲線只描邊
      // 點 0 是起點;1..3 與 4..6 是兩段三次曲線
      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 形:只描邊,永不被閉合
      // 成黃三角
      Canvas.Brush.Style := bsSolid;
      Canvas.Brush.Color := clYellow;
      Canvas.Polyline([Point(20, 240), Point(120, 160), Point(220, 240)]);
    finally
      Canvas.Free;   // 結束錄製
    end;
    Mf.SaveToFile(FileName);
  finally
    Mf.Free;
  end;
end;

這裡的每個座標都塞得進 SmallInt,GDI 通常會存 16 位元變體。要走到 32 位元處理器,得靠真的寫出它們的產生器,或手工拼裝的記錄。手造檔案有自己的陷阱,而且以 VCL 的「Metafile is not valid」錯誤現形:TMetafile.LoadFromStream 只在剩餘長度嚴格大於 108 位元組的 TEnhMetaHeader 時,才把串流當 EMF。過短的標頭、或恰好 108 位元組的空 EMF,會被當成 WMF 拒收。第一條測試記錄之前,請把 108 位元組標頭連同擴充欄位寫全

用 ImportEMFFromFile 匯入中繼檔

PDFlibPas 經 ImportEMFFromFile 或 ImportEMFFromStream 匯入 EMF,成功回傳非零影像 ID、失敗回傳 0。GeneralOptions = 0 保留本文談的向量路徑,1 則把中繼檔點陣化。FontOptions = 1 加入中繼檔用到的字型並以子集內嵌。串流變體會先倒回位置 0 再載入,所以請交給它一份只含中繼檔的串流

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);              // DrawImage 的左上原點
    PDF.SetMeasurementUnits(0);    // 點
    // FontOptions 1 = 把中繼檔字型加成內嵌子集
    // GeneralOptions 0 = 向量匯入,1 = 點陣
    ImageID := PDF.ImportEMFFromFile(EmfFile, 1, 0);
    if ImageID = 0 then
      raise Exception.Create('The metafile could not be imported');
    PDF.SelectImage(ImageID);
    // 對 EMF 而言,ImageWidth / ImageHeight 是以點為單位的框架尺寸
    PDF.DrawImage(36, 36, PDF.ImageWidth, PDF.ImageHeight);

    // 頁面只呼叫匯入的表單:q ... cm /Name Do Q
    // (可以加進自己程式碼的選配健全檢查)
    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;

向量的 EMF 匯入會變成 form XObject,所以 GetPageContentToString 只回傳儲存、變換、Do、還原那組序列。從 Poly* 記錄產生的 m、l、c、h 與 S 運算子,住在壓縮的 form XObject 串流裡。用 PDF 物件檢視器打開存出的檔案、解壓那條串流,對上面的測試檔查三件事:多邊線以 S 收尾、前面沒有 h;PolyDraw 圖形裡每個閉合旗標都產出了一個 h;那些子路徑上沒有出現任何 f 或 B。DrawImage 按 Width 與 Height 較小者等比縮放匯入的 EMF,所以即使你傳的框比例不合,圖形也保持長寬比

Free Pascal 使用者可以讀PDFlibPas 的 EMF 向量匯入器如何在 Free Pascal 下建置;無論匯入器在哪裡編譯,記錄語意完全相同

EMF 檔裡的點數是不受信任的輸入

中繼檔裡的每個點數,都應該在複製任何點之前對著記錄大小檢查。EnumEnhMetaFile 只保證每條記錄的 nSize 落在檔案內,從不檢查 cptl 與 nSize 相符。數被偽造或損壞之後,用 Move 複製 cptl 個點的處理器會欣然讀進後續記錄、甚至越過中繼檔結尾。PDFlibPas 對兩種寬度的 PolyDraw、PolyBezier、PolyBezierTo、Polyline、PolylineTo 與 Polygon,都以「固定標頭加點數乘每點位元組」對 nSize 比較,PolyDraw 的型別陣列每點再加一位元組。PolyPoly 記錄的每圖形計數之和也不得超過宣告總數,零點的圖形被跳過

這種測試不過的記錄,我們偏好跳過、而不是把數量夾到塞得下為止。被夾過的記錄照樣畫,報告裡畫了一半的圖形比缺了的圖形更難發現。檢查很短,可以直接放進你自己的剖析器;下面這個版本驗證 32 位元 EMR_POLYPOLYLINE、回傳指向其真正點陣列的指標:

uses
  Winapi.Windows;

// 加進你自己 EMF 剖析器的檢查(不是程式庫常式)。
// 除非記錄真的裝著它宣告的點,否則回傳 nil。
// 點從計數陣列之後開始:偏移 32 + nPolys * 4 位元組,
// 不是 RTL 宣告成單元素陣列的 aptl[0]
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;                         // 偽造或截斷的數量
  Total := 0;
  Count := @P^.aPolyCounts[0];    // 以指標走訪:[0..0] 會觸發範圍檢查
  for I := 1 to P^.nPolys do
  begin
    Inc(Total, Count^);
    Inc(Count);
  end;
  if Total > P^.cptl then
    Exit;                         // 圖形宣稱的點比存在的多
  Result := PPoint(NativeUInt(Rec) + NativeUInt(PointsOffset));
end;

順序在這裡有講究。點數塞得下的測試先跑,迴圈走訪之前就證明了計數陣列落在記錄內。算術用 Int64,因為 nPolys * 4 與 cptl * 8 在 32 位元裡計算會回繞成小數字、騙過比較

同樣的記錄語意,適用於渲染你報表的任何元件。HotPDF 的 EMF 與 WMF 向量匯入講那個元件怎麼把漸層與網紋筆刷變成 PDF 圖樣;PDFlibPas 的向量圖形、著色器與漸層示範怎麼完全跳過中繼檔、用程式庫 API 直接畫同一批形狀

想讓自己的報表中繼檔過這個匯入器,PDFlibPas Delphi PDF library 產品頁有產品細節與試用下載