1. 从一组绘图API说起：为什么这些函数值得单独拎出来讲

如果你写过Windows平台下的图形程序，或者维护过一些年代稍早的桌面软件，大概率会在某个WM_PAINT消息处理里见过MoveToEx、LineTo、Polyline这一串函数。它们不像Direct2D、OpenGL那样光鲜，也不像Qt、WPF那样有完整的框架包装，但它们构成了GDI绘图的底层骨架。标题里这一长串函数——POINT、MoveToEx、LineTo、Polyline、PolylineTo、Arc、ArcTo、SetArcDirection、PolyBezier、PolyBezierTo——本质上就是GDI里"画线"这件事的完整工具箱。

很多人第一次接触这些函数时，会觉得它们又老又碎：为什么画条线还要先MoveToEx再LineTo？为什么Polyline和PolylineTo长得几乎一样却要分成两个？Arc和ArcTo的区别到底在哪？SetArcDirection这种函数存在的意义是什么？这些问题在官方文档里往往只有一句干巴巴的说明，真正踩过坑的人才知道，这些设计背后对应的是GDI状态机模型、当前点（current position）机制、以及路径（path）与直接绘制之间的微妙差异。

这篇内容适合三类人：一是正在维护老Windows项目、需要精确控制GDI绘图的开发者；二是想理解GDI底层绘图模型、为迁移到现代图形API打基础的人；三是对Windows图形编程历史感兴趣、想搞清楚这些API设计逻辑的技术爱好者。我会从POINT这个最基础的结构讲起，一路把线段、折线、圆弧、贝塞尔曲线的绘制函数串起来，重点讲清楚每个函数的行为边界、当前点的变化规则、以及实际项目里容易踩的坑。所有内容都基于GDI的通用行为，不涉及任何特定商业项目。

2. POINT结构与当前点机制：一切绘线的起点

2.1 POINT、POINTS与坐标精度问题

POINT是Windows里最基础的坐标结构之一，定义非常朴素：

typedef struct tagPOINT { LONG x; LONG y; } POINT;

两个LONG字段，逻辑坐标下的横纵坐标。看起来简单，但实际用起来有几个细节值得注意。第一，LONG在Windows上是32位有符号整数，范围足够覆盖绝大多数屏幕和打印坐标，但如果你做的是大幅面绘图或者地图类应用，坐标可能超出这个范围，这时候就需要自己做坐标变换或者分块处理。第二，GDI的坐标默认是逻辑坐标，受映射模式（mapping mode）影响，MM_TEXT下1单位等于1像素，但换成MM_LOMETRIC或MM_ANISOTROPIC之后，同样的POINT值代表的物理距离就完全不同了。我见过不少人在MM_TEXT下调得好好的代码，一换映射模式就画歪了，根源就是没意识到POINT里的数值是逻辑坐标。

还有一个容易混淆的结构叫POINTS，字段是SHORT类型：

typedef struct tagPOINTS { SHORT x; SHORT y; } POINTS;

它主要用于消息传递（比如WM_MOUSEMOVE的lParam打包），精度只有16位。如果你从消息里取坐标然后直接塞给需要POINT的GDI函数，编译器可能不报错，但数值范围会受限。我建议在消息处理里统一转成POINT再往下传，避免后面出现莫名其妙的坐标截断。

2.2 当前点：GDI绘线的隐藏状态

GDI的线段绘制函数有一个核心概念叫"当前点"（current position）。你可以把它理解成画笔的落点：MoveToEx负责把画笔抬起来挪到某个位置，LineTo负责从当前点画一条线到目标点，画完之后当前点自动更新为目标点。这个机制和很多现代图形API不一样——现代API通常要求你每次显式指定起点和终点，而GDI把起点藏在了设备上下文（DC）的状态里。

MoveToEx的原型是：

BOOL MoveToEx( HDC hdc, int X, int Y, LPPOINT lpPoint );

前三个参数好理解，第四个参数lpPoint用来接收移动前的旧当前点，如果不需要可以传NULL。这个设计其实挺贴心，方便你做"保存-恢复"式的操作。比如你想临时画一条辅助线，画完还要回到原来的位置继续画，就可以先MoveToEx拿到旧点，画完再MoveToEx回去。

这里有个经典坑：MoveToEx失败时返回FALSE，但当前点不会改变。如果你在循环里连续调用，某一次失败后后续的LineTo就会从错误的起点开始画，而且不会有任何报错提示。我的习惯是每次MoveToEx之后检查返回值，至少在调试阶段加上断言。

2.3 为什么GDI要用当前点这种设计

从今天的视角看，当前点机制有点反直觉，但它其实反映了早期绘图仪和笔式绘图机的工作模型——物理笔只有一个位置，画线就是"抬笔移动、落笔画线"的循环。GDI把这套模型抽象成了DC状态，好处是连续画折线时非常自然：一次MoveToEx之后可以接任意多个LineTo，每个LineTo自动以上一个终点为起点，代码写起来很紧凑。

代价是状态管理变复杂了。DC是共享资源，当前点属于DC状态的一部分，如果你在某个函数里改了当前点却没恢复，调用方后续的绘图就可能错位。我在实际项目里养成了一个习惯：凡是会改变当前点的操作，要么在函数开头保存、结尾恢复，要么在函数注释里明确标注"本函数会修改当前点"。这个习惯帮我省了很多排查时间。

3. LineTo与Polyline：单段线与折线的分工

3.1 LineTo的行为细节与边界情况

LineTo的原型：

BOOL LineTo( HDC hdc, int nXEnd, int nYEnd );

它从当前点画一条直线到(nXEnd, nYEnd)，不包含终点像素（这是GDI的约定，线段是左闭右开的），画完后当前点更新为(nXEnd, nYEnd)。注意"不包含终点"这个细节：如果你连续画两条首尾相接的线，接缝处不会重复绘制，这在某些填充算法里很重要。

LineTo有一个容易忽略的行为：如果当前点还没设置过，GDI会默认从(0, 0)开始。这意味着如果你忘了MoveToEx，第一条线会从原点画出来，而且不会有任何警告。我调试过的一个老项目里就有这个问题，界面上莫名其妙多了一条从左上角出发的斜线，查了半天才发现是某个分支忘了MoveToEx。

另外，LineTo在绘制时会使用DC当前的画笔（pen），包括颜色、线宽、线型（实线、虚线等）。线宽大于1时，线段的端点样式由画笔的nPenStyle和dwPenStyle决定，比如PS_ENDCAP_ROUND是圆头，PS_ENDCAP_SQUARE是方头。这些细节在画粗线时影响很大，尤其是折线拐角处，不同端点样式拼出来的效果差别明显。

3.2 Polyline：一次调用画多条线段

Polyline的原型：

BOOL Polyline( HDC hdc, const POINT *apt, int cpt );

它接收一个POINT数组和点数，把数组里相邻的点依次连成线段。比如数组是{P0, P1, P2, P3}，就画P0-P1、P1-P2、P2-P3三条线段。注意它不画闭合段，P3到P0不会自动连上，需要闭合的话得自己在数组末尾再加一个P0。

Polyline和连续调用LineTo的区别主要有两点。第一，性能：Polyline是一次调用画多条线，减少了函数调用开销和状态切换，画大量线段时优势明显。第二，当前点：Polyline不改变当前点，而连续LineTo会把当前点留在最后一个终点。这个差异在混合使用两种方式时特别容易出问题。我一般建议在同一个绘图流程里要么全用Polyline，要么全用LineTo，混用的话一定要清楚当前点在哪。

还有一个细节：Polyline的cpt参数如果小于2，函数直接返回FALSE，什么都不画。这个边界条件在动态生成折线时要注意，比如根据数据点数量决定是否调用，别传了个空数组进去。

3.3 PolylineTo：折线绘制与当前点更新的结合

PolylineTo的原型：

BOOL PolylineTo( HDC hdc, const POINT *apt, DWORD cpt );

它和Polyline几乎一样，唯一的区别是：PolylineTo会把当前点更新为数组最后一个点。这个设计让它适合接在MoveToEx后面，形成"移动到起点、画折线、当前点停在终点"的流程，方便后续继续用LineTo或再次PolylineTo延伸。

选择Polyline还是PolylineTo，取决于你后续要不要继续用当前点。如果折线画完就结束了，用Polyline更干净，不会污染DC状态；如果还要接着画，用PolylineTo可以省一次MoveToEx。我在封装绘图工具类时，通常会把这两个函数都包一层，根据调用场景选择，而不是固定用某一个。

这里有个实测经验：PolylineTo的cpt参数类型是DWORD，而Polyline是int。虽然实际传值不会有问题，但在写跨平台或严格类型检查的代码时要注意这个差异，避免类型转换警告。

4. Arc、ArcTo与SetArcDirection：圆弧绘制的三个关键点

4.1 Arc的绘制逻辑与矩形边界

Arc的原型：

BOOL Arc( HDC hdc, int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4 );

参数看起来多，其实逻辑很清晰：(x1, y1)和(x2, y2)定义一个边界矩形，圆弧就在这个矩形内切椭圆上；(x3, y3)是圆弧起点，(x4, y4)是圆弧终点。GDI会从椭圆中心向这两个点各引一条射线，射线与椭圆的交点就是实际的弧起止点。

这个"射线求交"的机制意味着：起止点不需要精确落在椭圆上，只要方向对就行。实际项目里我经常用角度算出来的点，即使有浮点误差也不影响结果。但反过来说，如果起止点恰好都在椭圆中心，射线方向未定义，绘制结果就不可预测了。所以传参时要确保起止点不等于矩形中心。

Arc画完之后不改变当前点，也不填充。它只画弧线本身，两端是开放的。如果要画扇形或弓形，需要配合Pie或Chord，那是另一组函数了。

4.2 ArcTo与当前点的联动

ArcTo的原型：

BOOL ArcTo( HDC hdc, int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4 );

参数和Arc完全一样，区别在于：ArcTo会把当前点更新为弧的终点，并且如果当前点与弧起点不重合，还会先画一条从当前点到弧起点的直线。这个行为第一次见会觉得奇怪，但结合当前点机制就说得通了——ArcTo的设计目标是"从当前点平滑过渡到弧"，所以它会自动补上连接线。

这个自动连线有时候是想要的，比如画圆角矩形时，直线段和圆角弧之间需要连接；有时候是多余的，比如你只想画一段独立的弧，结果多了一条线出来。我的做法是：用ArcTo之前先MoveToEx到弧的起点，这样当前点和弧起点重合，就不会有多余连线。这个技巧在画复杂路径时特别有用。

4.3 SetArcDirection：控制弧的走向

SetArcDirection的原型：

int SetArcDirection( HDC hdc, int dir );

dir可以是AD_COUNTERCLOCKWISE（逆时针）或AD_CLOCKWISE（顺时针），默认是逆时针。这个函数影响Arc、ArcTo、Pie、Chord等所有圆弧类函数的绘制方向。

为什么方向重要？因为同样的起止点，顺时针和逆时针画出来的弧是互补的两段。比如起点在椭圆右侧、终点在左侧，逆时针画的是上半弧，顺时针画的是下半弧。很多人在画仪表盘、进度环时被这个方向搞晕，其实就是没设置SetArcDirection。

这个函数返回旧的方向值，方便恢复。我建议在修改方向的代码块前后成对调用，避免影响后续绘图。另外注意，SetArcDirection是DC状态的一部分，和当前点一样，跨函数调用时要注意状态污染。

5. PolyBezier与PolyBezierTo：贝塞尔曲线的批量绘制

5.1 贝塞尔曲线的控制点规则

PolyBezier的原型：

BOOL PolyBezier( HDC hdc, const POINT *apt, DWORD cpt );

它绘制一条或多条三次贝塞尔曲线。三次贝塞尔曲线需要4个控制点：起点、两个控制点、终点。PolyBezier的数组规则是：第一个点是起点，之后每3个点构成一段曲线。所以点数必须是1 + 3n的形式，比如4、7、10……如果点数不满足这个规则，函数行为未定义，可能画出一堆乱七八糟的线。

这个规则在实际使用中很容易搞错。我见过有人传了5个点想画两段曲线，结果第二段只取了部分控制点，画出来的形状完全不对。正确的做法是：要画n段贝塞尔曲线，数组长度必须是3n + 1。比如两段曲线需要7个点：起点、控制点1、控制点2、中间点、控制点3、控制点4、终点。

PolyBezier不改变当前点，也不使用当前点作为起点——起点完全由数组第一个点决定。这一点和LineTo、ArcTo不同，用的时候要区分清楚。

5.2 PolyBezierTo与当前点的衔接

PolyBezierTo的原型：

BOOL PolyBezierTo( HDC hdc, const POINT *apt, DWORD cpt );

它和PolyBezier的区别同样是当前点：PolyBezierTo会先画一条从当前点到数组第一个点的直线，然后以数组第一个点为起点画贝塞尔曲线，最后把当前点更新为最后一个点。数组规则和PolyBezier一样，需要3n + 1个点。

这个"自动连线"特性和ArcTo类似，设计意图是支持连续路径绘制。比如你要画一条由直线段和贝塞尔曲线组成的平滑路径，可以用MoveToEx定位起点，然后交替调用LineTo和PolyBezierTo，当前点会自动衔接，不需要手动管理每一段的起点。

但如果你只想画独立的贝塞尔曲线，用PolyBezierTo之前一定要MoveToEx到曲线起点，否则会多出一条从当前点（可能是(0,0)）到曲线起点的线。这个坑我在早期项目里踩过，界面上突然出现一条长斜线，查了半天才发现是PolyBezierTo的自动连线。

5.3 贝塞尔曲线的实际应用场景

贝塞尔曲线在UI里最常见的用途是平滑曲线和圆角。比如画一个自定义的图表，数据点之间用贝塞尔曲线连接会比直线段自然很多；再比如画圆角矩形，四个角可以用贝塞尔曲线近似，比ArcTo更灵活，因为可以单独调整每个角的曲率。

实际调参时，控制点的位置决定了曲线的"胖瘦"。两个控制点离起点和终点越远，曲线越鼓；越近，曲线越平。我通常先用一个系数（比如0.4）乘以相邻点距离来估算控制点位置，然后根据视觉效果微调。这个系数没有标准答案，取决于具体的设计需求。

性能方面，PolyBezier和PolyBezierTo一次调用可以画多段曲线，比每段单独调用效率高。但贝塞尔曲线的计算量比直线大，如果曲线段数很多（比如上千段），要考虑是否值得用更高级的图形API替代。不过在普通UI场景下，几十到几百段曲线，GDI完全够用。

6. 当前点状态管理：那些年我们一起踩过的坑

6.1 当前点被意外修改的典型场景

当前点属于DC状态，任何会修改它的函数都可能影响后续绘图。除了前面提到的LineTo、PolylineTo、ArcTo、PolyBezierTo，还有一些不那么明显的函数也会动当前点，比如AngleArc、Chord（某些实现下）、以及路径相关函数。我在维护一个老绘图模块时，遇到过最隐蔽的一次：某个辅助函数内部调用了LineTo画了条不可见的线（颜色和背景一样），结果把当前点改了，导致调用方后续的折线全部错位。这种问题靠肉眼审查代码很难发现，后来我加了一个调试版本的DC包装类，每次当前点变化都打日志，才定位到。

我的建议是：在团队协作的项目里，约定一个规则——凡是会修改当前点的函数，函数名或注释里必须明确标注。如果项目允许，可以封装一层自己的绘图接口，把当前点管理集中起来，避免散落在各处。

6.2 保存与恢复当前点的正确姿势

GDI提供了SaveDC和RestoreDC来保存和恢复整个DC状态，包括当前点、画笔、画刷、映射模式等。这是最彻底的方案：

int saved = SaveDC(hdc); // 一系列绘图操作，可能修改当前点 RestoreDC(hdc, saved);

SaveDC返回一个保存标识，RestoreDC用它恢复。这个方案的好处是万无一失，坏处是有一定开销，而且如果嵌套层次多了容易搞混。对于只需要保存当前点的场景，可以用MoveToEx的第四个参数：

POINT oldPt; MoveToEx(hdc, x, y, &oldPt); // 绘图操作 MoveToEx(hdc, oldPt.x, oldPt.y, NULL);

这种方式更轻量，但只恢复当前点，不恢复其他状态。选择哪种取决于你的具体需求。我在画复杂图形时通常用SaveDC，因为往往还需要恢复画笔和画刷；画简单辅助线时用MoveToEx就够了。

6.3 多线程环境下的DC状态问题

GDI的DC不是线程安全的。如果多个线程共享同一个DC，当前点和其他状态可能被并发修改，导致绘图结果不可预测。正确的做法是每个线程使用自己的DC，或者通过消息机制把绘图请求集中到UI线程处理。

我在一个后台渲染项目里见过这个问题：工作线程直接拿窗口DC画图，偶尔出现线条错位，但复现率很低。后来改成工作线程画到内存DC，再通过BitBlt一次性拷贝到窗口DC，问题就消失了。这个方案还有个额外好处：内存DC的绘图不会闪烁，适合频繁更新的场景。

7. 性能与选型：什么时候用哪个函数

7.1 批量绘制优先用Poly系列

如果你的场景是画大量线段或曲线，优先用Polyline、PolylineTo、PolyBezier、PolyBezierTo，而不是循环调用LineTo。原因很简单：每次函数调用都有开销，包括参数压栈、状态检查、坐标转换等。批量函数把这些开销摊薄到一次调用里，点数越多优势越明显。

我做过一个粗略的对比测试：画10000条线段，循环LineTo大概比一次Polyline慢30%到50%，具体取决于线段长度和系统负载。对于实时性要求高的场景，这个差距值得注意。

7.2 圆弧与贝塞尔的取舍

画圆弧时，Arc和ArcTo是直接选择。但如果圆弧需要和其他线段平滑连接，ArcTo的自动连线特性能省不少事。贝塞尔曲线则更适合需要自由曲率的场景，比如手绘风格的曲线、自定义圆角等。

有一个实际经验：GDI的Arc在画大半径圆弧时，边缘可能会有轻微锯齿，这是GDI本身的限制。如果对画质要求高，可以考虑用PolyBezier近似圆弧，通过增加控制点来平滑边缘。不过这会增加计算量，需要权衡。

7.3 坐标精度与映射模式的影响

前面提到过，POINT是逻辑坐标，受映射模式影响。在MM_TEXT下，坐标就是像素，最直观；在其他映射模式下，坐标需要经过变换。如果你的绘图需要缩放、旋转，用映射模式可以省去手动计算，但要注意变换后的坐标精度损失。

我的建议是：除非有明确的缩放需求，否则默认用MM_TEXT，所有坐标自己管理。这样逻辑最清晰，调试也方便。需要缩放时，在绘图前统一做坐标变换，而不是依赖映射模式。

8. 从GDI到现代API：这些函数教会我们什么

8.1 状态机模型的利与弊

GDI的当前点机制是典型的隐式状态模型。好处是连续绘图时代码简洁，坏处是状态管理复杂、容易出错。现代图形API（如Direct2D、Skia）大多改成了显式传参，每次绘制都指定完整的几何信息，虽然代码啰嗦一点，但可预测性强很多。

理解GDI的状态机模型，有助于理解为什么现代API要那样设计。比如Direct2D的DrawLine需要传起点和终点，就是因为设计者吸取了隐式状态的教训。如果你从GDI迁移到Direct2D，最大的思维转变就是从"管理状态"变成"描述几何"。

8.2 路径与直接绘制的区别

GDI里还有一套路径（path）机制，通过BeginPath、EndPath、StrokePath等函数，可以先把多条线段、曲线记录到路径里，再一次性描边或填充。路径机制比直接绘制更灵活，支持复杂的填充规则和变换。

标题里的这些函数都是直接绘制，不涉及路径。但实际项目里，路径和直接绘制经常混用。比如先用PolyBezierTo画一条曲线路径，再用StrokePath描边，可以避免中间状态的干扰。理解两者的区别，能让你在合适的场景选合适的工具。

8.3 老API的维护价值

这些GDI函数虽然年代久远，但在很多存量项目里仍然是主力。维护这类项目时，与其推倒重来，不如先把现有代码的状态管理理清楚，把常见的坑填上。我见过太多项目因为一个小绘图bug反复返工，最后发现根源就是当前点没管理好。

如果你正在维护这类代码，我的建议是：先写一个简单的DC状态跟踪工具，记录每次绘图前后的当前点、画笔、画刷，跑一遍主要流程，把异常状态变化找出来。这个投入不大，但能省下大量排查时间。

9. 几个实测有效的调试技巧

调试GDI绘图问题时，光看代码往往不够，因为很多问题出在运行时状态上。我常用的几个技巧：第一，用GetCurrentPositionEx随时查询当前点，在关键位置打日志；第二，把绘图结果输出到内存DC，再保存成图片，方便对比预期和实际；第三，对于复杂的折线和曲线，先用不同颜色分段绘制，确认每一段的起止点是否正确。

还有一个笨但有效的办法：把画笔设成醒目的颜色（比如红色），线宽设成1，先确认几何形状对不对，再调样式。很多问题其实是几何错误，而不是样式问题，先排除几何能省不少事。

另外，Polyline和PolyBezier这类批量函数，如果结果不对，先把点数减到最少（比如只画一段），确认基本逻辑正确，再逐步增加点数。这样能快速定位是数据问题还是调用问题。

10. 写在最后：一些个人体会

这些GDI绘图函数我用了很多年，从最初照着文档抄，到后来能凭经验判断该用哪个，中间踩的坑不计其数。最大的体会是：GDI的API设计有它的历史合理性，但用的时候一定要清楚每个函数对DC状态的影响，尤其是当前点。把状态管理做好了，这些函数其实很稳；状态管理乱了，再简单的图形也会出问题。

如果你刚开始接触这些函数，建议从MoveToEx+LineTo这个最小组合开始，把当前点的变化规律摸清楚，再逐步扩展到折线、圆弧、贝塞尔曲线。每学一个新函数，先问自己三个问题：它读当前点吗？它改当前点吗？它和已有函数怎么配合？把这三个问题搞清楚，基本就不会出大错了。

最后分享一个小习惯：我在写任何涉及GDI绘图的函数时，都会在函数头注释里写一行"当前点：读/写/不变"，这个习惯帮我避免了很多跨函数的隐蔽bug。如果你也在维护GDI代码，不妨试试。