TIStellarisWare图形库使用指南

TI StellarisWare图形库使用指南V1.0作者:Richard MaEmail: mxschina 1. 前言1.2. 基础知识2.2.1. 显示驱动层 (Display Driver Layer) 2.2.1.1. 基本功能2.2.1.2. 图形输出驱动3.2.1.3. 用户输入驱动3.2.2. 基本图形层 (Graphics Primitives Layer) 4.2.3. 控件层 (Widget Layer) 4.3. StellarisWare 图形库基本使用 .6.3.1. 开发环境及 StellarisWare 安装 6.3.2. 图形库添加与编译(显示部分)7.3.2.1. 建立新项目 7.3.2.2. 添加图形库 8.3.2.3. 驱动程序初始化 1.0.3.3. 图形库添加与编译(触摸部分)1.0.4. 基本图形绘制1.2.4.1. 绘图上下文(tContext) 12.4.2. 颜色设置1.2.4.3. 绘制基本图形1.3.4.4. 绘制文字 1.4.4.5. 绘制图片1.6.图片表示方式 .16.-1 -TI StellarisWare 图形库使用指南Richard Ma4.52 图片生成工具 17.5. 控件使用.19.5.1. 控件使用示例代码 1.9.5.2. 控件使用步骤说明23.5.2.1. 配置显示及用户输入 24.5.2.2. 创建控件及属性配置24.1) 控件名2.5.2) 控件管理 -控件树25.3) 显示设备对象(pDisplay) 27.4) 位置和尺寸 27.5) 控件风格(Style)及其它属性27.6) 事件响应27.5.2.3. 控件添加绘制及管理 28.6. 各控件功能及属性29.6.1. 画布控件(Canvas) 29.6.2. 选择/多选框控件(Checkbox)336.3. 容器控件(Co nta in er) .3.6.6.4. 图形按钮控件(Image Butt on) 39.6.5. 列表框控件(ListBox) .43.6.6. 按钮控件(Push Button) 46.6.7. 单选按钮控件(Radio Button) 51.拖滑/进度条控件(Slider).5.4TI StellarisWare 图形库使用指南Richard Ma丄、八 、1.刖言TI Stellaris 系列 Cortex-M3/Cortex-M4F 系列 MCU 的方便强大，StellarisWare 软件库提供 的快速软件开发解决方案功不可没。作为TI StellarisWare软件包的一部分，StellarisWare图形库(Grlib)提供了一套比较完整的MCU图形显示方案，既可以进行基础的图形、文字绘制，也 可以轻松实现PC机上常见的，基于消息的控件(Widget)。伴随着Stellaris LM4F系列的推出, StellarisWare图形库也会进一步升级，支持汉字字库。由于Stellaris图形库没有相关的中文文档，有时候会让大家觉得入门非常困难，所以写这篇文 档，抛砖引玉，让对Stellaris感兴趣的朋友都能够通过阅读这篇文档，快速上手StellarisWare图形库，为MCU世界增加更多美丽的应用。本文所介绍的StellarisWare可以在TI的StellarisM3/M4F系列上运行。下面图就是用Stellaris图形库进行控件绘制的示例，Stellaris最高可支持24bit颜色，精心设 计过的界面可以非常有吸引力。本文以 TI的LM3S9B96开发板为基础，示例程序均在开发板上 演示、运行。2. 基础知识虽然Stellaris图形库应用起来比较简单，但理论知识还是需要的。下面谈谈Stellaris图形库的基本结构。Stellaris图形库分成了三层，分别是：显示驱动层(Display Driver Layer)(2) 基本图形层(Graphics Primitives Layer)(3) 控件层(Widget Layer)硬件无关硬件无关控件层(Widget)基本图形层(Graphics Primitives)显示驱动层(Display Driver)底层+硬件相关下面分别介绍下各层的大概作用。2.1. 显示驱动层(Display Driver Layer)2.1.1. 基本功能 显示驱动层提供了和硬件通信的基本功能，这层直接和硬件直接通信。提供了两类驱动，分别是 图形输出驱动、用户输入驱动。图形库应用中，用户输入不是必须的。辛苦的分层带来了巨大好处，当需要把程序从一个硬件平台移植到另一个新的时候，如果显示内 容不变，开发者们只需要重新实现驱动层，而上层的代码可以保持不变。2.12图形输出驱动图形输出驱动和显示屏控制器打交道，实现诸如在屏幕上画点之类的基本作用（毕竟再复杂的图 像也是一个点一个点画出来的），参考 TI LM3S9B96开发板的驱动，有如下的显示驱动程序：kitro nix320x240x16_ssd2119_8bit.c它们就是开发板上320x240彩色LCD显示屏的驱动。打开驱动程序，能找到如下对象： tDisplay g_sKitro nix320x240x16_SSD2119;对象中定义了显示相关的参数（如尺寸，屏幕的横竖等），并实现了下面的函数：Kitronix320x240x16_SSD2119PixelDraw （绘制点）Kitronix320x240x16_SSD2119PixelDrawMultiple （绘制多个点）Kitronix320x240x16_SSD2119LineDrawH （绘制水平线）Kitronix320x240x16_SSD2119LineDrawV （绘制垂直线）Kitronix320x240x16_SSD2119RectFill （填充方块）Kitro nix320x240x16_SSD2119ColorTra nslate （ 颜色变换）Kitronix320x240x16_SSD2119Flush （使绘图结果生效）没错，它们实现了基本的绘图功能，在图形库更上层基本图形层中，这些函数将被调用，直接控 制LCD，在屏幕上显示点（Pixel）、线（Line）以及面（Rect）等。所以在移植的时候，这些函数需要 充分调试，以保证它们能正确画出所需图形。2.1.3.用户输入驱动响应用户输入事件用的硬件驱动（如触摸屏幕驱动），也算作显示的驱动的一部分，归在显示驱 动层。在LM3S9B96开发板上，提供了触摸屏的驱动：touch.c里面的函数与Stellaris图形库直接相关，用户需要用到的主要是:TouchScree nCallbackSet在触摸功能初始化的时候，这个函数通过回调，将用户动作事件和Stellaris图形库的事件响应函数连接在一起。当用户动作时，输入驱动可以调用Stellaris图形库的 WidgetPointerMessage函数，传入动作的信息(如动作的x、y坐标，动作方式等)。图形库会处理这些信息，进行画面更新，响应用 户的动作。2.2. 基本图形层(Graphics Primitives Layer)只能画点线面显然是不够的。Stellaris图形库的基本图形层实现了形状、文字以及图片的绘制功 能。如果只需要基本的图形显示功能，可以仅使用该层而不用控件层。2.3. 控件层(Widget Layer)对pc上的按钮、点选框等控件，想必各位应该相当熟悉了。控件层的作用就是实现这些类似的 功能。Stellaris图形库可以实现的控件有：画布(Ca nvas)控件容器(Container)按钮(Push Butt on)图形按钮(Image Butt on)选择/多选框(Checkbox)单选框(Radio Butt on)列表框(ListBox) 拖滑/进度条(Slider)StellarisWare图形库中，实现了这些控件的自动绘制、事件响应，使用户不需花费时间在重复 繁琐的用户输入处理工作上，为应用带来方便。后文会具体介绍如何使用这些控件。-4 -TI StellarisWare 图形库使用指南Richard Ma-5 -TI StellarisWare 图形库使用指南Richard Ma画布(Ca nvas)选择/多选框(Checkbox)控件容器(Co ntai ner)单选框(Radio Butt on)按钮(Push Butt on)拖滑/进度条(Slider)-# -TI StellarisWare 图形库使用指南Richard Ma-6 -TI StellarisWare 图形库使用指南Richard Ma3. StellarisWare 图形库基本使用3.1. 开发环境及StellarisWare 安装本文以 IAR Embedded Workbench v6.2 (ARM)为开发环境，以 TI Stellaris LMS9B96 开发板为基础，介绍StellarisWare图形库的用法。要使用StellarisWare图形库，StellarisWare 软件包当然必不可少。在 TI官网免费可以下载到 这个软件包。Boanc口ProjectStellarisWareSte- 二）tel-3r!SV.L3r-& Id- , J Bluetop =t 1+ Q bMrdsQ bwtjoaderli do佔& I口 tirTgrlitJ + _） exarDlesQ O口氏孑 O ICnifltl+ SinnphQTI-L.l. 1 l u_JE- O tools 1+ li 3 usolibli_J Jtls3 O rWindQf. 5_dr.er5 l）亡）StelansVjareqF安装StellarisWare 后，进入安装路径，在grlib目录下可以找到StellarisWare图形库相关内 容。Grlib根目录下包含了图形库的源代码，如ccs、ewarm这些目录则包含了针对不同IDE的库文件。32图形库添加与编译（显示部分）为了比较详细地说明用法，我们完全手动建立项目，实际项目时可以从StellarisWare/boards/dk-lm3s9b96/hello示例开始以节约时间。首先介绍的是显示部分的设置，触摸功能将放在下一章。3.2.1. 建立新项目在 IAR 中新建项目 Stellaris_Demo，设置项目 Device 为 TexasInstruments LM3SxBxx 。在项 目中加入Stellaris_Demo.c，写一个空的ma in函数。同时也别忘记加入启动代码startup_ewarm.c（该文件可以在 StellarisWare/boards/dk-lm3s9b96/hello中的应用中找至V，_ewarm表示该启动代码为针对IAR的）。-7 -TI StellarisWare 图形库使用指南Richard Ma-# -TI StellarisWare 图形库使用指南Richard Ma新项目中只有默认的中断函数处理程序（定义在 startup_ewarm.c中），尝试编译通过，进入下一Filesl=J JStollaris Demo - DebugT3 0 startup_Bwarm.c3 |F Stelle.ris_Derno.c4Output322.添加图形库首先在项目中添加StellarisWare 驱动库和图形库。分别在StellarisWare/driverlib 和 StellarisWare/grlib 下面，找为IAR （ewarm）已编译好的库。因为是在 M3平台上的，所以用- cm3版本。-cm4f是为LM4F系列准备的，如果是在LM4F平台使用，只需要连接 LM4F的库, 而代码不需要改动。FilesStelluris_Demo - Debug driverlib-cm3.&Q grlib-亡rri3si 0 siartup.ev/errn.Q El B Stelleris_Demo.c -S 口 Output打开程序设置，在 C/C+ Compiler 中 Preprocessor 选项卡下 Additional include directories 添加 C:StellarisWare （StellarisWare的安装路径）。如果使用了 LM3S9B96 开发板，需要再添加 C:StellarisWareboardsdk-lm3s9b96，为后面使用其驱动程序做准备。由于使用IAR作为开发环境，需要在 Defined symbols 中加入ewarm （小写）定义。图中 TARGET_IS_TEMPEST_RB1是驱动库可能用到的，用以区别器件版本，根据不同的器件版本应 填入不同的参数。-8 -TI StellarisWare 图形库使用指南Richard Ma-9 -TI StellarisWare 图形库使用指南Richard MaCategory:Geral OotionsC/C-I-+ Compiler Mdthfile CompilationDiscard Lhused PublicsAsEwrrnlbOLitput ConvexteCustom BuildBuild ActionsLikfirDen*百訶Sir j atff-ArgdGDB Ser ;erIAR FtOM-monitDrJ-Link/J-TrceH Stellaris FTDr MacraigoiPE neroRD1TpucData这样的形式在C中的效率比较低。在实际使用中，图片文件均被定义为unsigned char的数组而非结构体。TI提供了专门的工具从图片生成所需的数组。4.52图片生成工具在用StellarisWare图形库开发过程中，图片是用 C语言中unsigned char 数组表示的。TI StellarisWare图形库提供了一个将图片文件转换成C代码的软件。在StellarisWare/tools文件夹下，有一个叫pnmtoc.exe 的程序（pnmtoc文件夹下是源代码）。使用pnmtoc可以将 pnm格式的图片转换为C代码。pnm不是常见的图片格式，但很多常见的绘图软件都可以直 接生成pnm格式，如Photoshop。同时，也有很多免费转换工具可以将bmp、jpeg等常见格式转换为pnm 文件，如NetPBM、GIMP等。当得到pnm格式图片后可以使用pnmtoc来转换，命令如下：pnm toc -c image.p nm image.c这里会将image.pnm 文件转换输出为image.c。-c命令表示启用图片压缩。如果压缩后体积 大于不压缩时，压缩会自动关闭。通常生成如下形式的图片数组，g_puclmageLogo 可直接作为GrImageDraw 中pucImage 的 参数。-17 -TI StellarisWare 图形库使用指南Richard Maconst un sig ned char g_puclmageLogo= _IMAGE_FMT_8BPP_COMP,33, 0,16, 0,101,0x00, 0x00, 0x00,0x10, 0x10, 0x10,0x2a, 0x2a, 0x2a,0xc7, 0x07, 0x07, 0x00, 0x0f, 0x11, 0x07, 0x07, 0x07, 0x87, 0x01,0x1b, 0x4d, 0x52, 0x1f, 0x07, 0x07, 0x04, 0x00, 0x0c, 0x37, 0x54, 0x55, 0x53, 0x00, 0x2d, 0x2f, 0x33, 0x33, 0x33, 0x33, 0x34, 0x34, 0x10, 0x34, 0x33,;-18 -TI StellarisWare 图形库使用指南Richard Ma5. 控件使用最常见的控件就是 Windows系统中的按钮，当用户点击时，按钮的外观形状将发生变化，同时 会有相应的动作执行。StellarisWare图形库中控件的作用是类似的，就是将图形的绘制及用户 的操作封装在一起，这样在程序设计时，开发人员可以不再费心处理每一个控件细节（如点击某个区域引起控件事件等），而只用设置如按钮的名字、大小以及事件响应动作等属性。要使用控件，需要以下几个步骤：1）配置显示及用户输入（如触摸）2）创建控件对象，设置控件对象的属性（结构、位置及外观等）3）加入控件列表将控件绘制出来5.1. 控件使用示例代码首先用一个Hello World 的例子进行一个示例，该例子在 LM3S9B96上调试通过，会在LCD 上显示一个“ Show Welcome ”的按钮，点击后会屏幕上会出现“ Hello World ”，同时按钮 变为“ Hide Welcome ”；再次点击则Hello World 会消失，按钮文字复原。这个例子主要为 提供直观的印象，后文中会对图形库的使用做更详细的介绍。#in clude in c/hw_types.h#in clude driverlib/in terrupt.h#in clude driverlib/sysctl.h#include driverlib/rom.h#include grlib/grlib.h#include grlib/widget.h#in clude grlib/ca nvas.h#in clude grlib/pushbutt on .h#include drivers/kitronix320x240x16_ssd2119_8bit.h#in clude drivers/touch.h#in clude drivers/set_p ino ut.h*/声明驱动库中定义的tDisplay显示设备对象。*extern const tDisplay g_sKitro nix320x240x16_SSD2119;*/提前声明要使用到的控件。(后文为建立控件树可能会相互引用)*exter n tCa nvasWidget g_sBackgro und;exter n tCa nvasWidget g_sHeadi ngexter n tCa nvasWidget g_sHello;extern tPushButto nWidget g_sPushBt n;/*/提前声明按钮按下时的处理函数。/*void On Butto nPress(tWidget *pWidget);*/创建并定义各控件。/包括3个画布控件(背景、标题、Hello World 显示)，一个按钮控件*/作为屏幕标题的画布控件Can vas(g_sHeadi ng, &g_sBackgro und, 0, &g_sPushBt n,&g_sKitro nix320x240x16_SSD2119, 0, 0, 320, 23,(CANVAS_STYLE_FILL | CANVAS_STYLE_OUTLINE | CANVAS_STYLE_TEXT),ClrDarkBlue, ClrWhite, ClrWhite, &g_sF on tCm20,hello-widget, 0, 0);/作为屏幕背景的画布控件Can vas(g_sBackgrou nd, WIDGET_ROOT, 0, &g_sHeadi ng,&g_sKitro nix320x240x16_SSD2119, 0, 23, 320, (240 - 23),CANVAS_STYLE_FILL, ClrBlack, 0, 0, 0, 0, 0, 0);/用于点击，以显示“ Hello World ”的按钮控件Recta ngularButt on( g_sPushBt n, &g_sHeadi ng, 0, 0,&g_sKitro nix320x240x16_SSD2119, 60, 60, 200, 40,(PB_STYLE_OUTLINE | PB_STYLE_TEXT_OPAQUE | PB_STYLE_TEXT | PB_STYLE_FILL | PB_STYLE_RELEASE_NOTIFY), ClrDarkBlue, ClrBlue, ClrWhite, ClrWhite,&g_sFo ntCmss22b, Show Welcome, 0, 0, 0, 0,On Butt on Press);/用于显示“ Hello World 的画布控件/请注意这个控件并没有被加入控件树，因此是不可见的。只有在用户点击按钮后,/该控件被加入控件树，才会被显示。Can vas(g_sHello, &g_sPushBt n, 0, 0,&g_sKitro nix320x240x16_SSD2119, 0, 150, 320, 40,(CANVAS_STYLE_FILL | CANVAS_STYLE_TEXT),ClrBlack, 0, ClrWhite, &g_sFo ntCm40, Hello World!, 0, 0);*/全局变量，用于记录 Hello World是否可见*tBoolea n g_bHelloVisible = false;*/当按钮按下时的事件处理函数。/如果Hello World 为不可见，则将g_sHello控件加入控件树以显示;/如果Hello World 为可见，则将g_sHello控件移除控件树以隐藏。*void On Butto nPress(tWidget *pWidget)/翻转Hello World 的可见状态g_bHelloVisible = !g_bHelloVisible;/更新Hello World 的显示if(g_bHelloVisible)II如果Hello World的新状态为可见，/则将其加入控件列表(作为按钮控件的子控件)。WidgetAdd(tWidget *)&g_sPushBtn, (tWidget *)&g_sHello);II更新按钮文字。PushButtonTextSet(&g_sPushBtn, Hide Welcome);II重画按钮控件及其下子控件。WidgetPai nt(tWidget *)&g_sPushBt n);elseII如果Hello World的新状态为不可见，则将其移除出控件列表WidgetRemove(tWidget *)&g_sHello);II更新按钮文字PushButt on TextSet(&g_sPushBt n, Show Welcome);II重画整个控件树以清除屏幕上的多余文字WidgetPai nt(WIDGET_ROOT);II*II主函数II*int main( void)II设置系统工作在 50MHz。ROM_SysCtlClockSet(SYSCTL_SYSDIV_4 | SYSCTL_USE_PLL |SYSCTL_OSC_MAIN | SYSCTL_XTAL_16MHZ);/为9B96开发板分配管脚。(主要为使能各GPIO )Pin outSet();/全局允许中断。ROMn tMasterE nable();/初始化显示驱动程序。Kitro nix320x240x16_SSD2119l nit();/初始化触摸驱动程序。TouchScree nln it();/设置触摸驱动函数的回调函数为图形库的处理函数TouchScree nCallbackSet(WidgetPoi nterMessage);/将g_sBackground 以下的控件加入控件树。WidgetAdd(WIDGET_ROOT, (tWidget *)& g_sBackgrou nd);/绘制控件树中的所有控件。WidgetPai nt(WIDGET_ROOT);/主循环。while(1)/处理所有控件事件。WidgetMessageQueueProcess();5.2. 控件使用步骤说明现在对控件创建使用的几个主要步骤做以下说明:521.配置显示及用户输入首先需要初始化显示，提供如 4.1节中所提的到的tDisplay对象。/声明驱动库中定义的tDisplay对象extern const tDisplay g_sKitro nix320x240x16_SSD2119;/=/初始化显示驱动程序Kitro ni x320x240x16_SSD2119 In it();同时要为StellarisWare图形库提供用户输入接口，让 StellarisWare图形库来处理用户的输入 操作。/初始化触摸屏TouchScree nln it();/关联触摸屏与StellarisWare图形库的用户输入处理函数TouchScree nCallbackSet(WidgetPoi nterMessage);触摸事件与图形库的响应采用回调的方式，当用户点击时，WidgetPoi nterMessage函数会被调用并传入用户点击屏幕的坐标等参数。WidgetPointerMessage函数为StellarisWare 的库函数，接受三个参数：ulMessage、IX、IY。 Message表示事件的内容，如点击、拖动等；lX 和lY表示操作的坐标。如果已有现成的触摸驱动，这些参数用户不必太关心，驱动程序会处理 好这些参数。5.2.2. 创建控件及属性配置可以发现，5.1节中的例子使用了类似如下的代码创建控件，并配置了属性。乍一看，这些属性 似乎非常的繁琐复杂，而且不同的控件所需要设置的属性也不相同，这些具体的属性可以在第6章中找到具体的定义，读者先有个大概的了解，知道如何使用即可，不必纠结于每个参数的具体 选项。Canv as(g_sHead ing, &g_sBackgro und, 0, &g_sPushBt n,& g_sKitro nix320x240x16_SSD2119, 0, 0, 320, 23,CANVAS_STYLE_FILL | CaNVAS_STYLE_OUTLINE | CANVAS_STYLE 二TEXT,ClrDarkBlue, ClrWhite, ClrWhite, &g_sFontCm20, hello-widget, 0, 0);Recta ngularButt on( g_sPushBt n, &g_sHead ing, 0, 0,& g_sKitro ni x320x240x16_SSD2119, 60, 60, 200, 40, (PB_STYLE_OUTLINE | PB_STYLE_TEXT_OPAQUE | PB_STYLE_TEXT | PB_STYLE_FILL | PB_STYLE_RELEASE_NOTIFY),ClrDarkBlue, ClrBlue, ClrWhite, ClrWhite,& g_sFo ntCmss22b, Show Welcome, 0, 0, 0, 0, On Butto nPress);整体来看，这些控件其实有一些共同点，下文先介绍下这些共同点，相信各位读者在理解了这些 共同点后，能够通过阅读第6章，很快上手每个不同的控件。1) 控件名每个控件都有自己的唯一名字，用于标识自己，以及被引用。上面例子中的g_sHeadi ng和g_sPushBtn都是控件的名字。不同类型的控件，控件名对应的实际类型都不一样，如RectangularButton的类型是 ButtonWidget 、Canvas 的类型是 tCanvasWidget 等。5.1 节中代码开始部分的控件声明处可以作为示例。2) 控件管理-控件树通常来说，一个界面中会有很多控件对象。为了方便管理，StellarisWare图形库将众多控件以树状的形式管理，这样做有很多好处：每个控件(树)都可以动态加入或者移出被渲染的控件列表树，以决定屏幕要显示的内容；同时当需要部分更新屏幕内容时，可以只从某个节点开始渲染， 这样就只绘制其及子节点以节约资源。图形库中有一个虚拟的 widget_root控件，总是作为最顶层的控件，其它控件都作为它的子 节点或者更下层的子节点。不同控件在树状列表中的地位没有区别。为了描述一个树状结构，每个控件都有三个属性，分别是：父控件(Pare nt)下一个控件(Next)子控件(Child)这些属性各自指向了自己周围的节点。下图就是一个典型的控件树:LogoCapti on-27 -TI StellarisWare 图形库使用指南