u8g2 图形处理库
作者:江访
一、概述
u8g2 图形处理库是 LuatOS 的显示屏驱动库,支持多种 OLED 和 LCD 单色屏幕,提供丰富的图形绘制功能;
u8g2 库提供了如下几大类功能:
1、显示屏初始化配置:支持I2C、SPI接口的显示屏初始化;
2、基本图形绘制:点、线、圆、矩形等基本图形的绘制;
3、文本显示:支持中英文字体显示,支持UTF-8编码;
4、位图显示:支持XBM格式位图显示;
5、二维码生成:支持二维码生成和显示;
6、高级绘图功能:按钮、椭圆、三角形等复杂图形绘制;
在 LuatOS 中,u8g2 库和 lcd 库都是用于显示驱动的库,而且有些接口和用法类似,但 2 个库还是有本质的差异。
u8g2 专注于单色显示屏驱动,提供了丰富的图形绘制功能,如按钮,圆弧,阴影等等,做 UI 设计相对更简单。同样运行后资源的开销也会比 LCD 核心库更多。
而 lcd 核心库,提供了基本的点、线、矩形、圆形、文字、图片显示功能,色彩更丰富,资源开销相对 u8g2 库较小,能够支持的显示屏分辨率也更大。
1.1 u8g2 核心库初始化的内置型号和 custom 型号的差异
1.1.1 内置型号
在函数详解部分,u8g2 初始化函数 u8g2.init()
的第一个参数 driver_ic
支持以下具体型号:
"ssd1306", "st7565", "ssd1309", "ssd1322", "sh1106", "sh1107", "sh1108", "st7567" "uc1701" "ssd1306_128x32" ;
这些是核心库已预适配的显示驱动芯片型号。对于内置型号,库底层已完成各芯片在 LuatOS 系统上正常显示所需的参数配置。使用时,仅需指定对应型号、连接的硬件端口、屏幕方向及分辨率即可完成初始化,后续显示操作将自动按照初始化参数执行。
1.1.2 "custom"型号
"custom"表示当前核心库未内置适配的显示芯片型号。由于未适配的芯片品牌和型号众多,无法全部预置,因此 u8g2 核心库提供了自定义初始化功能。
用户需根据具体显示芯片的数据手册,自行配置初始化参数,详情可以查看第四章节函数详解 4.1 u8g2.begin(conf)
的参数 conf
说明。
1.2 u8g2 字体如何使用
1.2.1 坐标说明
默认以点(0,0)位置为左上角,水平方向为 x 坐标,竖直方向为 y 坐标;
u8g2.DrawUTF8(str, x, y)和 u8g2.DrawButtonUTF8(str,x, y, flags, width, padding_h, padding_v)接口显示内容以设置的坐标为左下角,其余接口显示内容是以设置的坐标为左上角。
1.2.2 字体说明
使用字体常量中的字体需要先使用 u8g2.SetFont(font)进行设置;
使用 gtfont 字体需要外置 gtfont 芯片并完成初始化后才能使用,且不需要使用 u8g2.SetFont(font, indentation)进行设置,可直接使用;
1.3 u8g2 核心库都支持哪些图形操作
1.3.1 基本图形演示
显示类型 | 说明 | 效果 | 相关函数 |
文字效果 | 正常文本 | ![]() | u8g2.DrawUTF8(str, x, y) |
字体透明模式 | ![]() | u8g2.SetFontMode(1) | |
禁用字体透明模式 | ![]() | u8g2.SetFontMode(0) | |
文本装饰接口 | ![]() | u8g2.DrawButtonUTF8(str,x, y, flags, width, padding_h, padding_v) | |
反转文本 | ![]() | u8g2.DrawButtonUTF8(str,x, y, u8g2.BTN_INV, width, padding_h, padding_v) | |
文字+边框 | ![]() | u8g2.DrawButtonUTF8(str,x, y, u8g2.BTN_BW1, width, padding_h, padding_v) | |
文字+边框+设置边框边距 | ![]() | u8g2.DrawButtonUTF8(str,x, y, u8g2.BTN_INV + u8g2.BTN_BW1, width, padding_h, padding_v) | |
文字+边框+设置边框边距+第二个边框 | ![]() | u8g2.DrawButtonUTF8(str,x, y, u8g2.BTN_INV + u8g2.BTN_BW1+u8g2.BTN_XFRAME, width, padding_h, padding_v) | |
文字+边框+设置边框边距+阴影 | ![]() | u8g2.DrawButtonUTF8(str,x, y, u8g2.BTN_INV + u8g2.BTN_BW1+u8g2.BTN_SHADOW1, width, padding_h, padding_v) | |
文字反转+边框+设置边框边距+阴影 | ![]() | u8g2.DrawButtonUTF8(str,x, y, u8g2.BTN_INV+u8g2.BTN_BW2+u8g2.BTN_SHADOW1, width, padding_h, padding_v) | |
文字反转+边框+设置边框边距+第二边框+阴影 | ![]() | u8g2.DrawButtonUTF8(str,x, y, u8g2.BTN_INV+u8g2.BTN_BW2+u8g2.BTN_XFRAME+u8g2.BTN_SHADOW1, width, padding_h, padding_v) | |
图形效果 | 点 | ![]() | u8g2.DrawPixel(x, y) |
线 | ![]() | u8g2.DrawLine(x0,y0,x1,y1) | |
实心三角形 | ![]() | u8g2.DrawTriangle(x0,y0,x1,y1,x2,y2) | |
空心圆 | ![]() | u8g2.DrawCircle(x0,y0,rad) 或者u8g2.DrawCircle(x0,y0,rad,u8g2.DRAW_ALL) | |
空心圆+上左 | ![]() | u8g2.DrawCircle(x0,y0,rad,u8g2.DRAW_UPPER_LEFT) | |
空心圆+上左+上右 | ![]() | u8g2.DrawCircle(x0,y0,rad, u8g2.DRAW_UPPER_LEFT+u8g2.DRAW_UPPER_RIGHT) | |
空心圆+上左+下右 | ![]() | u8g2.DrawCircle(x0,y0,rad, u8g2.DRAW_UPPER_LEFT+u8g2.DRAW_LOWER_RIGHT) | |
空心圆+上左+下右 | ![]() | u8g2.DrawCircle(x0,y0,rad, u8g2.DRAW_UPPER_LEFT+u8g2.DRAW_UPPER_RIGHT+u8g2.DRAW_LOWER_RIGHT) | |
实心园 | ![]() | u8g2.DrawDisc(x0,y0,rad) 或者u8g2.DrawDisc(x0,y0,rad,u8g2.DRAW_ALL) | |
实心圆+上左 | ![]() | u8g2.DrawDisc(x0,y0,u8g2.DRAW_UPPER_LEFT) | |
实心圆+上左+上右 | ![]() | u8g2.DrawDisc(x0,y0, u8g2.DRAW_UPPER_LEFT+u8g2.DRAW_UPPER_RIGHT) | |
实心圆+上左+下右 | ![]() | u8g2.DrawDisc(x0,y0, u8g2.DRAW_UPPER_LEFT+u8g2.DRAW_LOWER_RIGHT) | |
实心圆+上左+上右+下右 | ![]() | u8g2.DrawDisc(x0,y0, u8g2.DRAW_UPPER_LEFT+u8g2.DRAW_UPPER_RIGHT+u8g2.DRAW_LOWER_RIGHT) | |
空心椭圆 | ![]() | u8g2.DrawEllipse(x0,y0,rx,ry) 或者 u8g2.DrawEllipse(x0,y0,rx,ry,u8g2.DRAW_ALL) | |
空心椭圆+上左 | ![]() | u8g2.DrawEllipse(x0,y0,rx,ry, u8g2.DRAW_UPPER_LEFT) | |
空心椭圆+上左+上右 | ![]() | u8g2.DrawEllipse(x0,y0,rx,ry, u8g2.DRAW_UPPER_LEFT+u8g2.DRAW_UPPER_RIGHT) | |
空心椭圆+上左+下右 | ![]() | u8g2.DrawEllipse(x0,y0,rx,ry, u8g2.DRAW_UPPER_LEFT+u8g2.DRAW_LOWER_RIGHT) | |
空心椭圆+上左+上右+下右 | ![]() | u8g2.DrawEllipse(x0,y0,rx,ry, u8g2.DRAW_UPPER_LEFT+u8g2.DRAW_UPPER_RIGHT+u8g2.DRAW_LOWER_RIGHT) | |
实心椭圆 | ![]() | u8g2.DrawFilledEllipse(x0,y0,rx,ry,opt) | |
实心椭圆+上左 | ![]() | u8g2.DrawFilledEllipse(x0,y0,rx,ry, u8g2.DRAW_UPPER_LEFT) | |
实心椭圆+上左+上右 | ![]() | u8g2.DrawFilledEllipse(x0,y0,rx,ry, u8g2.DRAW_UPPER_LEFT+u8g2.DRAW_UPPER_RIGHT) | |
实心椭圆+上左+下右 | ![]() | u8g2.DrawFilledEllipse(x0,y0,rx,ry, u8g2.DRAW_UPPER_LEFT+u8g2.DRAW_LOWER_RIGHT) | |
实心椭圆+上左+上右+下右 | ![]() | u8g2.DrawFilledEllipse(x0,y0,rx,ry, u8g2.DRAW_UPPER_LEFT+u8g2.DRAW_UPPER_RIGHT+u8g2.DRAW_LOWER_RIGHT) | |
矩形框 | ![]() | u8g2.DrawFrame(x,y,w,h) | |
实心矩形 | ![]() | u8g2.DrawBox(x,y,w,h) | |
圆角空心矩形框 | ![]() | u8g2.DrawRFrame(x,y,w,h,r) | |
圆角实心矩形 | ![]() | u8g2.DrawRBox(x, y, w, h, r) | |
设置位图背景色不透明 | ![]() | u8g2.SetBitmapMode(1) | |
设置位图背景色透明 | ![]() | u8g2.SetBitmapMode(0) | |
二维码 | ![]() | u8g2.DrawDrcode(x, y, str, size) |
二、核心示例
1、核心示例是指:使用本库文件提供的核心 API,开发的基础业务逻辑的演示代码;
2、核心示例的作用是:帮助开发者快速理解如何使用本库,所以核心示例的逻辑都比较简单;
3、更加完整和详细的 demo,请参考 LuatOS 仓库 中各个产品目录下的 demo/u8g2
2.1 核心代码
-- 主循环
local function ui_main()
-- 初始化硬件SPI的SSD1306显示屏
local u8g2it_reslut = u8g2.begin(
{
ic = "ssd1306",
direction = 0,
mode = "spi_hw_4pin",
spi_id = 0,
spi_res = 20,
spi_dc = 21,
spi_cs = 24
},
{
width = 128,
height = 64
}
)
-- 打印初始化结果
log.info("u8g2初始化结果",u8g2it_reslut)
while true do
sys.wait(1000)
u8g2.ClearBuffer()
u8g2.DrawUTF8("屏幕宽度", 0, 24)
u8g2.DrawUTF8("屏幕高度", 0, 42)
u8g2.DrawUTF8(":"..u8g2.GetDisplayWidth(), 80, 24)
u8g2.DrawUTF8(":"..u8g2.GetDisplayHeight(), 80, 42)
u8g2.SendBuffer()
sys.wait(1000)
u8g2.ClearBuffer()
u8g2.DrawUTF8("画线测试:", 30, 24)
for i = 0, 128, 8 do
u8g2.DrawLine(0,40,i,40)
u8g2.DrawLine(0,60,i,60)
u8g2.SendBuffer()
sys.wait(100)
end
sys.wait(1000)
u8g2.ClearBuffer()
u8g2.DrawUTF8("画圆测试:", 30, 24)
u8g2.DrawCircle(30,50,10,15)
u8g2.DrawDisc(90,50,10,15)
u8g2.SendBuffer()
sys.wait(1000)
u8g2.ClearBuffer()
u8g2.DrawUTF8("椭圆测试:", 30, 24)
u8g2.DrawEllipse(30,50,6,10,15)
u8g2.DrawFilledEllipse(90,50,6,10,15)
u8g2.SendBuffer()
sys.wait(1000)
u8g2.ClearBuffer()
u8g2.DrawUTF8("方框测试:", 30, 24)
u8g2.DrawBox(30,40,30,24)
u8g2.DrawFrame(90,40,30,24)
u8g2.SendBuffer()
sys.wait(1000)
u8g2.ClearBuffer()
u8g2.DrawUTF8("圆角方框:", 30, 24)
u8g2.DrawRBox(30,40,30,24,8)
u8g2.DrawRFrame(90,40,30,24,8)
u8g2.SendBuffer()
sys.wait(1000)
u8g2.ClearBuffer()
u8g2.DrawUTF8("三角测试:", 30, 24)
u8g2.DrawTriangle(30,60, 60,30, 90,60)
u8g2.SendBuffer()
-- qrcode测试
sys.wait(1000)
u8g2.ClearBuffer()
u8g2.DrawDrcode(4, 4, "https://docs.openluat.com", 30);
u8g2.SendBuffer()
sys.wait(1000)
log.info("main", "u8g2 demo done")
end
sys.taskInit(ui_main)
三、常量详解
核心库常量,顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值,在脚本代码中不需要声明,可直接调用,包含以下常量;
3.1 u8g2.DRAW_UPPER_LEFT
参数含义:绘制左上部分;
数据类型:number;
取值范围:u8g2.DRAW_UPPER_LEFT或者2;
是否必选:常量,可选使用;
注意事项:用于DrawCircle、DrawDisc等函数的opt参数;
参数示例:以点(30,30)为圆心,画一个半径20像素只包含上左部分的实心圆
u8g2.DrawDisc(30,30,20,u8g2.DRAW_UPPER_LEFT)
3.2 u8g2.DRAW_UPPER_RIGHT
参数含义:绘制右上部分;
数据类型:number;
取值范围:u8g2.DRAW_UPPER_RIGHT或者1;
是否必选:常量,可选使用;
注意事项:用于DrawCircle、DrawDisc等函数的opt参数;
参数示例:以点(30,30)为圆心,画一个半径20像素只包含右上部分的实心圆
u8g2.DrawDisc(30,30,20,u8g2.DRAW_UPPER_RIGHT)
3.3 u8g2.DRAW_LOWER_LEFT
参数含义:绘制左下部分;
数据类型:number;
取值范围:u8g2.DRAW_LOWER_LEFT或者4;
是否必选:常量,可选使用;
注意事项:用于DrawCircle、DrawDisc等函数的opt参数;
参数示例:以点(30,30)为圆心,画一个半径20像素只包含左下部分的实心圆
u8g2.DrawDisc(30,30,20,u8g2.DRAW_LOWER_LEFT)
3.4 u8g2.DRAW_LOWER_RIGHT
参数含义:绘制右下部分;
数据类型:number;
取值范围:u8g2.DRAW_LOWER_RIGHT或者8;
是否必选:常量,可选使用;
注意事项:用于DrawCircle、DrawDisc等函数的opt参数;
参数示例:以点(30,30)为圆心,画一个半径20像素只包含右下部分的实心圆
u8g2.DrawDisc(30,30,20,u8g2.DRAW_LOWER_RIGHT)
3.5 u8g2.DRAW_ALL
参数含义:绘制全部;
数据类型:number;
取值范围:u8g2.DRAW_ALL或者15;
是否必选:常量,可选使用;
注意事项:用于DrawCircle、DrawDisc等函数的opt参数;
参数示例:以点(30,30)为圆心,画一个半径20像素的实心圆
u8g2.DrawDisc(30,30,20,u8g2.DRAW_ALL)
3.6 u8g2.BTN_BW0
参数含义:文本周围没有边框;
数据类型:number;
取值范围:u8g2.BTN_BW0或者0;
是否必选:常量,可选使用;
注意事项:用于DrawButtonUTF8函数的flags参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm12)
u8g2.DrawButtonUTF8("hello luatos",0, 20, u8g2.BTN_BW0, 0, 0, 0)
3.7 u8g2.BTN_BW1
参数含义:文本周围的边框,1像素边框宽度;
数据类型:number;
取值范围:u8g2.BTN_BW1或者1;
是否必选:常量,可选使用;
注意事项:用于DrawButtonUTF8函数的flags参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm12)
u8g2.DrawButtonUTF8("hello luatos",0, 20, u8g2.BTN_BW1, 0, 0, 0)
3.8 u8g2.BTN_BW2
参数含义:文本周围的边框,2像素边框宽度;
数据类型:number;
取值范围:u8g2.BTN_BW2或者2;
是否必选:常量,可选使用;
注意事项:用于DrawButtonUTF8函数的flags参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm12)
u8g2.DrawButtonUTF8("hello luatos",0, 20, u8g2.BTN_BW2, 0, 0, 0)
3.9 u8g2.BTN_BW3
参数含义:文本周围的边框,3像素边框宽度;
数据类型:number;
取值范围:u8g2.BTN_BW3或者3;
是否必选:常量,可选使用;
注意事项:用于DrawButtonUTF8函数的flags参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm12)
u8g2.DrawButtonUTF8("hello luatos",0, 20, u8g2.BTN_BW3, 0, 0, 0)
3.10 u8g2.BTN_SHADOW0
参数含义:启用阴影,与框架无间隙;
数据类型:number;
取值范围:u8g2.BTN_SHADOW0或者8;
是否必选:常量,可选使用;
注意事项:用于DrawButtonUTF8函数的flags参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm12)
u8g2.DrawButtonUTF8("hello luatos",0, 20, u8g2.BTN_BW2 + u8g2.BTN_SHADOW0,
0, 0, 0)
3.11 u8g2.BTN_SHADOW1
参数含义:启用阴影,到帧的1像素间隙;
数据类型:number;
取值范围:u8g2.BTN_SHADOW1或者16;
是否必选:常量,可选使用;
注意事项:用于DrawButtonUTF8函数的flags参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm12)
u8g2.DrawButtonUTF8("hello luatos",0, 20, u8g2.BTN_BW2 + u8g2.BTN_SHADOW1,
0, 0, 0)
3.12 u8g2.BTN_SHADOW2
参数含义:启用阴影,到帧的2像素间隙;
数据类型:number;
取值范围:u8g2.BTN_SHADOW2或者24;
是否必选:常量,可选使用;
注意事项:用于DrawButtonUTF8函数的flags参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm12)
u8g2.DrawButtonUTF8("hello luatos",0, 20, u8g2.BTN_BW2 + u8g2.BTN_SHADOW2,
0, 0, 0)
3.13 u8g2.BTN_INV
参数含义:反转文本;
数据类型:number;
取值范围:u8g2.BTN_INV或者32;
是否必选:常量,可选使用;
注意事项:用于DrawButtonUTF8函数的flags参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm12)
u8g2.DrawButtonUTF8("hello luatos",0, 20, u8g2.BTN_INV, 0, 0, 0)
3.14 u8g2.BTN_HCENTER
参数含义:将文本中心置于所设置的坐标处;
数据类型:number;
取值范围:u8g2.BTN_HCENTER或者64;
是否必选:常量,可选使用;
注意事项:用于DrawButtonUTF8函数的flags参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm12)
u8g2.DrawButtonUTF8("hello luatos",48, 20, u8g2.BTN_HCENTER, 0, 0, 0)
3.15 u8g2.BTN_XFRAME
参数含义:在按钮周围绘制第二个1像素框;
数据类型:number;
取值范围:u8g2.BTN_XFRAME或者128;
是否必选:常量,可选使用;
注意事项:用于DrawButtonUTF8函数的flags参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm12)
u8g2.DrawButtonUTF8("hello luatos",48, 20, u8g2.BTN_INV +
u8g2.BTN_BW1+u8g2.BTN_XFRAME, 0, 0, 0)
3.16 u8g2.font_opposansm10
参数含义:设置字体为10号英文字体,可显示英文、数字、英文符号;
数据类型:userdata;
取值范围:u8g2.font_opposansm10;
是否必选:可选使用;
注意事项:用于SetFont函数的font参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm10)
3.17 u8g2.font_opposansm12
参数含义:设置字体为12号英文字体,可显示英文、数字、英文符号;
数据类型:userdata;
取值范围:u8g2.font_opposansm12;
是否必选:可选使用;
注意事项:用于SetFont函数的font参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm12)
3.18 u8g2.font_opposansm16
参数含义:设置字体为16号英文字体,可显示英文、数字、英文符号;
数据类型:userdata;
取值范围:u8g2.font_opposansm16;
是否必选:可选使用;
注意事项:用于SetFont函数的font参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm16)
3.19 u8g2.font_opposansm18
参数含义:设置字体为18号英文字体,可显示英文、数字、英文符号;
数据类型:userdata;
取值范围:u8g2.font_opposansm18;
是否必选:可选使用;
注意事项:用于SetFont函数的font参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm18)
3.20 u8g2.font_opposansm20
参数含义:设置字体为20号英文字体,可显示英文、数字、英文符号;
数据类型:userdata;
取值范围:u8g2.font_opposansm20;
是否必选:可选使用;
注意事项:用于SetFont函数的font参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm20)
3.21 u8g2.font_opposansm22
参数含义:设置字体为22号英文字体,可显示英文、数字、英文符号;
数据类型:userdata;
取值范围:u8g2.font_opposansm22;
是否必选:可选使用;
注意事项:用于SetFont函数的font参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm22)
3.22 u8g2.font_opposansm24
参数含义:设置字体为24号英文字体,可显示英文、数字、英文符号;
数据类型:userdata;
取值范围:u8g2.font_opposansm24;
是否必选:可选使用;
注意事项:用于SetFont函数的font参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm24)
3.23 u8g2.font_opposansm32
参数含义:设置字体为32号英文字体,可显示英文、数字、英文符号;
数据类型:userdata;
取值范围:u8g2.font_opposansm32;
是否必选:可选使用;
注意事项:用于SetFont函数的font参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm32)
3.24 u8g2.font_opposansm12_chinese
参数含义:设置字体为12号中文字体,可显示中文、英文、数字、英文符号;
数据类型:userdata;
取值范围:u8g2.font_opposansm12_chinese;
是否必选:可选使用;
注意事项:用于SetFont函数的font参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm12_chinese)
3.25 u8g2.font_opposansm16_chinese
参数含义:设置字体为16号中文字体,可显示中文、英文、数字、英文符号;
数据类型:userdata;
取值范围:u8g2.font_opposansm16_chinese;
是否必选:可选使用;
注意事项:用于SetFont函数的font参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm16_chinese)
3.26 u8g2.font_opposansm24_chinese
参数含义:设置字体为24号中文字体,可显示中文、英文、数字、英文符号;
数据类型:userdata;
取值范围:u8g2.font_opposansm24_chinese;
是否必选:可选使用;
注意事项:用于SetFont函数的font参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm24_chinese)
3.27 u8g2.font_opposansm32_chinese
参数含义:设置字体为32号中文字体,可显示中文、英文、数字、英文符号;
数据类型:userdata;
取值范围:u8g2.font_opposansm32_chinese;
是否必选:可选;
注意事项:用于SetFont函数的font参数;
参数示例:u8g2.SetFont(u8g2.font_opposansm32_chinese)
四、函数详解
4.1 u8g2.begin(conf)
功能
显示屏初始化配置;
注意事项
在使用任何 u8g2 绘图功能前,必须先调用此函数初始化显示屏;
参数
conf
参数含义:显示屏配置信息表;
数据类型:table;
取值范围:必须包含ic、direction、mode等必要字段;
是否必选:必须传入此参数;
注意事项:在使用任何u8g2绘图功能前,必须先调用一次此函数初始化显示屏;
参数示例:table内包含多个表格参数,每个表格参数具体说明如下:
{
参数含义:屏幕驱动IC型号
数据类型:string
取值范围:"ssd1306", "st7565", "ssd1309", "ssd1322", "sh1106", "sh1107",
"sh1108", "st7567" "uc1701" "ssd1306_128x32" "custom";
是否必选:必须传入此参数
注意事项:使用自定义屏幕初始化时需设置为"custom"
参数示例:"ssd1306"
ic = ,
参数含义:屏幕显示方向
数据类型:number
取值范围:0, 90, 180, 270
是否必选:可选传入此参数,不传入默认0
注意事项:设置屏幕的显示方向
参数示例:0
direction = ,
参数含义:通信模式
数据类型:string
取值范围:"i2c_hw" - 硬件I2C模式
"i2c_sw" - 软件I2C模式
"spi_hw_4pin" - 硬件SPI 4线模式
是否必选:必须传入此参数
注意事项:根据实际硬件连接选择对应的通信模式
参数示例:"i2c_hw"
mode = ,
参数含义:硬件I2C端口号
数据类型:number
取值范围:有效的I2C端口号
是否必选:当mode为"i2c_hw"时必须传入此参数
注意事项:暂无
参数示例:0
i2c_id = ,
参数含义:I2C通信速度
数据类型:number
取值范围:i2c.SLOW(100kHz), i2c.FAST(400kHz),i2c.PLUS(1MHz)标准速度
是否必选:可选传入此参数,不填默认为i2c.SLOW(100k);
注意事项:设置I2C总线通信速率
参数示例:i2c.FAST
i2c_speed = ,
参数含义:软件I2C时钟引脚
数据类型:number
取值范围:有效的GPIO端口号
是否必选:当mode为"i2c_sw"时必须传入此参数
注意事项:暂无
参数示例:6
i2c_scl = ,
参数含义:软件I2C数据引脚
数据类型:number
取值范围:有效的GPIO端口号
是否必选:当mode为"i2c_sw"时必须传入此参数
注意事项:暂无
参数示例:7
i2c_sda = ,
参数含义:硬件SPI端口号
数据类型:number
取值范围:有效的SPI端口号
是否必选:当mode为"spi_hw_4pin"时必须传入此参数
注意事项:暂无
参数示例:0
spi_id = ,
参数含义:SPI复位引脚
数据类型:number
取值范围:有效的GPIO端口号
是否必选:当mode为"spi_hw_4pin"时必须传入此参数
注意事项:暂无
参数示例:10
spi_res = ,
参数含义:SPI数据/命令选择引脚
数据类型:number
取值范围:有效的GPIO端口号
是否必选:当mode为"spi_hw_4pin"时必须传入此参数
注意事项:用于区分数据传输和命令传输
参数示例:11
spi_dc = ,
参数含义:SPI片选引脚
数据类型:number
取值范围:有效的GPIO端口号
是否必选:当mode为"spi_hw_4pin"时必须传入此参数
注意事项:暂无
参数示例:12
spi_cs = ,
},
{
参数含义:屏幕宽度分辨率
数据类型:number
取值范围:正整数
是否必选:可选传入此参数,不填默认为128,获取屏幕宽度时返回0;
注意事项:用户根据屏的参数自行修改
参数示例:128
width = ,
参数含义:屏幕高度分辨率
数据类型:number
取值范围:正整数
是否必选:可选传入此参数,不填默认为64,获取屏幕高度时返回0;
注意事项:用户根据屏的参数自行修改
参数示例:64
height = ,
参数含义:自定义初始化命令序列
数据类型:table
取值范围:包含初始化命令序列的table
是否必选:可选传入此参数,使用”custom”方式初始化时使用;
注意事项:命令格式:0xF8, 0x00;
参数示例:{0xF8, 0x00}
initcmd = ,
参数含义:睡眠命令
数据类型:number
取值范围:十六进制命令值
是否必选:可选传入此参数,默认0xAE
注意事项:使用u8g2.sleep()时发送配置的命令
参数示例:0xAE
sleepcmd = ,
参数含义:唤醒命令
数据类型:number
取值范围:十六进制命令值
是否必选:可选传入此参数,默认0xAF
注意事项:使用u8g2.wakeup()时发送配置的命令
参数示例:0xAF
wakecmd = ,
},
返回值
local result = u8g2.begin(conf)
result
含义说明:初始化结果代码;
数据类型:number;
取值范围:1-初始化成功,2-已经初始化过,3-内存不足,4-初始化失败;
注意事项:返回1表示初始化成功,可以正常使用;
返回示例:1
示例 1 内置型号初始化
-- 初始化硬件I2C的SSD1306显示屏
local u8g2it_reslut = u8g2.begin(
{
ic = "ssd1306",
direction = 0,
mode = "i2c_hw",
i2c_id = 0
}
)
log.info("u8g2初始化结果",u8g2it_reslut)
-- 初始化软件I2C的SSD1306显示屏
local u8g2it_reslut = u8g2.begin(
{
ic = "ssd1306",
direction = 0,
mode = "i2c_sw",
i2c_scl = 1,
i2c_sda = 4
}
)
log.info("u8g2初始化结果",u8g2it_reslut)
-- 初始化硬件SPI的SSD1306显示屏
local u8g2it_reslut = u8g2.begin(
{
ic = "ssd1306",
direction = 0,
mode = "spi_hw_4pin",
spi_id = 0,
spi_res = 20,
spi_dc = 21,
spi_cs = 24
}
)
log.info("u8g2初始化结果",u8g2it_reslut)
示例 2 通用硬件 SPI 接口,使用”custom”方式初始化
local spi_id, spi_res, spi_dc, spi_cs = 0, 22, 10, 8
-- 初始化硬件spi的自定义命令屏幕
local u8g2it_reslut = u8g2.begin(
{
ic = "custom",
direction = 0,
mode = "spi_hw_4pin",
spi_id = spi_id,
spi_res = spi_res,
spi_dc = spi_dc,
spi_cs = spi_cs
},
{
width = 128, --分辨率宽度,128像素;用户根据屏的参数自行修改
height = 64, --分辨率高度,64像素;用户根据屏的参数自行修改
-- 初始化命令表,此表命令需要根据所使用芯片对应的手册填
initcmd =
{
0xE2, -- 系统复位
0x82, -- 设置偏压比
0x2F, -- 电源控制(开启内部电荷泵)
0x26, -- 电阻比率设置
0xF8, 0x00, -- 设置显示偏移(垂直偏移量为0)
0x81, 0x09, -- 设置对比度(0x09为对比度值)
0x40, -- 设置显示起始行(第0行)
0xC8, -- COM扫描方向(反向)
0xA4, -- 正常显示模式
0xAF, -- 开启显示
},
-- 休眠命令
sleepcmd = 0xAE,
-- 唤醒命令
wakecmd = 0xAF,
}
)
log.info("u8g2初始化结果",u8g2it_reslut)
示例 3 硬件 I2C 接口,使用”custom”方式初始化
-- 初始化显示屏,此处为SSD1315
local u8g2it_reslut = u8g2.begin(
{
ic = "custom",
direction = 0,
mode="i2c_hw",
i2c_id=1
},
{
width = 128, -- 分辨率宽度,
height = 64, -- 分辨率高度,
-- 初始化命令表,此表命令需要根据所使用芯片对应的手册填
initcmd =
{
0xAE, -- 关闭显示
0x40, -- 设置显示起始行
0xA1, -- 设置段重映射(SEG0到SEG131)
0xC0, -- 设置COM扫描方向(COM0到COM64)
0xA2, -- 设置u8g2偏置比
0x2F, -- 设置电源控制(开启电荷泵)
0x26, -- 设置电阻比
0x81, 0x10, -- 设置电子音量/对比度
0xFA, 0x01, -- 设置温度补偿
0xAC, 0x00, -- 关闭静态指示器
0xA6, -- 正常显示(非反转)
0xAF -- 开启显示
},
-- 休眠命令
sleepcmd = 0xAE,
-- 唤醒命令
wakecmd = 0xAF,
}
)
log.info("u8g2初始化结果", u8g2it_reslut)
示例 4 软件 I2C 接口,使用”custom”方式初始化
local u8g2it_reslut = u8g2.begin(
{
ic = "custom",
direction = 0,
mode="i2c_sw",
i2c_scl=1,
i2c_sda=4
}
)
log.info("u8g2初始化结果", u8g2it_reslut)
4.2 u8g2.close()
功能
关闭显示屏;
注意事项
关闭后需要重新初始化才能使用 u8g2 相关功能;
参数
无
返回值
无
示例
-- 关闭显示屏
u8g2.close()
4.3 u8g2.ClearBuffer()
功能
清空内存帧缓冲区中的所有像素;
注意事项
此函数只清空内存缓冲区,需要调用 SendBuffer()才能更新到屏幕;
参数
无
返回值
无
示例
-- 清空缓冲区
u8g2.ClearBuffer()
-- 绘制1个圆
u8g2.DrawCircle(60, 30, 8)
-- 将缓冲区内容更新到屏幕
u8g2.SendBuffer()
4.4 u8g2.SendBuffer()
功能
将内存帧缓冲区的内容发送到显示器;
注意事项
所有绘图操作都是在内存缓冲区中进行,需要调用此函数才能显示到屏幕;
参数
无
返回值
无
示例
-- 绘制1个圆
u8g2.DrawCircle(60, 30, 8)
-- 将缓冲区内容更新到屏幕
u8g2.SendBuffer()
4.5 u8g2.CopyBuffer(buff)
功能
获取底层图像缓冲区内容;
注意事项
需要在 u8g2 初始化之后才能调用;
参数
buff
参数含义:zbuff实例,用于接收图像数据;
数据类型:userdata;
取值范围:空间大小要大于等于底层缓冲区大小;
是否必选:可选传入此参数,不填则获取缓冲区大小,填参数则拷贝底层缓冲区给参数对应的buff区;
注意事项:需要先创建足够大的zbuff;
参数示例:-- 本函数在u8g2初始化之后才能调用
-- 获取底层图像缓冲区大小
local sz = u8g2.CopyBuffer()
-- 创建一个与底层图像缓冲区大小相同的新缓冲区buff
local buff = zbuff.create(sz)
-- 拷贝底层图像缓冲区数据给buff
u8g2.CopyBuffer(buff)
返回值
local size = u8g2.CopyBuffer(buff)
size
含义说明:成功返回缓冲区大小,失败返回nil;
数据类型:number或nil;
取值范围:无特别限制;
注意事项:暂无;
返回示例:1024
示例
-- 本函数在u8g2初始化之后才能调用
-- 获取底层图像缓冲区大小
local sz = u8g2.CopyBuffer()
-- 创建一个与底层图像缓冲区大小相同的新缓冲区buff
local buff = zbuff.create(sz)
-- 拷贝底层图像缓冲区数据给buff
u8g2.CopyBuffer(buff)
4.6 u8g2.SetFont(font, indentation)
功能
设置当前字体,若未进行初始化,默认为 8 像素的英文字体;
注意事项
设置后会影响后续所有文本绘制操作;
参数
font
参数含义:字体对象;
数据类型:userdata;
取值范围:u8g2提供的字体常量;
是否必选:必须传入此参数;
注意事项:字体常量详见常量详解的3.16到3.27章节;
参数示例:u8g2.font_opposansm12
indentation
参数含义:等宽字体ASCII字符右侧缩进像素数,目前字体常量中没有等宽字体;
例如:等宽字体中"合宙i i i i "显示会和中文一样宽,可以选择使用此参数删除右侧空白,
显示为"合宙iii",
数据类型:number;
取值范围:0-127;
是否必选:可选传入此参数;
注意事项:非等宽字体此参数无效;
参数示例:2
返回值
无
示例
-- 设置英文字体
u8g2.SetFont(u8g2.font_opposansm12)
-- 设置中文字体
u8g2.SetFont(u8g2.font_opposansm12_chinese)
-- 设置字体并指定缩进
u8g2.SetFont(u8g2.font_opposansm12, 2)
4.7 u8g2.SetFontMode(mode)
功能
设置字体渲染模式;
注意事项
影响文本绘制时的背景透明效果;
参数
mode
参数含义:字体渲染模式;
数据类型:number;
取值范围:0-禁用背景透明,1-启用背景透明;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:1
返回值
无
示例
-- 启用背景透明模式
u8g2.SetFontMode(1)
-- 禁用背景透明模式
u8g2.SetFontMode(0)
4.8 u8g2.DrawUTF8(str, x, y)
功能
在指定位置绘制 UTF-8 编码文本;
注意事项
坐标点为文本左下角位置,需要调用 SendBuffer()才能显示;
参数
str
参数含义:要显示的UTF-8编码格式文本内容;
数据类型:string;
取值范围:任意UTF-8编码字符串;
是否必选:必须传入此参数;
注意事项:需要设置合适的字体;
参数示例:"Hello World"
x
参数含义:文本左下角的X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左下角开始;
参数示例:10
y
参数含义:文本左下角的Y坐标;
数据类型:number;
取值范围:文字高度至屏幕宽度加文字高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左下角开始;
参数示例:20
返回值
无
示例
-- 绘制文本
u8g2.DrawUTF8("欢迎使用LuatOS", 10, 20)
4.9 u8g2.DrawButtonUTF8(str,x, y, flags, width, padding_h, padding_v)
功能
在提供的文本周围画一个框。这与 DrawUTF8 接口类似都是使用 UTF-8 编码,但为文本添加了一些装饰。要调用 u8g2.SendBuffer()才会更新到屏幕;
注意
设置坐标为显示字符串左下角坐标
参数
str
参数含义:按钮文本内容,UTF-8编码;
数据类型:string;
取值范围:任意字符串;
是否必选:必须传入此参数;
注意事项:需要设置合适的字体;
参数示例:"合宙LuatOS"
x
参数含义:按钮的X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左下角开始;
参数示例:10
y
参数含义:按钮的Y坐标;
数据类型:number;
取值范围:文字高度至屏幕宽度加文字高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左下角开始;
参数示例:20
flags
参数含义:按钮样式标志;
数据类型:number;
取值范围:u8g2按钮常量组合;
是否必选:必须传入此参数;
注意事项:多个标志可以用"或"运算组合;
参数示例:u8g2.BTN_BW1 | u8g2.BTN_HCENTER
width
参数含义:按钮的最小宽度。如果为0或小于等于文本宽度,则文本宽度将用于框架;
如果所设置的按钮宽度大于文本宽度,默认在字符串右侧与按钮之间按超出部分像素显示空白。
数据类型:number;
取值范围:0或正数;
是否必选:必须传入此参数;
注意事项:0表示使用文本宽度;
参数示例:0
padding_h
参数含义:字符串距离水平方向距离边框的像素;
数据类型:number;
取值范围:任意正数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:2
padding_v
参数含义:字符串竖直方向距离边框的像素;
数据类型:number;
取值范围:任意正数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:2
返回值
无
示例
-- 设置字体
u8g2.SetFont(u8g2.font_opposansm12)
-- 显示一个带边框和阴影的按钮
u8g2.DrawButtonUTF8("hello luatos",10, 20, u8g2.BTN_BW2 + u8g2.BTN_SHADOW2, 0, 0, 0)
4.10 u8g2.drawGtfontGb2312(str, size, x, y)
功能
使用 gtfont 显示 GB2312 编码字符串,字符串内容左上角显示在设置的坐标位置;
注意事项
需要外置 gtfont 字体芯片并进行初始化后才能使用,不需要使用 u8g2.SetFont(font, indentation)进行设置;
参数
str
参数含义:要显示的GB2312字符串;
数据类型:string;
取值范围:GB2312编码字符串;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:"中文文本"
size
参数含义:字体大小;
数据类型:number;
取值范围:16-192;
是否必选:必须传入此参数;
注意事项:支持16-192号大小字体;
参数示例:32
x
参数含义:文本X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:0
y
参数含义:文本Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:0
返回值
无
示例
-- 显示GB2312文本
u8g2.drawGtfontGb2312("中文文本", 32, 0, 0)
4.11 u8g2.drawGtfontUtf8(str, size, x, y)
功能
使用 gtfont 显示 UTF-8 编码字符串,字符串内容左上角显示在设置的坐标位置;
注意事项
需要外置 gtfont 字体芯片并进行初始化后才能使用,不需要使用 u8g2.SetFont(font, indentation)进行设置;
参数
str
参数含义:要显示的UTF-8字符串;
数据类型:string;
取值范围:UTF-8编码字符串;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:"中文文本"
size
参数含义:字体大小;
数据类型:number;
取值范围:16-192;
是否必选:必须传入此参数;
注意事项:支持16-192号大小字体;
参数示例:32
x
参数含义:文本X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:0
y
参数含义:文本Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:0
返回值
无
示例
-- 显示UTF-8文本
u8g2.drawGtfontUtf8("中文文本", 32, 0, 0)
4.12 u8g2.SetDrawColor(c)
功能
设置绘图颜色;
注意事项
影响后续所有绘图操作的颜色;
参数
c
参数含义:颜色值;
数据类型:number;
取值范围:0-无色,1-有色,2-与底色异或;
0-无色:显示的内容是无色的,若没有背景色则看不到内容,
1-有色:显示的内容是有颜色的,没有背景色的时候,内容也可以看到,
2-与底色异或:有背景色的地方内容显示透明,无背景色的地方显示有色的内容;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:1
返回值
无
示例
-- 设置绘图颜色为有色
u8g2.SetDrawColor(1)
4.13 u8g2.DrawPixel(x, y)
功能
在指定位置绘制一个点;
注意事项
需要调用 SendBuffer()才能显示;
参数
x
参数含义:点的X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:20
y
参数含义:点的Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:5
返回值
无
示例
-- 绘制一个点
u8g2.DrawPixel(20, 5)
4.14 u8g2.DrawLine(x0, y0, x1, y1)
功能
在两点之间绘制一条直线;
注意事项
需要调用 SendBuffer()才能显示;
参数
x0
参数含义:起点X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:10
y0
参数含义:起点Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:10
x1
参数含义:终点X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:20
y1
参数含义:终点Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:32
返回值
无
示例
-- 绘制一条直线
u8g2.DrawLine(20, 5, 5, 32)
4.15 u8g2.DrawCircle(x0, y0, rad, opt)
功能
绘制空心圆;
注意事项
可以绘制整个圆或部分圆弧;
参数
x0
参数含义:圆心X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:60
y0
参数含义:圆心Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:30
rad
参数含义:圆半径;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:8
opt
参数含义:绘制选项;
数据类型:number;
取值范围:u8g2圆弧绘制常量,参考常量解释中的3.1-3.4;
是否必选:可选传入此参数;
注意事项:默认绘制整个圆;
参数示例:u8g2.DRAW_ALL
返回值
无
示例
-- 绘制整个圆
u8g2.DrawCircle(60, 30, 8, u8g2.DRAW_ALL)
-- 绘制右上四分之一圆
u8g2.DrawCircle(60, 30, 8, u8g2.DRAW_UPPER_RIGHT)
4.16 u8g2.DrawDisc(x0, y0, rad, opt)
功能
绘制实心圆;
注意事项
可以绘制整个实心圆或部分实心圆弧;
参数
x0
参数含义:圆心X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:60
y0
参数含义:圆心Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:30
rad
参数含义:圆半径;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:8
opt
参数含义:绘制选项;
数据类型:number;
取值范围:u8g2圆弧绘制常量,参考常量解释中的3.1-3.4;
是否必选:可选传入此参数;
注意事项:默认绘制整个实心圆;
参数示例:u8g2.DRAW_ALL
返回值
无
示例
-- 绘制整个实心圆
u8g2.DrawDisc(60, 30, 8, u8g2.DRAW_ALL)
4.17 u8g2.DrawEllipse(x0, y0, rx, ry, opt)
功能
绘制空心椭圆;
注意事项
可以绘制整个椭圆或部分椭圆弧;
参数
x0
参数含义:椭圆中心X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:60
y0
参数含义:椭圆中心Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:30
rx
参数含义:椭圆X轴半径;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:15
ry
参数含义:椭圆Y轴半径;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:8
opt
参数含义:绘制选项;
数据类型:number;
取值范围:u8g2椭圆绘制常量,参考常量解释中的3.1-3.4;
是否必选:可选传入此参数;
注意事项:默认绘制整个椭圆;
参数示例:u8g2.DRAW_ALL
返回值
无
示例
-- 绘制整个椭圆
u8g2.DrawEllipse(60, 30, 15, 8, u8g2.DRAW_ALL)
4.18 u8g2.DrawFilledEllipse(x0, y0, rx, ry, opt)
功能
绘制实心椭圆;
注意事项
可以绘制整个实心椭圆或部分实心椭圆;
参数
x0
参数含义:椭圆中心X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:60
y0
参数含义:椭圆中心Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:30
rx
参数含义:椭圆X轴半径;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:15
ry
参数含义:椭圆Y轴半径;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:8
opt
参数含义:绘制选项;
数据类型:number;
取值范围:u8g2椭圆绘制常量,参考常量解释中的3.1-3.4;
是否必选:可选传入此参数;
注意事项:默认绘制整个实心椭圆;
参数示例:u8g2.DRAW_ALL
返回值
无
示例
-- 绘制实心椭圆
u8g2.DrawFilledEllipse(60, 30, 15, 8)
4.19 u8g2.DrawBox(x, y, w, h)
功能
绘制实心矩形;
注意事项
从左上角坐标开始绘制;
参数
x
参数含义:矩形左上角X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:3
y
参数含义:矩形左上角Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:7
w
参数含义:矩形宽度;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:25
h
参数含义:矩形高度;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:15
返回值
无
示例
-- 绘制实心矩形
u8g2.DrawBox(3, 7, 25, 15)
4.20 u8g2.DrawFrame(x, y, w, h)
功能
绘制空心矩形框;
注意事项
从左上角坐标开始绘制;
参数
x
参数含义:矩形左上角X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:3
y
参数含义:矩形左上角Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:7
w
参数含义:矩形宽度;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:25
h
参数含义:矩形高度;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:15
返回值
无
示例
-- 绘制空心矩形框
u8g2.DrawFrame(3, 7, 25, 15)
4.21 u8g2.DrawRBox(x, y, w, h, r)
功能
绘制圆角实心矩形;
注意事项
从左上角坐标开始绘制;
参数
x
参数含义:矩形左上角X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:3
y
参数含义:矩形左上角Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:7
w
参数含义:矩形宽度;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:25
h
参数含义:矩形高度;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:15
r
参数含义:圆角半径;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:3
返回值
无
示例
-- 绘制圆角实心矩形
u8g2.DrawRBox(3, 7, 25, 15, 3)
4.22 u8g2.DrawRFrame(x, y, w, h, r)
功能
绘制圆角空心矩形框;
注意事项
从左上角坐标开始绘制;
参数
x
参数含义:矩形左上角X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:3
y
参数含义:矩形左上角Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:7
w
参数含义:矩形宽度;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:25
h
参数含义:矩形高度;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:15
r
参数含义:圆角半径;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:3
返回值
无
示例
-- 绘制圆角空心矩形框
u8g2.DrawRFrame(3, 7, 25, 15, 3)
4.23 u8g2.DrawTriangle(x0, y0, x1, y1, x2, y2)
功能
绘制实心三角形;
注意事项
按三个顶点坐标绘制三角形;
参数
x0
参数含义:第一个顶点X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:20
y0
参数含义:第一个顶点Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:5
x1
参数含义:第二个顶点X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:27
y1
参数含义:第二个顶点Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:50
x2
参数含义:第三个顶点X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:5
y2
参数含义:第三个顶点Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:32
返回值
无
示例
-- 绘制三角形
u8g2.DrawTriangle(20, 5, 27, 50, 5, 32)
4.24 u8g2.SetBitmapMode(mode)
功能
设置位图显示模式;
注意事项
影响位图绘制时的背景透明效果;
参数
mode
参数含义:位图模式;
数据类型:number;
取值范围:0-禁用背景透明,1-启用背景透明;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:1
返回值
无
示例
-- 启用位图背景透明模式
u8g2.SetBitmapMode(1)
4.25 u8g2.DrawXBM(x, y, w, h, data)
功能
绘制 XBM 格式位图;
注意事项
XBM 是单色位图格式,每个 bit 位表示一个像素;
参数
x
参数含义:位图左上角X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:0
y
参数含义:位图左上角Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:0
w
参数含义:位图宽度;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:16
h
参数含义:位图高度;
数据类型:number;
取值范围:大于0的整数;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:16
data
参数含义:位图数据;
数据类型:string;
取值范围:XBM格式数据字符串;
是否必选:必须传入此参数;
注意事项:数据需要是XBM格式;
参数示例:string.char(0x00, 0x18, 0x24, 0x42, ...)
返回值
无
示例
-- 在(0,0)为左上角,绘制 16x16 "今" 的位图
-- 取模使用PCtou8g22002软件
u8g2.DrawXBM(0, 0, 16, 16, string.char(
0x80,0x00,0x80,0x00,0x40,0x01,0x20,0x02,
0x10,0x04,0x48,0x08,0x84,0x10,0x83,0x60,
0x00,0x00,0xF8,0x0F,0x00,0x08,0x00,0x04,
0x00,0x04,0x00,0x02,0x00,0x01,0x80,0x00
))
4.26 u8g2.DrawDrcode(x, y, str, size)
功能
以参数(x,y)坐标为左上角,绘制一个内容为参数 str,边长像素为传入参数 size 的正方形二维码;
注意事项
二维码大小会根据内容和纠错等级自动调整;
参数
x
参数含义:二维码左上角X坐标;
数据类型:number;
取值范围:0至屏幕宽度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:10
y
参数含义:二维码左上角Y坐标;
数据类型:number;
取值范围:0至屏幕高度减1;
是否必选:必须传入此参数;
注意事项:坐标从屏幕左上角开始;
参数示例:10
str
参数含义:二维码内容;
数据类型:string;
取值范围:任意字符串;
是否必选:必须传入此参数;
注意事项:内容长度影响二维码大小;
参数示例:"https://docs.openluat.com"
size
参数含义:二维码尺寸,显示大小为正方形,尺寸 = size*size;
数据类型:number;
取值范围:正整数,size建议填大于21的参数;
是否必选:必须传入此参数;
注意事项:二维码等级1级-40级,每级尺寸按(8+4*二维码等级+9)计算,
1级尺寸21,2级尺寸25,3级尺寸29……40级尺寸177,假如设置尺寸为24,
24大于1级尺寸小于2级尺寸,那么会显示一个21*21像素的二维码,外面3个像素的白框。
参数示例:21
返回值
无
示例
-- 绘制二维码
u8g2.DrawDrcode(10, 10, "https://docs.openluat.com", 49)
4.27 u8g2.GetDisplayWidth()
功能
获取显示屏宽度;
注意事项
需要在显示屏初始化后调用;
参数
无
返回值
local width = u8g2.GetDisplayWidth()
width
含义说明:显示屏宽度像素数;
数据类型:number;
取值范围:取决于具体屏幕;
注意事项:暂无;
返回示例:128
示例
-- 获取屏幕宽度
local width = u8g2.GetDisplayWidth()
log.info("u8g2", "屏幕宽度:", width)
4.28 u8g2.GetDisplayHeight()
功能
获取显示屏高度;
注意事项
需要在显示屏初始化后调用;
参数
无
返回值
local height = u8g2.GetDisplayHeight()
height
含义说明:显示屏高度像素数;
数据类型:number;
取值范围:取决于具体屏幕;
注意事项:暂无;
返回示例:64
示例
-- 获取屏幕高度
local height = u8g2.GetDisplayHeight()
log.info("u8g2", "屏幕高度:", height)
4.29 u8g2.SetContrast(contrast)
功能
设置屏幕对比度,如果对比度低了显示的颜色可能看不见,对比度高了会显示一片看不清内容或者刺眼;
注意事项
对比度范围取决于具体屏幕驱动 IC;
参数
contrast
参数含义:对比度值;
数据类型:number;
取值范围:取决于屏幕IC(如ST7567为0-63);
是否必选:必须传入此参数;
注意事项:不同屏幕IC范围不同;
参数示例:32
返回值
无
示例
-- 设置屏幕对比度
u8g2.SetContrast(32)
4.30 u8g2.SetPowerSave(is_enable)
功能
设置省电模式,进入省电模式黑屏但不影响数据刷新,关闭省电模式后恢复显示,默认关闭省电模式;
参数
is_enable
参数含义:是否启用省电模式;
数据类型:boolean;
取值范围:true-启用,false-禁用;
是否必选:必须传入此参数;
注意事项:暂无;
参数示例:true
返回值
无
示例
-- 开启省电模式
u8g2.SetPowerSave(true)
-- 关闭省电模式
u8g2.SetPowerSave(false)
五、产品支持说明
1、本库只支持普通 SPI,不支持 LCD 专用 SPI 接口;
2、软件支持可以查看选型手册对应模组及固件是否支持 u8g2 功能或 u8g2 库
3、OLED 屏幕需要正确驱动才会显示内容,否则就是黑屏;
4、大部分 API 都只能在 lcd.init()成功后使用