当前位置：首页 > news >正文

嵌入式GUI开发实战：emWin 2D绘图与图像显示API详解

news 2026/6/21 10:14:45

1. 嵌入式GUI开发中的2D绘图：从原理到emWin实战

在嵌入式系统里做图形界面开发，和我们在PC或者手机上写应用完全是两码事。这里没有现成的、功能强大的GPU，内存可能只有几十KB到几MB，CPU主频也可能就百兆赫兹级别。在这种“螺丝壳里做道场”的环境下，每一个像素的绘制、每一次内存的访问，都得精打细算。图形用户界面（GUI）不再是锦上添花，而是很多设备与用户交互的核心，比如工业触摸屏上的控制按钮、智能手表上的心率曲线、或者车载中控的导航地图。它的核心任务，就是把我们代码里抽象的“画一条线”、“显示一张图”这样的指令，高效、准确地变成屏幕上一系列有颜色的点。

这个过程背后，是一套完整的图形学基础在支撑。首先是坐标系统，通常以屏幕左上角为原点(0,0)，X轴向右，Y轴向下，这与许多数学坐标系不同，需要特别注意。其次是颜色模型，嵌入式屏常见的有RGB565（16位色）、RGB888（24位色）或者甚至灰度屏，颜色值如何转换成屏幕控制器能识别的数据格式是关键。最后是渲染管线，虽然简单，但也包含了坐标变换（比如窗口裁剪）、图元生成（如将一条线的数学描述转换成一系列像素点）、以及最终的帧缓冲（Frame Buffer）写入。

emWin作为SEGGER公司推出的一款老牌嵌入式GUI库，其价值就在于它封装了这些底层复杂性，提供了一套统一、高效的API。它的2D图形库是其基石，我们今天要深入探讨的，就是如何利用这些API，在资源受限的环境下，实现从简单线条到复杂图像的各种绘制需求。掌握它，意味着你能在单片机上也能实现流畅、美观的图形界面，这是嵌入式开发工程师迈向更高阶的必备技能。

1.1 核心需求解析：为什么是emWin的2D API？

在项目初期选择图形库时，我们通常会评估几个维度：资源占用、运行效率、功能完整性和可移植性。emWin在这几个方面表现均衡。

从资源占用看，emWin库本身可以根据需要裁剪，只链接你用到的模块。它的2D绘图API是纯软件实现，不依赖特定硬件加速（当然也支持与硬件加速器对接），这意味着它可以在几乎所有带显示功能的MCU上运行。内存使用上，它提供了内存设备（Memory Device）机制，可以将复杂绘图先在内存中完成，再一次性刷到屏幕，既能解决闪烁问题，又能作为缓存提升重复绘制效率。

运行效率是嵌入式GUI的生命线。emWin的2D库在算法上做了大量优化。例如，绘制水平线（GUI_DrawHLine）和垂直线（GUI_DrawVLine）有专用函数，因为对于大多数LCD控制器，连续的水平或垂直像素操作可以通过设置行/列地址后连续写入数据来完成，比通用的逐点计算直线算法快得多。这种针对性的优化，在频繁绘制表格、边框时效果显著。

功能完整性方面，从基础的线、圆、矩形、多边形，到高级的Alpha混合、位图缩放旋转、以及JPEG/PNG解码，emWin提供了全覆盖。我们今天重点剖析的2D绘图和图像显示API，是构建一切复杂界面的基础构件。

可移植性则由emWin的硬件抽象层（HAL）保证。你只需要为你的显示设备和触摸设备（如果有）提供底层的像素读写函数和触摸读取函数，上层的所有应用代码，包括我们今天讲的所有2D绘图调用，都可以无缝移植。

因此，学习emWin的2D API，不仅仅是学习几个函数调用，更是理解在嵌入式约束下如何进行高效图形编程的思维方式。接下来，我们将从最简单的点线面开始，逐步深入到多边形变换和图像显示。

2. 线条与基本图元绘制：细节与性能考量

绘制线条是图形界面中最基础、最频繁的操作。emWin提供了一组从简到繁的线条绘制函数，理解它们之间的区别和适用场景，是写出高效绘图代码的第一步。

2.1 基础线条绘制API详解

GUI_DrawLine(int x0, int y0, int x1, int y1)是最通用的画线函数，它使用Bresenham算法在两点间绘制一条直线。这个函数的内部逻辑是计算像素路径，适用于任意方向的直线。但正因为其通用性，它包含了斜率计算和判断，在只需要画水平或垂直线时，并不是最优选择。

这时就该使用GUI_DrawHLine(int y, int x0, int x1)和GUI_DrawVLine(int x, int y0, int y1)。这两个函数在源码层面做了极大简化。以水平线为例，它的逻辑大致是：

void GUI_DrawHLine(int y, int x0, int x1) { if (x1 < x0) return; // 参数检查 LCD_SetWindow(x0, y, x1, y); // 设置LCD显示窗口为这一行 for (int x = x0; x <= x1; x++) { LCD_WriteData(CurrentColor); // 连续写入颜色数据 } }

实际上，LCD_WriteData往往可以配置为连续写入模式，控制器会自动递增地址，CPU可能只需要发送一次起始地址和颜色数据，然后持续推送数据即可，甚至可以用DMA来完成，效率极高。因此，一个重要的优化原则是：当明确知道要绘制水平或垂直线时，务必使用专用的GUI_DrawHLine和GUI_DrawVLine函数。

GUI_DrawLineRel(int dx, int dy)和GUI_DrawLineTo(int x, int y)则是基于“当前笔触位置”的概念。emWin内部维护了一个当前点坐标（CP）。GUI_MoveTo(x, y)用于移动CP而不画线，GUI_MoveRel(dx, dy)相对移动CP。GUI_DrawLineTo从CP画线到指定绝对坐标，并更新CP到终点。GUI_DrawLineRel从CP画线到相对偏移点，并更新CP。这在连续绘制路径时非常方便，比如绘制一个由多条线段组成的图形轮廓，可以避免重复计算每个线段的起点。

注意：“当前笔触位置”（CP）是一个全局状态。如果你在多个任务或中断服务程序中交叉调用绘图函数，必须注意CP可能被意外修改，导致绘图错乱。在复杂的、非线性的绘图逻辑中，更推荐使用绝对坐标的GUI_DrawLine，或者在使用相对/连续绘图前，显式地用GUI_MoveTo设定起始点。

2.2 线型设置与多边形绘制

除了实线，emWin还支持虚线、点线等线型，通过GUI_SetLineStyle(U8 LineStyle)设置。可选的线型有GUI_LS_SOLID（实线，默认）、GUI_LS_DASH（虚线）、GUI_LS_DOT（点线）、GUI_LS_DASHDOT（点划线）、GUI_LS_DASHDOTDOT（双点划线）。这里有一个关键限制：线型仅在画笔大小（Pen Size）为1时生效。如果你通过GUI_SetPenSize()设置了更粗的画笔，画出的永远是实线。这是因为虚线、点线的模式是基于单个像素路径定义的，笔刷变宽后，如何定义这种模式的填充变得复杂，库没有实现。

绘制折线使用GUI_DrawPolyLine(const GUI_POINT *pPoint, int NumPoints, int x, int y)。它接受一个GUI_POINT结构体数组（包含x, y坐标），依次连接所有点。参数x, y是整体偏移量，可以将整个折线平移到指定位置。这个函数内部就是循环调用GUI_DrawLineTo，所以同样受当前线型影响。

多边形是闭合的折线。GUI_DrawPolygon用于绘制多边形轮廓，它会自动将最后一个点与第一个点连接起来。GUI_FillPolygon则用于填充多边形。填充算法是扫描线填充法，效率较高。这里有一个重要的宏GUI_FP_MAXCOUNT，它定义了扫描线算法中用于计算交点的最大点数，默认是12。如果你的多边形非常复杂（例如星形有很多个凹角），在某个Y坐标水平扫描时，可能与多边形边界产生很多个交点，如果超过GUI_FP_MAXCOUNT的一半（因为需要配对），填充就会出错。此时你需要在包含GUI.h之前定义这个宏来扩大限制，例如#define GUI_FP_MAXCOUNT 50。

2.3 圆形、椭圆与弧线

GUI_DrawCircle和GUI_FillCircle用于画圆，参数是圆心坐标和半径。GUI_DrawEllipse和GUI_FillEllipse用于画椭圆，参数是圆心坐标和X轴半径、Y轴半径。它们的实现同样基于优化的绘制算法。

GUI_DrawArc用于绘制圆弧，参数包括圆心、X半径、Y半径、起始角和终止角（角度制）。文档中明确提到了两个限制：1.ry参数当前未被使用，仅rx有效，即目前只支持正圆圆弧，不支持椭圆弧。2. 半径参数不能超过180，因为内部使用了整数运算，过大会导致溢出。这在设计仪表盘、进度指示器时需要特别注意，如果你的显示区域很大，需要绘制大半径圆弧，可能需要自己用多个短线段来模拟。

绘制图形（GUI_DrawGraph）和饼图（GUI_DrawPie）是更高层次的封装。GUI_DrawGraph直接传入一个Y值数组和起点，它会自动连接成折线图，常用于快速显示波形或数据趋势。GUI_DrawPie用于绘制扇形，可以很方便地制作饼状图。

3. 高级几何变换与上下文管理

在动态图形或复杂界面中，我们经常需要对图形进行平移、旋转、缩放，或者需要管理不同的绘图状态。emWin也提供了相应的支持。

3.1 多边形的几何变换

emWin提供了三个强大的多边形变换函数：GUI_EnlargePolygon,GUI_MagnifyPolygon,GUI_RotatePolygon。它们并不直接绘图，而是对描述多边形的点集（GUI_POINT数组）进行变换，生成一个新的点集，然后你可以用新的点集去绘制或填充。

GUI_EnlargePolygon是“增肥”或“收缩”。它沿着多边形每个边的法线方向，将所有顶点向外或向内平移指定距离（Len参数为正则向外，为负则向内）。这对于需要绘制轮廓线（比如先画一个粗的多边形，再在内部画一个细的）非常有用。但要注意，对于凹多边形，过度的向内收缩可能导致图形自相交，产生奇怪的结果。

GUI_MagnifyPolygon是缩放。它以原点(0,0)为中心，将每个顶点的坐标乘以放大系数Mag。如果你想以多边形自身中心点进行缩放，需要先平移点集使中心到原点，缩放后再平移回去。这与GUI_EnlargePolygon有本质区别：放大是乘法的，各边等比例缩放；增大是加法的，各边平移固定像素。

GUI_RotatePolygon是旋转。它同样以原点(0,0)为中心，将点集旋转指定的Angle弧度。同样，绕任意点旋转需要额外的平移操作。

实操心得：这些变换函数要求目标点数组（pDest）不小于源点数组（pSrc）。一个安全的做法是定义两个同样大小的数组。变换操作是计算密集型的，涉及浮点运算（旋转）。在实时性要求高的场景（如动画），应避免在每一帧都进行变换计算。更好的做法是预先计算好变换后的点集，或者只计算一次并缓存起来。

3.2 GUI上下文与裁剪区域

GUI上下文（GUI Context）是一个结构体，它保存了当前所有的绘图状态，包括但不限于：当前前景色、背景色、字体、文本对齐方式、画笔大小、线型、当前笔触位置（CP）等。通过GUI_SaveContext和GUI_RestoreContext，你可以保存和恢复这些状态。

这在什么情况下有用呢？想象一个复杂的绘图函数，它内部可能会修改颜色、字体等状态。如果调用者不希望自己的绘图状态被破坏，就可以在调用前保存上下文，调用后恢复。

GUI_CONTEXT Context; GUI_SaveContext(&Context); // 保存当前状态 DrawMyComplexWidget(); // 这个函数内部可能修改了颜色、字体等 GUI_RestoreContext(&Context); // 恢复调用前的状态 // 现在继续绘图，颜色、字体还是原来的设置

另一个重要概念是裁剪区域（Clipping Rectangle）。默认情况下，裁剪区域是整个显示区域。通过GUI_SetClipRect，你可以设置一个矩形区域，此后所有的绘图操作都只会在这个区域内生效，超出部分不会被绘制。这常用于实现局部刷新、窗口裁剪或者绘制滚动视图的可见部分。传入NULL可以恢复为默认全屏裁剪区。

GUI_RECT Rect = {10, 10, 50, 50}; // 左上角(10,10)，右下角(50,50) GUI_SetClipRect(&Rect); GUI_DrawLine(0, 0, 100, 100); // 实际上只有穿过Rect区域的那部分线段会被画出 GUI_SetClipRect(NULL); // 恢复全屏绘制

注意事项：裁剪区域是全局状态，同样需要注意多任务访问冲突。并且，设置一个非常小的裁剪区域虽然能提高效率（因为很多图元计算会提前被剔除），但设置和恢复裁剪区本身也有开销。对于简单的、单一的绘图操作，不一定能带来性能提升，通常用于复杂的UI层叠管理。

4. 位图（BMP）文件显示：内存与存储的权衡

在嵌入式设备上显示图片，BMP格式因其结构简单、无需解码而常被使用。emWin支持从内存直接绘制BMP文件。

4.1 BMP API 解析与内存管理

最直接的函数是GUI_BMP_Draw(const void *pFileData, int x0, int y0)。你需要将整个BMP文件（包括文件头和信息头）加载到内存中的一个连续缓冲区，然后将指针传递给这个函数。它支持多种BMP格式：1位、4位、8位索引色，以及16位、24位、32位真彩色，并且支持RLE压缩的4位和8位位图。

但是，将整个图片文件加载到内存可能是个问题，尤其是图片较大而RAM有限时。为此，emWin提供了GUI_BMP_DrawEx函数。它不要求文件全部在内存中，而是通过一个回调函数pfGetData来按需读取数据。库在解码过程中，会分批请求数据（最多一次请求一行像素所需的数据量）。这个回调函数的原型是int GetData(void *p, void *pBuffer, int NumBytesReq)，你需要在这个函数里从存储介质（如SD卡、SPI Flash）中读取NumBytesReq字节到pBuffer，并返回实际读取的字节数。

int myGetData(void *p, void *pBuffer, int NumBytesReq) { // p 是 GUI_BMP_DrawEx 传入的上下文，比如一个文件句柄 FILE *fp = (FILE *)p; return fread(pBuffer, 1, NumBytesReq, fp); } // 使用 FILE *fp = fopen("image.bmp", "rb"); GUI_BMP_DrawEx(myGetData, fp, x, y); fclose(fp);

这是emWin处理大图像或存储介质上图像的经典模式，在JPEG/PNG的Ex函数中同样适用，务必掌握。

GUI_BMP_DrawScaled和GUI_BMP_DrawScaledEx提供了缩放显示功能。缩放通过分子（Num）和分母（Denom）参数控制。例如，要缩小到原图的75%，则Num=3,Denom=4（因为3/4=0.75）。注意，缩放是软件实现的，会消耗额外的CPU时间进行插值计算。

4.2 获取图像尺寸与屏幕截图

在动态布局时，我们常常需要先知道图片的尺寸再决定如何摆放。GUI_BMP_GetXSize/GetYSize（及其Ex版本）就是用于此目的。它们会解析BMP文件头，返回图像的宽度和高度，而无需解码整个像素数据，速度很快。

一个非常实用的功能是GUI_BMP_Serialize系列函数，它可以将当前显示内容或指定矩形区域的内容“序列化”成一个BMP文件数据流。你不需要提供一个缓冲区来存放整个BMP文件数据，而是提供一个回调函数pfSerialize。库在生成BMP文件数据（包括文件头和像素数据）时，会每生成一个字节就调用一次这个回调函数。你可以在回调函数中将这个字节写入文件、通过串口发送、或者存储到任何地方。

void mySerialize(U8 Data, void *p) { // 例如，将Data写入UART发送寄存器 UART_SendByte(Data); } // 将屏幕(0,0, 100,100)区域保存为BMP GUI_BMP_SerializeEx(mySerialize, 0, 0, 100, 100, NULL);

这个功能对于远程调试、生成日志图片或实现屏幕录像功能极其有用。

5. JPEG图像显示：解码与性能优化

JPEG因其高压缩比，非常适合存储照片类图片，能极大节省Flash空间。但JPEG解码是计算密集型操作，在嵌入式设备上需要妥善处理。

5.1 JPEG支持概览与编译时集成

emWin的JPEG解码库支持基线（Baseline）、扩展顺序（Extended Sequential）和渐进式（Progressive）JPEG。需要注意的是，由于专利限制，它不支持算术编码的JPEG文件，但绝大多数相机和软件生成的JPEG都使用哈夫曼编码，所以这个问题在实践中很少遇到。

使用JPEG最直接的方式是使用GUI_JPEG_Draw函数，它和GUI_BMP_Draw类似，接受内存中的JPEG文件数据指针。但更常见的用法是GUI_JPEG_DrawEx，同样使用GetData回调来避免一次性加载整个文件。

对于频繁显示、不会改变的图片（如Logo、图标），最好的做法是在编译时就将JPEG图片集成到程序中。emWin提供的工具Bin2C.exe可以将任意二进制文件（包括JPEG）转换成一个C数组。这样做的好处是：图片数据被直接链接到代码段（通常位于Flash），节省了RAM；访问速度更快（直接从Flash读取）；并且去掉了文件系统依赖。

步骤很简单：

使用Bin2C.exe工具转换image.jpg得到image.c。
在工程中包含image.c文件。
在代码中声明外部引用该数组：extern const unsigned char acImage[];。
使用GUI_JPEG_Draw(acImage, sizeof(acImage), x, y);显示。

5.2 解码性能优化实战

JPEG解码是GUI操作中可能最耗CPU的部分。如果在一个需要频繁重绘的窗口回调函数中直接调用GUI_JPEG_Draw，会导致界面严重卡顿。

解决方案是使用内存设备（Memory Device）。内存设备是一块离屏缓冲区（Off-screen Buffer），你可以先将JPEG图片绘制到内存设备中，这个操作只执行一次耗时的解码。之后，每次需要显示这张图片时，只需将内存设备的内容快速复制（Blit）到屏幕上即可，这个复制操作的速度远快于重新解码。

GUI_HMEM hMem; // 创建内存设备，大小与JPEG图片相同（需要先获取尺寸，这里假设为100x100） hMem = GUI_MEMDEV_Create(0, 0, 100, 100); // 选择内存设备作为绘图目标 GUI_MEMDEV_Select(hMem); // 在内存设备中绘制JPEG（解码发生在这里） GUI_JPEG_Draw(acImage, sizeof(acImage), 0, 0); // 切换回正常绘图目标（通常是LCD） GUI_MEMDEV_Select(0); // ... 在需要显示图片的地方 ... GUI_MEMDEV_WriteAt(hMem, x, y); // 快速将内存设备内容写到屏幕指定位置

另一个优化点是图片尺寸。如果屏幕显示区域只有240x320，那么存储一张1920x1080的JPEG就是巨大的浪费。不仅占用更多Flash，解码时间也成倍增加。务必在将图片放入资源前，用图像处理软件将其缩放或裁剪到实际显示所需的最大尺寸。

最后，对于需要动态加载的JPEG图片（如从SD卡读取），如果图片显示频率高，也可以考虑在程序启动时或空闲时，将其解码到内存设备中缓存起来，用空间换时间。

6. 常见问题排查与调试技巧

在实际使用emWin的2D绘图和图像API时，你肯定会遇到各种问题。这里记录一些我踩过的坑和解决方法。

6.1 绘图无显示或显示错乱

检查LCD底层驱动：这是最根本的。确保你的LCD_X_Config和LCD_X_DisplayDriver函数正确配置，并且LCD_DrawBitmap或像素点写入函数能正常工作。可以用一个最简单的画点函数测试底层。
确认坐标和裁剪区域：绘图的坐标是否在屏幕物理坐标（或当前窗口/裁剪区域内）？有时你以为画在(10,10)，但当前窗口的左上角可能不是(0,0)。使用GUI_SetClipRect(NULL)重置裁剪区再试。
颜色格式不匹配：emWin内部使用GUI_COLOR（通常是32位ARGB），但最终需要转换成你的LCD控制器接受的颜色格式（如RGB565）。检查LCD_COLORINDEX相关的宏和转换函数是否正确。一个快速测试方法是调用GUI_SetColor(GUI_RED); GUI_FillRect(0,0,10,10);看是否能出现一个红色方块。
内存设备未正确切换：如果你使用了内存设备，绘制完成后是否通过GUI_MEMDEV_Select(0)切换回了默认设备？后续的绘图操作如果忘记切换，可能会画到“黑洞”里。

6.2 图像显示问题（BMP/JPEG）

BMP文件头问题：GUI_BMP_Draw要求传入的是完整的、未解析的BMP文件数据。确保你的文件指针指向文件开头，并且文件是标准的、emWin支持的BMP格式。可以用电脑上的画图工具另存为一个标准的24位位图来排除格式问题。
JPEG解码失败：首先确认JPEG文件是标准的、非算术编码的格式。如果使用GUI_JPEG_DrawEx，确保你的GetData回调函数能正确返回请求的数据量。一个常见错误是文件读取到达末尾（EOF）时，回调函数没有正确处理，导致解码库获取不到数据而失败。确保回调函数在读取失败时返回实际已读取的字节数（例如0），而不是一个错误码。
图像显示为花屏或错位：这通常是颜色深度（Bits Per Pixel）不匹配导致的。例如，你的LCD是RGB565（16位色），但JPEG解码出来是RGB888（24位色），emWin会进行转换。但如果底层驱动配置的颜色格式是8位色（调色板模式），而图像是真彩色，就会出问题。检查LCD_BITSPERPIXEL和LCD_FIXEDPALETTE的配置。

6.3 性能优化问题

绘制速度慢：
- 避免在循环中频繁设置颜色、字体、画笔等状态。将这些设置移到循环外面。
- 优先使用GUI_DrawHLine/VLine代替GUI_DrawLine画水平和垂直线。
- 对于复杂的、静态的背景，考虑使用内存设备一次性绘制好，然后快速复制。
- 启用emWin的多缓冲（Multiple Buffering）机制（如果硬件支持），可以消除闪烁并可能提升绘制效率。
内存占用过大：
- 仔细评估GUI_NUM_LAYERS（图层数）和GUI_NUM_BUFFERS（缓冲数），非必要时不要增加。
- 动态内存设备用完后，及时用GUI_MEMDEV_Delete释放。
- 使用GUI_ALLOC_GetNumFreeBytes()等函数监控堆内存使用情况，防止内存泄漏。

6.4 调试与诊断技巧

使用GUI_Delay定位卡顿点：在怀疑耗时的操作前后调用GUI_Delay(100)，观察界面反应，可以粗略定位性能瓶颈。
简化问题：当遇到复杂显示问题时，创建一个最简单的、只包含问题代码的新工程进行测试，排除其他模块干扰。

利用GUI_GetTime()进行性能测量：在操作前后获取时间戳，计算差值，可以量化性能。

int t0 = GUI_GetTime(); GUI_JPEG_Draw(pData, FileSize, x, y); // 你的绘图操作 int t1 = GUI_GetTime(); printf("JPEG draw took %d ms\n", t1 - t0);

关注官方例程和手册：SEGGER提供的示例代码（通常位于Sample或Example目录）是极好的参考。用户手册（UM）中关于特定函数的“Additional information”和“Limitations”部分，往往包含了最关键的限制条件和实现细节，比如之前提到的GUI_DrawArc的半径限制。