跳转至

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
是否必选:常量,可选使用;
注意事项:用于DrawCircleDrawDisc等函数的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
是否必选:常量,可选使用;
注意事项:用于DrawCircleDrawDisc等函数的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
是否必选:常量,可选使用;
注意事项:用于DrawCircleDrawDisc等函数的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
是否必选:常量,可选使用;
注意事项:用于DrawCircleDrawDisc等函数的opt参数
参数示例:以点(30,30)为圆心,画一个半径20像素只包含右下部分的实心圆
        u8g2.DrawDisc(30,30,20,u8g2.DRAW_LOWER_RIGHT)

3.5 u8g2.DRAW_ALL

参数含义:绘制全部;
数据类型:number
取值范围:u8g2.DRAW_ALL或者15
是否必选:常量,可选使用;
注意事项:用于DrawCircleDrawDisc等函数的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
取值范围:必须包含icdirectionmode等必要字段
是否必选:必须传入此参数;
注意事项:在使用任何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.163.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级尺寸212级尺寸253级尺寸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()成功后使用