从 PDF 内容流示例里抄来的一条页脚横线写着 72 72 m 540 72 l S:移到 (72, 72),画线到 (540, 72),描边。在原始 PDF 里这条线位于 US Letter 页面底边上方一英寸处。把同样四个数喂给一个从左上角起测的绘图 API,横线就落到顶部下方一英寸,正好穿过信头。线本身没有任何问题,变的只是参照系,而在 792 磅的页面上在两个参照系之间移动就是一次减法:792 减 Y
HotPDF 页面上 Y = 0 在哪里?
HotPDF 的页面绘制调用把原点放在页面左上角,X 向右增长、Y 向下增长,与 VCL TCanvas 用的是同一个参照系。PDF 用户空间定义在 ISO 32000-1 §8.3.2.3,从左下角开始、Y 向上增长,HotPDF 会在写内容流时转换你传入的每一个 Y。所以在 THotPDF.CurrentPage 上 Y := 72 的意思是顶部边缘下方一英寸,无论页面多大
页面尺寸关系到另一头。US Letter 页面是 612 × 792 磅,Y := 720 在底部上方一英寸。不特意说明时,新的 HotPDF 页面是 A4,而 A4 高 842 磅,同一个 Y := 720 下面还剩 122 磅,约 1.7 英寸。用 792 减出来的页脚在 A4 上向上漂,原因正是这个。高度请从 CurrentPage.Height 读,别硬编码;或者在 BeginDoc 之后立刻显式设置 CurrentPage.Size
单位是磅,1/72 英寸,因为 THotPDF.Resolution 默认 72。调高 Resolution 会让坐标和尺寸改按 1/Resolution 英寸计。矢量绘图请把它留在 72:线宽、虚线长度和坐标于是都与 PDF 文件存储的单位一致,内容流里看到的值和源码里的值能对上
文字遵循同一个模型。默认情况下你给 TextOut 的 Y 是文本的顶边,所以标签和它的外框在同一张网格上规划。少数几个调用作用于 PDF 文件而不是绘图表面、使用自下而上的 PDF 坐标:诸如 SetCropBox(Left, Bottom, Right, Top) 的页面框设置器,以及给已加载文档盖章的 StampLoadedPageText / StampLoadedPageImage 系列。把这两类和路径调用混在一起,正是大多数上下颠倒布局的来历,请把它们放进各自独立的过程
构建路径并绘制它
路径先构建、后绘制。MoveTo 设一个起点但不标记任何东西,每个 LineTo 加一段直线,在 Stroke 这样的绘制调用用当前描边色和线宽消费它之前,什么都不会出现在页面上。用 PDF 的话说,Stroke 发出的是 S 运算符,而每个绘制运算符都会结束当前路径,所以下一个 MoveTo 从干净状态开始
var
Pdf: THotPDF;
begin
Pdf := THotPDF.Create(nil);
try
Pdf.FileName := 'DrawPaths.pdf';
Pdf.BeginDoc;
Pdf.CurrentPage.Size := Letter; // 612 x 792 磅;默认是 A4
// 线宽和颜色是页面状态:设一次,之后每次 Stroke 都用它
Pdf.CurrentPage.SetLineWidth(1.5);
Pdf.CurrentPage.SetRGBStrokeColor(clBlack);
// 顶部下方一英寸的一条横线,两边各留 72 磅边距
Pdf.CurrentPage.MoveTo(72, 72);
Pdf.CurrentPage.LineTo(540, 72);
Pdf.CurrentPage.Stroke;
// 开篇那条页脚横线:底部上方一英寸
Pdf.CurrentPage.MoveTo(72, Pdf.CurrentPage.Height - 72);
Pdf.CurrentPage.LineTo(540, Pdf.CurrentPage.Height - 72);
Pdf.CurrentPage.Stroke;
// 一条路径里三段相连的线段,更粗、蓝色
Pdf.CurrentPage.SetLineWidth(3);
Pdf.CurrentPage.SetRGBStrokeColor(RGB(30, 90, 200));
Pdf.CurrentPage.MoveTo(72, 152);
Pdf.CurrentPage.LineTo(172, 102);
Pdf.CurrentPage.LineTo(272, 172);
Pdf.CurrentPage.LineTo(372, 112);
Pdf.CurrentPage.Stroke;
Pdf.EndDoc;
finally
Pdf.Free;
end;
end;
线宽是状态,不是参数。SetLineWidth 写一个 w 运算符,之后页面上每一次描边都用这个宽度,直到你改它——这就是折线出来是 3 磅、两条横线保持 1.5 的原因。从不设置的话,适用 PDF 默认值 1.0(ISO 32000-1 §8.4.3.2)。形状缺失的原因更平淡:铺了几何、后面却没有绘制调用的东西永远不会渲染
坐标和宽度都是 Single,所以 72.25 和 0.5 磅的发丝线都能原样进文件。零是特例。规范把宽度 0 定义成输出设备能画出的最细线:屏幕上任何缩放级别都是一个像素,600 dpi 打印机上就是 1/600 英寸,于是同一条规则在查看器里看着挺粗、到纸上几乎消失。发丝线请选个真实宽度,比如 0.25 或 0.5,线条在每台设备上都保住自己的分量
为什么闭合的三角形一个角上有个缺口?
用三个 LineTo 回到起点画的三角形看着闭合,但在 PDF 里它仍是一条开放子路径。ISO 32000-1 §8.5.3.2 只在子路径内部线段相交处应用斜接;两个自由端得到的则是线帽。默认平头帽配 6 磅笔,起始角上就会咬掉一块方形,另外两个角是干净的斜接。ClosePath(h 运算符)补上最后一段,并告诉渲染器把它与第一段相接
Pdf.CurrentPage.SetLineWidth(6);
Pdf.CurrentPage.SetRGBStrokeColor(clBlack);
// 看着闭合,其实没有:平头端帽在 (72, 500) 相遇,留下缺口
Pdf.CurrentPage.MoveTo(72, 500);
Pdf.CurrentPage.LineTo(132, 420);
Pdf.CurrentPage.LineTo(192, 500);
Pdf.CurrentPage.LineTo(72, 500);
Pdf.CurrentPage.Stroke;
// 闭合子路径:三个角都得到同样的斜接
Pdf.CurrentPage.MoveTo(232, 500);
Pdf.CurrentPage.LineTo(292, 420);
Pdf.CurrentPage.LineTo(352, 500);
Pdf.CurrentPage.ClosePath;
Pdf.CurrentPage.Stroke; // 或一次调用 ClosePathStroke
// Fill 不需要 ClosePath:填充隐式闭合每个子路径
Pdf.CurrentPage.SetRGBFillColor(RGB(220, 60, 60));
Pdf.CurrentPage.MoveTo(392, 500);
Pdf.CurrentPage.LineTo(452, 420);
Pdf.CurrentPage.LineTo(512, 500);
Pdf.CurrentPage.Fill;
打算描边的每个多边形都用 ClosePath 或 ClosePathStroke 闭合,哪怕最后一个点已经与第一个重合。1 磅时缺口在屏幕上看不见;6 磅时正常缩放就露馅,印在图表图例里就像渲染毛刺。填充图形没有这个问题;路径自交、想用奇偶规则代替非零环绕时,还有 EoFill 在
矩形、圆形与 TCanvas 的肌肉记忆
封闭图元省掉 MoveTo 的记账。Rectangle(X, Y, Width, Height) 收左上角和尺寸,Circle(X, Y, Radius) 收圆心和半径,两者都能用 Fill、Stroke 或 FillAndStroke 绘制。填充色与描边色相互独立:SetRGBFillColor 和 SetRGBStrokeColor 各收一个 TColor,Delphi 颜色常量和 RGB(...) 直接可用,SetRGBColor 则一次设两个
Rectangle 的参数形状是陷阱。TCanvas.Rectangle 收 (Left, Top, Right, Bottom),多年 VCL 绘制代码把你的手指训练成了传第二个角。把 Rectangle(72, 202, 232, 292) 递给 HotPDF,得到的是一个 232 磅宽、292 磅高的框,而不是 160 × 90。手里有的数真是两个角时,调用 MFRectangle(X, Y, X1, Y1)——它收角坐标、替你算尺寸;Rectangle 留给按尺寸思考的代码
PDF 文件里没有圆运算符。Circle 写四段三次贝塞尔,控制点系数是惯用的 0.5523——解压页面内容流就能看到:一个 m 跟四个 c 运算符。Ellipse(X, Y, Width, Height) 在左上角为 (X, Y) 的外接框里做同样的事
HotPDF 还暴露 THotPDF.Canvas——当前页面的一个标准 TCanvas,Graphic 示例里的 CanvasDraw 程序就是用普通的 Canvas.Rectangle、Ellipse 和 RoundRect 调用填满一页 Ledger。移植既有 VCL 绘制代码时这条路是合理的。新写的绘图代码更适合待在 CurrentPage 上:每个调用对应一个以磅计的 PDF 运算符,输出能精确预测到具体数值
四次提交拼出一个标注框
标注框把上面的东西一次用全:一块填充加描边的面板、一条指示线、一个锚点圆点,以及放进面板里、与图形共用同一套左上坐标的两行文字。FillAndStroke(B 运算符)一次调用画出同一条路径的内部和边框,矩形只需构建一次而不是两次
procedure DrawCallout(Page: THPDFPage);
begin
// 1. 面板:浅色填充加更深的边框,一条路径,一次提交
Page.SetRGBFillColor(RGB(255, 244, 214));
Page.SetRGBStrokeColor(RGB(180, 130, 40));
Page.SetLineWidth(1);
Page.Rectangle(90, 122, 240, 70); // 左上角 (90, 122),240 x 70
Page.FillAndStroke;
// 2. 指示线:从面板左边缘引向目标
Page.SetLineWidth(1.5);
Page.MoveTo(90, 177);
Page.LineTo(66, 246);
Page.Stroke;
// 3. 指示线末端的锚点圆点,用边框颜色
Page.SetRGBFillColor(RGB(180, 130, 40));
Page.Circle(64, 250, 3);
Page.Fill;
// 4. 标签:每个 Y 都是文本顶边,在同一网格上测量
Page.SetFont('Arial', [fsBold], 10);
Page.TextOut(102, 134, 0, 'Check this total');
Page.SetFont('Arial', [], 9);
Page.TextOut(102, 152, 0, 'Rounded to two decimals per line,');
Page.TextOut(102, 164, 0, 'then summed');
end;
// 在 BeginDoc 和 EndDoc 之间调用:
// DrawCallout(Pdf.CurrentPage);
每个块都在需要它的形状之前设置自己的填充色、描边色和宽度,哪怕上一块留下的值相同。这在文件里多花几个冗余运算符。换来的是:任何一块都可以移动、删除或独立成过程,而不必从前一块那里继承一抹莫名的红色填充——对随报表变化而变化的绘图代码来说,这笔交易每次都值得做
颜色值得同样的纪律。用 Random($FFFFFF) 播种填充色,演示页看着活泼,生成式报告却没法在两次运行之间比较,因为同样数据构建的两份产物字节不同。让颜色来自数据或固定调色板数组——CanvasDraw 示例用它的八项 CanvasColors 表就是这么做的——同样的输入就产出同样的文件
虚线、曲线与透明度
SetDash 和线宽一样是页面状态。SetDash([3, 3], 0) 让之后的每次描边都画 3 磅、空 3 磅,第二个参数挪动图案的起点,NoDash 恢复实线。虚线数组是 array of Byte,长度是 1 到 255 的整磅数,并按给定值原样写进内容流。为一组网格线设的虚线会一直延续到后面每条线,所以把虚线那一节用 GStateSave 和 GStateRestore 包起来:它们发出 q 和 Q,恢复保存的状态一步带回之前的虚线、宽度和颜色
曲线延伸同一条路径。CurveToC(X1, Y1, X2, Y2, X3, Y3) 从当前点加一段到 (X3, Y3) 的三次贝塞尔,带两个控制点;CurveToV 和 CurveToY 覆盖第一或第二控制点与端点重合的情形。一条路径可以在一次 Stroke 或 Fill 之前混用 LineTo 和 CurveToC 段——圆角和顺滑的图表折线就是这么画的
透明度住在命名图形状态里,因为 PDF 把 alpha 存在 ExtGState 字典而不是颜色里。THotPDF.RegisterExtGState(FillAlpha, StrokeAlpha) 收 0 到 1 的值并返回一个名字;CurrentPage.SetGraphicsState(Name) 把它应用到之后绘制的一切。每档不透明度每个文档注册一次、复用名字,文件里每档就只有一个字典,多少形状在用都一样。alpha 需要 PDF 1.4,HotPDF 会在需要时把输出版本抬到 1.4;设了 StrictVersionLock 则不动版本、返回空名字。PDFACompliance 选中 PDF/A-1 配置时,低于 1 的 alpha 抛异常,因为 ISO 19005-1 §6.4 在那里禁止透明;PDF/A-2 和 PDF/A-3 配置接受它
var
Half: AnsiString;
begin
// 每个文档注册一次,在任意页面上复用返回的名字
Half := Pdf.RegisterExtGState(0.5, 1.0); // 50% 填充,不透明描边
Pdf.CurrentPage.GStateSave; // q
Pdf.CurrentPage.SetDash([3, 3], 0);
Pdf.CurrentPage.SetLineWidth(0.5);
Pdf.CurrentPage.SetRGBStrokeColor(clGray);
Pdf.CurrentPage.MoveTo(72, 400);
Pdf.CurrentPage.LineTo(540, 400);
Pdf.CurrentPage.Stroke;
Pdf.CurrentPage.SetGraphicsState(Half);
Pdf.CurrentPage.SetRGBFillColor(clYellow);
Pdf.CurrentPage.Rectangle(72, 380, 200, 16); // 文字行上方的高亮
Pdf.CurrentPage.Fill;
Pdf.CurrentPage.GStateRestore; // Q:实线画笔,恢复完全不透明
end;
矢量调用适合程序算出来的几何:表格线、图表的轴和柱、标注框、十几条路径拼出的 Logo。照片或截图属于 AddImage 和 ShowImage;用路径去描像素只会把文件变大。检查输出时,把粗描边的角和任何虚线放大到 1600%:未闭合路径的缺口和漏出自己那一节的虚线在这个倍率下都很扎眼,在 100% 下却容易漏过
本文的每个调用都住在 HotPDF Delphi Component 的页面对象上,它运行在 Delphi 和 C++Builder 的 VCL 工程里,把结果写成朴素的 PDF 路径运算符