跳至主要內容

5.34 Graphic 设备

学习阁2026/8/18大约 33 分钟设备驱动驱动设备GraphicLCD显示

5.34 Graphic 设备

📚 本节导读

学习时长: 约 60 分钟
难度级别: ⭐⭐⭐⭐☆
前置知识: C 语言基础、LCD 显示原理、5.1 设备驱动框架、5.5 SPI 设备（部分屏走 SPI）

Graphic（图形/LCD 显示）设备是嵌入式 GUI 界面、仪表盘、工业屏的核心输出设备。OneOS 将显示设备抽象为 OS_DEVICE_TYPE_GRAPHIC 类型，提供 framebuffer 双缓冲、统一颜色格式、绘制函数库（点/线/矩形/圆/文字）与控制命令。Graphic 设备驱动位于 drivers/graphic/ 目录，核心文件为 graphic.h 与 graphic.c。

本节会带你：

  • 看懂 Graphic 设备如何基于 5.1 设备框架实现统一显示接口；
  • 掌握 os_graphic_device、os_graphic_info、os_graphic_ops、os_graphic_draw_ops、os_graphic_area 等核心结构体的每个字段；
  • 掌握颜色格式（RGB565/RGB888/ARGB8888）与 os_color_t 的位域/位运算演算；
  • 掌握 framebuffer 双缓冲机制（FRAME_NEXT/FRAME_SET/FRAME_FILL/FRAME_FLUSH）；
  • 逐个拆解 os_graphic_register、os_graphic_add_framebuffer、os_graphic_control 的完整源码；
  • 通过多个可运行示例掌握初始化、显示信息获取、绘制图形文字、双缓冲刷屏的实际开发。

说明：本节所有源码均取自项目 drivers/graphic/graphic.h 与 drivers/graphic/graphic.c，与项目源码逐字一致（含原始英文注释）。

🎯 学习目标

  • 理解 OneOS 中 Graphic 设备框架的设计理念与 framebuffer 双缓冲机制
  • 掌握 os_graphic_device、os_graphic_info、os_graphic_ops、os_graphic_draw_ops 各字段含义与来源
  • 掌握颜色格式（RGB565/RGB888/ARGB8888）与 os_color_t 的位域转换
  • 掌握 Graphic 设备控制命令（电源/信息/framebuffer/绘制）
  • 掌握 os_graphic_register、os_graphic_add_framebuffer、os_graphic_control 的使用
  • 理解更换 LCD 屏或 MCU 时如何移植 BSP 层 Graphic 驱动
  • 能够编写完整的 LCD 初始化、绘制与刷屏程序

一、概述

Graphic（图形/LCD 显示）设备是嵌入式 GUI 界面、仪表盘、工业屏的核心输出设备。OneOS 将显示设备抽象为 OS_DEVICE_TYPE_GRAPHIC 类型，提供 framebuffer 双缓冲、统一颜色格式、绘制函数库与控制命令。Graphic 设备驱动位于 drivers/graphic/ 目录下，核心头文件为 graphic.h。

Graphic 设备框架的特点：

  • framebuffer 双缓冲：支持 2 个帧缓冲，FRAME_NEXT/FRAME_SET/FRAME_FLUSH 实现无撕裂刷屏
  • 统一颜色格式：os_color_t 抽象 RGB565/RGB888/ARGB8888，位域转换自动完成
  • 绘制函数库：点、线、矩形、圆、实心图形、图像、字符、字符串
  • 硬件加速接口：GPU 混叠（blend）/块搬移（blit）预留接口
  • 多种屏驱动：ILI9341、ST7789VW、OTM8009A、HT240S030、ATK-TFLCD9341 等

1.1 Graphic 设备的分层架构

Graphic 设备基于 5.1 设备框架，通过 os_graphic_ops 与具体屏驱动解耦：

关键理解：Graphic 框架层不直接操作 LCD 寄存器。它负责"framebuffer 管理 + 控制命令分发 + 绘制函数库"，真正写 LCD 寄存器（如 ILI9341 的 0x2C 写显存命令）的是 BSP 屏驱动实现的 struct os_graphic_ops。这让上层应用与具体屏（SPI 屏/I2C 屏/DSI 屏）解耦。

1.2 Graphic 设备使用场景

一句话核心

Graphic 设备适用于需要向 LCD/显示屏输出图形、文字、图像的人机交互场景，通过 framebuffer 缓存 + 统一绘制接口实现。

与其他输出设备的机制对比

维度Graphic（LCD）Serial 串口终端7 段数码管LED 灯
输出内容图形、文字、图像文本流数字/字母开关状态
交互性高（可绘制 GUI）低（文本命令）低极低
framebuffer有（可回读）无无无
应用场景GUI、仪表、工业屏调试、终端数值显示状态指示

为什么用 Graphic 而不是串口终端：需要显示图形界面、仪表盘、图片时，串口只能输出文本，无法表达图形化界面。Graphic 提供 framebuffer 和绘制函数库，可渲染复杂 GUI。

典型应用场景

场景 1：GUI 界面刷新（双缓冲防撕裂）

┌──────────────┐  framebuffer[0]  ┌──────────────┐
│  应用绘制任务  │ ────────────────▶│   显存缓存     │
│ draw 按钮/文字│                  │  FRAME_FLUSH  │
└──────────────┘                  └──────┬───────┘
                                         │ 刷新到 LCD
                                         ▼
                                    ┌──────────┐
                                    │ LCD 屏幕  │
                                    └──────────┘

为什么用 Graphic：GUI 需要把"按钮、文字、图片"等元素渲染到屏幕。应用先把所有元素画到 framebuffer（内存），再一次性 FRAME_FLUSH 刷到 LCD，避免逐元素刷新产生的闪烁/撕裂。
实际工作：任务调 os_device_control(dev, OS_GRAPHIC_CTRL_DRAW_STRING, "Hello") 把文字画到 framebuffer → 调 OS_GRAPHIC_CTRL_FRAME_FLUSH 刷到 LCD → 屏幕显示"Hello"。

场景 2：仪表盘实时刷新（多段数据更新）

为什么用 Graphic：仪表盘指针、数值每秒更新多次，用 draw_line/draw_solid_circle 重绘指针，FRAME_FLUSH 同步刷新。
实际工作：每 100ms 用 draw_solid_rect 清除旧指针区域，draw_line 画新角度指针，FRAME_FLUSH 刷新。

选型边界表（何时不该用 Graphic）

场景该用什么为什么
只需显示少量数字7 段数码管Graphic 需要 LCD + 驱动，成本高
只需状态指示LED/GPIO无需图形渲染
只需文本日志Serial 终端无需图形，串口更简单
极高帧率视频专用 GPU/HDMIMCU 的 framebuffer 带宽有限

结合源码的使用注意点

  • 控制命令为主：Graphic 设备主要通过 os_device_control 使用（os_graphic_ops 只有 .control，无 read/write），绘制和刷屏都走控制命令（见 3.3）。
  • framebuffer 需先添加：使用 FRAME_FILL/FRAME_FLUSH 前，若 framebuffer_num == 0，需要先 os_graphic_add_framebuffer 添加缓冲（见 4.3）。
  • 颜色格式由编译期决定：os_color_t 是 RGB565/RGB888/ARGB8888 之一，由 OS_GRAPHIC_LCD_FORMAT_* 宏决定（见 3.2）。
  • 无缓冲时退化为直接写屏：绘制函数在 framebuffer_num == 0 时，会退化为调用 ops->display_area 直接把像素写屏（见 4.2 的 draw_point 分步详解）。

二、核心数据结构（字段详解）

本节对照 drivers/graphic/graphic.h 讲解 Graphic 框架的核心结构体。来源：drivers/graphic/graphic.h。

2.1 颜色结构体（os_color16 / os_color24 / os_color32 / os_color_t）

结构体位数字段说明
os_color1616 位b:5/g:6/r:5RGB565（蓝 5 位、绿 6 位、红 5 位），最常用
os_color2424 位b/g/rRGB888（各 8 位）
os_color3232 位b/g/r/aARGB8888（含 8 位透明度）

os_color_t 类型由编译期宏决定：

关键理解——OS_COLOR 宏自动做位域转换：OS_COLOR(r, g, b) 接收 8 位 R/G/B，自动按当前颜色格式转换。RGB565 时用 OS_COLOR_SET_R16/G16/B16 压缩到 5/6/5 位。

数值演算（RGB565 颜色转换）：OS_COLOR(0xFF, 0x80, 0x00)（红色 R=255、绿 G=128、蓝 B=0）：

计算项代入计算结果
OS_COLOR_SET_R16(0xFF)(0xFF >> 3) & 0x1F0x1F（5 位）
OS_COLOR_SET_G16(0x80)(0x80 >> 2) & 0x3F0x20（6 位）
OS_COLOR_SET_B16(0x00)(0x00 >> 3) & 0x1F0x00（5 位）
组成 os_color16{b=0, g=0x20, r=0x1F}红偏橙

2.2 显示设备信息 os_graphic_info

字段类型含义
pixel_formatuint8_t像素格式（OS_GRAPHIC_LCD_FORMAT_*）
bits_per_pixeluint8_t每像素位数（RGB565 为 16）
bytes_per_pixeluint8_t每像素字节数（RGB565 为 2）
bytes_per_lineuint16_t每行字节数（= 宽度 × 每像素字节数）
width/heightuint16_t屏幕宽/高（像素）
framebuffer[2]uint8_t *[2]两个帧缓冲指针（双缓冲）
framebuffer_numuint8_t已添加的帧缓冲个数（0/1/2）
framebuffer_sizeuint32_t每个帧缓冲大小
framebuffer_curruint8_t *当前正在使用的帧缓冲指针

关键理解：framebuffer[2] 支持双缓冲——一个缓冲被 FRAME_FLUSH 刷到屏幕时，应用可在另一个缓冲上继续绘制，实现无撕裂刷新。framebuffer_num 从 0 开始，os_graphic_add_framebuffer 每加一个递增（最多 2 个）。

2.3 显示设备结构体 os_graphic_device

typedef struct os_graphic_device
{
    os_device_t parent;

    struct os_graphic_info            info;
    const struct os_graphic_ops      *ops;
    const struct os_graphic_draw_ops *draw_ops;
} os_graphic_t;
字段类型含义
parentos_device_t内嵌的通用设备对象，用于接入 5.1 设备框架
infostruct os_graphic_info显示设备信息（分辨率/格式/framebuffer）
opsconst struct os_graphic_ops *屏驱动底层操作表（display_on/frame_flush/display_area）
draw_opsconst struct os_graphic_draw_ops *绘制函数表（OS_GRAPHIC_DRAW_ENABLE 时存在）

关键理解：ops 是屏驱动（操作具体 LCD 寄存器）提供的；draw_ops 是框架内置的绘制函数库（graphic.c 里的 draw_ops，见 4.4），由 os_graphic_register 在 OS_GRAPHIC_DRAW_ENABLE 时自动挂载。

2.4 屏驱动操作表 os_graphic_ops

函数指针说明
display_on开关显示（背光/显存），OS_TRUE 开、OS_FALSE 关
frame_flush把当前 framebuffer 数据刷到 LCD 屏幕
display_area把指定区域（os_graphic_area_t）绘制到屏幕
gpu_blend/gpu_blit/gpu_wait_finishGPU 硬件加速（OS_GRAPHIC_GPU_ENABLE 时存在）

关键理解：屏驱动只需实现 display_on/frame_flush/display_area 三个核心函数（GPU 相关可选）。框架的绘制函数库最终调用 display_area 或直接操作 framebuffer。

2.5 绘制操作表 os_graphic_draw_ops（OS_GRAPHIC_DRAW_ENABLE 时）

函数指针说明
draw_point/draw_line/draw_rect/draw_circle基本图形
draw_solid_rect/draw_solid_circle实心图形
draw_image图像（区域绘制）
draw_char/draw_string字符/字符串（配合字体）
set_txt_cursor/set_txt_color设置文本光标/颜色
set_font/add_font设置/添加字体
clear清屏

绘制相关结构体（os_graphic_pos_t/point_t/line_t/rect_t/circle_t/font_t）定义于 graphic.h，这里不逐一展开（见 4.4 的完整源码）。

2.6 显示区域结构体 os_graphic_area

typedef struct os_graphic_area
{
    uint16_t x; /* x coordinate. */
    uint16_t y; /* y coordinate. */
    uint16_t w; /* Width. */
    uint16_t h; /* Height.*/
    os_color_t  color;
    uint8_t *buffer;
} os_graphic_area_t;
字段类型含义
x/yuint16_t区域左上角坐标
w/huint16_t区域宽/高
coloros_color_t填充颜色（buffer 为空时用）
bufferuint8_t *图像数据指针（非空时用图像数据，空时用 color 填充）

关键理解：os_graphic_area 既可用于"填充色块"（buffer = OS_NULL），也可用于"显示图像"（buffer 指向图像数据）。os_graphic_frame_fill 根据 buffer 是否为 0 决定用 memcpy 还是逐像素填色（见 4.2）。

三、控制命令与颜色宏

本节对照 drivers/graphic/graphic.h 讲解控制命令与颜色宏。来源：drivers/graphic/graphic.h。

3.1 控制命令枚举

命令值说明
OS_GRAPHIC_CTRL_POWERON0开显示
OS_GRAPHIC_CTRL_POWEROFF1关显示
OS_GRAPHIC_CTRL_GET_INFO2获取显示信息（os_graphic_info_t *）
OS_GRAPHIC_CTRL_DISP_AREA3绘制指定区域
OS_GRAPHIC_CTRL_FRAME_NEXT4获取下一个帧缓冲（uint8_t **）
OS_GRAPHIC_CTRL_FRAME_SET5设置当前帧缓冲（uint8_t *）
OS_GRAPHIC_CTRL_FRAME_FILL6填充当前帧缓冲（os_graphic_area_t *）
OS_GRAPHIC_CTRL_FRAME_FLUSH7刷屏（把当前帧缓冲刷到 LCD）
OS_GRAPHIC_CTRL_DRAW_POINT8画点
OS_GRAPHIC_CTRL_DRAW_LINE9画线
OS_GRAPHIC_CTRL_DRAW_RECT10画矩形
OS_GRAPHIC_CTRL_DRAW_CIRCLE11画圆
OS_GRAPHIC_CTRL_DRAW_SOLID_RECT12画实心矩形
OS_GRAPHIC_CTRL_DRAW_SOLID_CIRCLE13画实心圆
OS_GRAPHIC_CTRL_DRAW_IMAGE14画图像
OS_GRAPHIC_CTRL_DRAW_CHAR15画字符
OS_GRAPHIC_CTRL_DRAW_STRING16画字符串
OS_GRAPHIC_CTRL_DRAW_SET_TXT_CURSOR17设置文本光标
OS_GRAPHIC_CTRL_DRAW_SET_TXT_COLOR18设置文本颜色
OS_GRAPHIC_CTRL_DRAW_ADD_FONT19添加字体
OS_GRAPHIC_CTRL_DRAW_SET_FONT20设置字体
OS_GRAPHIC_CTRL_DRAW_CLEAR21清屏
OS_GRAPHIC_CTRL_GPU_BLEND22GPU 混叠
OS_GRAPHIC_CTRL_GPU_ALPHAMAP_BLEND23GPU 透明度混叠
OS_GRAPHIC_CTRL_GPU_BLIT24GPU 块搬移
OS_GRAPHIC_CTRL_GPU_WAIT25GPU 等待完成

数值演算：控制命令是连续枚举，从 POWERON=0 依次递增到 GPU_WAIT=25。这些命令直接作为 os_device_control 的 cmd 传入（见 4.4 的 os_graphic_control switch）。注意：DRAW_* 系列命令在 OS_GRAPHIC_DRAW_ENABLE 宏下才被处理；GPU_* 系列在 OS_GRAPHIC_GPU_ENABLE 宏下才被处理。

3.2 颜色宏

颜色宏RGBRGB565 近似值
OS_COLOR_WHITEFF,FF,FF0xFFFF
OS_COLOR_BLACK00,00,000x0000
OS_COLOR_REDFF,00,000xF800
OS_COLOR_GREEN00,80,000x0400
OS_COLOR_BLUE00,00,FF0x001F
OS_COLOR_YELLOWFF,FF,000xFFE0

数值演算（RGB565 红色）：OS_COLOR(0xFF, 0x00, 0x00)：

计算项代入计算结果
OS_COLOR_SET_R16(0xFF)(0xFF >> 3) & 0x1F0x1F
OS_COLOR_SET_G16(0x00)(0x00 >> 2) & 0x3F0x00
OS_COLOR_SET_B16(0x00)(0x00 >> 3) & 0x1F0x00
RGB565 值r<<11 | g<<5 | b0x1F<<11 = 0xF800

位运算转换宏（RGB565 时使用）：

#define OS_COLOR_SET_R16(rr) (uint16_t)((rr >> 3) & 0x1FU)
#define OS_COLOR_SET_G16(gg) (uint16_t)((gg >> 2) & 0x3FU)
#define OS_COLOR_SET_B16(bb) (uint16_t)((bb >> 3) & 0x1FU)

#define OS_COLOR_BIT_5TO8(x) ((x * 263 + 7) >> 5)
#define OS_COLOR_BIT_6TO8(x) ((x * 259 + 3) >> 6)
宏作用
OS_COLOR_SET_R16/G16/B168 位 → 5/6/5 位压缩（存帧缓冲）
OS_COLOR_BIT_5TO8/6TO85/6 位 → 8 位扩展（读帧缓冲）

数值演算（5→8 位扩展）：OS_COLOR_BIT_5TO8(0x1F)（5 位最大值）：

计算项代入计算结果
0x1F * 263 + 731*263 + 78160
>> 58160 / 32255

5 位 0x1F（全红）扩展回 8 位 0xFF，无精度损失。

3.3 配置命令与 Kconfig

Graphic 设备的编译配置在 drivers/graphic/Kconfig（见第七章 7.1 的源码）。核心配置项：

配置说明默认值
OS_USING_GRAPHIC使能 Graphic 组件n
OS_GRAPHIC_LCD_WIDTH/HEIGHT屏宽高240/240
OS_GRAPHIC_LCD_FORMAT_*颜色格式（RGB565/RGB888/ARGB8888）RGB565
OS_GRAPHIC_DRAW_ENABLE使能绘制函数库n
OS_GRAPHIC_GPU_ENABLE使能 GPU 硬件加速n
OS_USING_DSI使用 DSI 接口n
BSP_USING_ILI9341ILI9341 屏驱动n
OS_USING_ST7789VWST7789VW 屏驱动n
OS_USING_HT240S030HT240S030 屏驱动n
BSP_USING_OTM8009AOTM8009A 屏驱动n

关键理解：OS_GRAPHIC_LCD_FORMAT_* 决定 os_color_t 类型（见 2.1）；OS_GRAPHIC_DRAW_ENABLE 决定是否编译绘制函数库（draw_ops）；OS_GRAPHIC_GPU_ENABLE 决定是否编译 GPU 控制命令分支。

四、核心 API 详解

本节逐个拆解 drivers/graphic/graphic.c 中的核心函数。来源：drivers/graphic/graphic.c。

4.1 os_graphic_register —— 注册 Graphic 设备

函数签名

os_err_t os_graphic_register(const char *name, os_graphic_t *graphic)

参数 / 返回值说明

参数类型说明
nameconst char *设备名称，如 "lcd"、"graphic"
graphicos_graphic_t *Graphic 设备结构体指针，必须已填充 ops
返回值说明
OS_SUCCESS注册成功

完整源码

分步详解

第一步：参数校验（条件 graphic 与 ops 非空）

    OS_ASSERT(graphic != OS_NULL);
    OS_ASSERT(graphic->ops != OS_NULL);

为什么断言 ops 非空：graphic->ops 是屏驱动提供的操作表（display_on/frame_flush/display_area），注册后 os_graphic_control 会访问它。若为空会空指针崩溃。

第二步：配置父设备与绘制函数表（无条件执行）

    graphic->parent.type = OS_DEVICE_TYPE_GRAPHIC;
    graphic->parent.ops  = &graphic_ops;
#ifdef OS_GRAPHIC_DRAW_ENABLE
    graphic->draw_ops = &draw_ops;
#endif
  • parent.type = OS_DEVICE_TYPE_GRAPHIC：标记为图形设备；
  • parent.ops = &graphic_ops：挂上框架层操作表（只有 .control = os_graphic_control，见下方）；
  • OS_GRAPHIC_DRAW_ENABLE 时，draw_ops = &draw_ops 挂上框架内置绘制函数库（见 4.4）。

框架层操作表 graphic_ops：

const static struct os_device_ops graphic_ops = {
    .control = os_graphic_control,
};

注意：graphic_ops 只有 control，没有 init/deinit/read/write。即 Graphic 设备不支持 os_device_read/write，所有操作都走 os_device_control。

第三步：填充显示信息（无条件执行）

    graphic->info.width           = OS_GRAPHIC_LCD_WIDTH;
    graphic->info.height          = OS_GRAPHIC_LCD_HEIGHT;
    graphic->info.pixel_format    = OS_GRAPHIC_LCD_FORMAT;
    graphic->info.bits_per_pixel  = OS_GRAPHIC_LCD_DEPTH;
    graphic->info.bytes_per_pixel = OS_GRAPHIC_LCD_DEPTH / 8;
    graphic->info.bytes_per_line  = OS_GRAPHIC_LCD_WIDTH * (OS_GRAPHIC_LCD_DEPTH / 8);

从 Kconfig 宏填充宽高、格式、位深。bytes_per_line = 宽 × 每像素字节数。

数值演算：设 OS_GRAPHIC_LCD_WIDTH = 240、HEIGHT = 240、RGB565（DEPTH = 16）：

计算项代入计算结果
bytes_per_pixel16 / 82
bytes_per_line240 * 2480
framebuffer_size480 * 240115200 字节

第四步：初始化 framebuffer 并注册（无条件执行）

framebuffer 全部清零（双缓冲为空，framebuffer_num = 0），计算 framebuffer_size，注册设备，最后调用 display_on(OS_TRUE) 点亮屏幕（若屏驱动实现了）。

条件走向总结

4.2 os_graphic_add_framebuffer —— 添加帧缓冲

函数签名

os_err_t os_graphic_add_framebuffer(struct os_device *dev, uint8_t *fb, uint32_t size)

参数 / 返回值说明

参数类型说明
devstruct os_device *设备指针
fbuint8_t *帧缓冲内存指针（需调用者分配）
sizeuint32_t帧缓冲大小（必须等于 framebuffer_size）
返回值说明
OS_SUCCESS添加成功
OS_FAILURE已满 2 个缓冲或 size 不匹配

完整源码

分步详解

第一步：断言帧缓冲非空（无条件执行）

    OS_ASSERT(fb != OS_NULL);

第二步：校验数量与大小（条件 framebuffer_num == 2 或 size 不匹配）

    if (info->framebuffer_num == 2)
        return OS_FAILURE;

    // The size must be full screen
    if (size != info->framebuffer_size)
        return OS_FAILURE;

为什么限制 2 个：双缓冲机制最多 2 个（一个绘制、一个刷新）。为什么 size 必须等于 framebuffer_size（整屏）：graphic.c 的 frame_fill/draw_* 函数直接按整屏行数/宽度寻址，若缓冲不满屏会越界。

第三步：清零并登记（无条件执行）

清零新缓冲，登记到 framebuffer[num]，num++；添加第一个缓冲时把它设为当前缓冲 framebuffer_curr。

条件走向总结

os_graphic_add_framebuffer() 条件走向总结：
├── OS_ASSERT(fb != OS_NULL)
├── framebuffer_num == 2（已满）→ 返回 OS_FAILURE
├── size != framebuffer_size（非整屏）→ 返回 OS_FAILURE
├── memset(fb, 0, size)（清零）
├── framebuffer[num] = fb；num++
├── num == 1（第一个）→ framebuffer_curr = fb
├── os_kprintf("Add framebuffer %d")
└── 返回 OS_SUCCESS

4.3 framebuffer 内部辅助函数（os_graphic_frame_next/set/fill）

这三个 static 函数由 os_graphic_control 在 FRAME_* 命令时调用，是双缓冲机制的核心。

完整源码（os_graphic_frame_next / os_graphic_frame_set）

分步详解（os_graphic_frame_next）

第一步：按缓冲数量返回下一个缓冲（条件 framebuffer_num 的值）

    if (graphic->info.framebuffer_num == 2)
        *fb = graphic->info.framebuffer[g_frame_id];
    else if (graphic->info.framebuffer_num == 1)
        *fb = graphic->info.framebuffer[0];
    else
        *fb = OS_NULL;
  • 双缓冲（num==2）：返回 framebuffer[g_frame_id]（g_frame_id 在 FRAME_FLUSH 后翻转，见 4.4）——这样应用拿到的是未在刷新的那个缓冲，可安全绘制；
  • 单缓冲（num==1）：返回 framebuffer[0]；
  • 无缓冲（num==0）：返回 OS_NULL。

分步详解（os_graphic_frame_set）

第一步：设置当前缓冲（条件 fb 非空）

    if (fb)
        graphic->info.framebuffer_curr = fb;

把 framebuffer_curr 指向 fb，后续绘制/填充都写这个缓冲。

完整源码（os_graphic_frame_fill）

分步详解（os_graphic_frame_fill）

第一步：计算目标/源地址偏移（无条件执行）

    uint32_t dst = (uint32_t)info->framebuffer_curr + area->y * graphic->info.bytes_per_line +
                      area->x * graphic->info.bytes_per_pixel;
    uint32_t src        = (uint32_t)area->buffer;
    uint32_t dst_offset = info->bytes_per_pixel * info->width;
    uint32_t src_offset = info->bytes_per_pixel * area->w;

计算目标区域起始地址（framebuffer_curr + y*每行字节 + x*每像素字节），以及行步长。

数值演算：设 RGB565、宽 240，area = {x=10, y=20, w=100, h=50, color=红, buffer=图像}：

计算项代入计算结果
dstframebuffer_curr + 20*480 + 10*2+9620
dst_offset2 * 240480
src_offset2 * 100200

第二步：按"图像数据"填充（条件 src != 0）

    if (src != 0)
    {
        for (i = 0; i < area->h; i++)
        {
            memcpy((void *)dst, (void *)src, src_offset);
            dst += dst_offset;
            src += src_offset;
        }
    }

area->buffer 非空时，逐行 memcpy 图像数据到帧缓冲（每行复制 src_offset 字节，目标按 dst_offset 换行）。

第三步：按"纯色"填充（条件 src == 0）

area->buffer 为空时，逐像素填 area->color 形成色块。最后 os_clean_dcache 清理 D-Cache（保证 DMA/刷屏时数据一致）。

条件走向总结（os_graphic_frame_fill）

os_graphic_frame_fill() 条件走向总结：
├── 计算 dst/src/dst_offset/src_offset
├── src != 0（有图像数据）
│   └── 逐行 memcpy 图像到帧缓冲
├── src == 0（纯色填充）
│   └── 逐像素填 area->color
└── os_clean_dcache(framebuffer_curr, size)

4.4 框架层控制入口（os_graphic_control）

函数签名

static os_err_t os_graphic_control(os_device_t *device, int cmd, void *args)

参数 / 返回值说明

参数类型说明
deviceos_device_t *设备指针
cmdint控制命令（OS_GRAPHIC_CTRL_*，见 3.1）
argsvoid *命令参数指针
返回值说明
OS_SUCCESS命令处理成功
其他DRAW_ADD_FONT/SET_FONT 的返回值

完整源码

分步详解

第一步：电源控制（条件 POWERON/POWEROFF）

调用屏驱动的 display_on 开/关显示。OS_TRUE 开屏、OS_FALSE 关屏。

第二步：获取信息 / 显示区域（条件 GET_INFO/DISP_AREA）

    case OS_GRAPHIC_CTRL_GET_INFO:
        memcpy(args, &graphic->info, sizeof(os_graphic_info_t));
        break;
    case OS_GRAPHIC_CTRL_DISP_AREA:
        if (graphic->ops->display_area)
        {
            graphic->ops->display_area(device, (os_graphic_area_t *)args);
        }
        break;

GET_INFO 把 graphic->info 拷贝到 args（调用者提供 os_graphic_info_t）。DISP_AREA 调用屏驱动把指定区域画到屏幕（无缓冲时绘制走这里）。

第三步：framebuffer 操作（条件 FRAME_*）

  • FRAME_NEXT：返回下一个可绘制的缓冲（args 为 uint8_t **）；
  • FRAME_SET：设置当前缓冲（args 为 uint8_t *）；
  • FRAME_FILL：填充当前缓冲（args 为 os_graphic_area_t *）；
  • FRAME_FLUSH：把当前缓冲刷到屏幕，并翻转 g_frame_id（1 - g_frame_id）实现双缓冲切换。

数值演算（双缓冲翻转）：g_frame_id 初始 0，每次 FRAME_FLUSH 后 1 - g_frame_id：

次数g_frame_id下一次 FRAME_NEXT 返回
初始0framebuffer[0]
1 次 FLUSH 后1framebuffer[1]
2 次 FLUSH 后0framebuffer[0]

第四步：绘制命令（条件 OS_GRAPHIC_DRAW_ENABLE）

#ifdef OS_GRAPHIC_DRAW_ENABLE
    case OS_GRAPHIC_CTRL_DRAW_POINT:
        if (graphic->draw_ops->draw_point)
        {
            graphic->draw_ops->draw_point(graphic, (os_graphic_point_t *)args);
        }
        break;
#endif

OS_GRAPHIC_DRAW_ENABLE 时，绘制命令调用 draw_ops 里对应的绘制函数。以 DRAW_POINT 为例，draw_ops->draw_point 的实现（graphic.c 的 os_graphic_draw_point）在 framebuffer_num > 0 时写帧缓冲，否则退化为 display_area（见 4.3 的说明）。

条件走向总结（os_graphic_control）

4.5 绘制函数库（os_graphic_draw_*）

当 OS_GRAPHIC_DRAW_ENABLE 时，graphic.c 内置一套绘制函数库（draw_ops）。核心思想：有帧缓冲时直接写帧缓冲，无帧缓冲时退化为 display_area 逐区域写屏。

以 os_graphic_draw_point（画点） 为例（分步详解）：

分步详解

第一步：有帧缓冲时直接写显存（条件 framebuffer_num > 0）

    if (graphic->info.framebuffer_num > 0)
    {
        fb = graphic->info.framebuffer_curr;
        OS_ASSERT(fb);
        fb += point->y * graphic->info.bytes_per_line + point->x * graphic->info.bytes_per_pixel;
        *(os_color_t *)fb = point->color;
    }

有帧缓冲：计算像素地址（framebuffer_curr + y*每行字节 + x*每像素字节），直接把颜色写入显存（后续靠 FRAME_FLUSH 统一刷屏）。

数值演算（像素地址）：设 RGB565、宽 240（每行 480 字节），point = {x=10, y=20, color=红}：

计算项代入计算结果
point->y * bytes_per_line20 * 4809600
point->x * bytes_per_pixel10 * 220
偏移9600 + 209620
写入*(os_color_t*)(fb+9620) = 0xF800画红点

第二步：无帧缓冲时退化为显示区域（条件 framebuffer_num == 0）

无帧缓冲：把"点"包装成 1×1 的 os_graphic_area，调 display_area 直接让屏驱动写屏（慢，但无需缓冲）。

再看一个算法型绘制函数：os_graphic_draw_line（Bresenham 直线）完整源码（graphic.c）：

分步详解（os_graphic_draw_line）

第一步：水平线快速路径（条件 line->y1 == line->y2）

水平线（y 相等）直接按行填充：有缓冲时用 pos 指针连续写 len 个像素；无缓冲时包装成 1×len 的 area 调 display_area。返回，不走 Bresenham。

第二步：计算增量与方向（条件：非水平线）

    delta_x = line->x2 - line->x1;
    delta_y = line->y2 - line->y1;
    row     = line->x1;
    col     = line->y1;

row/col 是当前游标（起点），delta_x/delta_y 是总增量。

第三步：决定步进方向（条件 delta_x/delta_y 正负）

    if (delta_x > 0)
        incx = 1;
    else if (delta_x == 0)
        incx = 0;
    else
    {
        incx    = -1;
        delta_x = -delta_x;
    }
  • 增量>0 → incx = 1（向右）；
  • 增量为0 → incx = 0（垂直）；
  • 增量<0 → incx = -1（向左）且 delta_x 取绝对值。
    incy 同理决定 y 方向步进。

第四步：Bresenham 累计误差画线（无条件循环）

distance 取长轴（delta_x 与 delta_y 较大者），决定循环次数。每步把当前 (row, col) 画一个点，然后用"累计误差"（xerr/yerr 累加长轴增量）判断是否沿短轴进一位——这正是 Bresenham 用整数运算避免浮点除法的核心。

数值演算（Bresenham）：设 line = {x1=0, y1=0, x2=4, y2=2}，则 delta_x=4、delta_y=2、distance=4、incx=1、incy=1。循环体顺序为先画点、再累加 xerr/yerr、最后判断进退：

迭代画点 (row,col)xerr 累加后yerr 累加后xerr>4?yerr>4?下一轮 (row,col)
初始—————(0,0)
i=0(0,0)0+4=40+2=2否否(0,0)
i=1(0,0)4+4=82+2=4是→xerr=4,row=1否(1,0)
i=2(1,0)4+4=84+2=6是→xerr=4,row=2是→yerr=2,col=1(2,1)
i=3(2,1)4+4=82+2=4是→xerr=4,row=3否(3,1)
i=4(3,1)4+4=84+2=6是→xerr=4,row=4是→yerr=2,col=2(4,2)
i=5(4,2)4+4=82+2=4是→xerr=4,row=5否(5,2)

画出的点序列为 (0,0), (1,0), (2,1), (3,1), (4,2)（i=0 与 i=1 都落在起点 (0,0)）。整体沿长轴 x 每步进 1，短轴 y 在误差累积到 distance=4 时才进 1，最终形成从 (0,0) 到 (4,2)、斜率为 1/2 的直线。

说明：draw_circle（中点圆）、draw_rect（4 条直线）、draw_solid_*（逐行填充）、draw_char/draw_string（逐位字形点阵）等结构与上述两例类似，核心统一遵循"有缓冲直接写显存、无缓冲退化 display_area"的双路径设计，此处不再逐一展开。

五、使用示例

以下示例基于项目头文件 drivers/graphic/graphic.h 的接口，均含返回值检查。

示例 1：初始化 LCD 并点亮

实际效果：打开 "lcd" 后，os_device_control(dev, OS_GRAPHIC_CTRL_POWERON, OS_NULL) 调屏驱动的 display_on(OS_TRUE) 点亮屏幕。

示例 2：获取显示信息

实际效果：os_device_control(dev, OS_GRAPHIC_CTRL_GET_INFO, &info) 把 graphic->info 拷贝到 info，打印分辨率、格式、位深、行字节数、帧缓冲信息。

示例 3：双缓冲绘制与刷屏（防撕裂）

实际效果：分配帧缓冲 → FRAME_SET 设置当前缓冲 → FRAME_FILL 画红色实心矩形到缓冲 → FRAME_FLUSH 刷到屏幕。通过"先画缓冲再刷屏"避免逐像素刷新的闪烁。

示例 4：绘制文字（需启用绘制函数库）

实际效果：设置光标到 (0,0)、文字颜色白色，DRAW_STRING 绘制 "OneOS GUI"，FRAME_FLUSH 刷屏。注意：绘制文字前需先通过 DRAW_ADD_FONT 添加字体并 DRAW_SET_FONT 设置（本示例未包含字体添加，实际使用需配合字体数据）。

示例 5：清屏

实际效果：DRAW_CLEAR 用 OS_COLOR_BLACK 填充整屏为黑色，FRAME_FLUSH 刷屏显示全黑。

六、更换 LCD 屏（Graphic 驱动移植）—— 全局视角

本节从全局视角讲解：当你要换一块 LCD 屏（或换 MCU 导致屏驱动失效）时，OneOS 的 Graphic 驱动要做什么才能在新屏上跑起来。核心结论与 5.2~5.33 一致：应用层与框架层完全不用动，只需要新写/移植 BSP 屏驱动。

6.1 认识 BSP 层驱动：ili9341.c / st7789vw.c 等

BSP 层屏驱动位于 drivers/graphic/，每块屏一个 .c 文件（ili9341.c、st7789vw.c、otm8009a.c、ht240s030.c、atk_tflcd9341.c）。以 ILI9341（drivers/graphic/ili9341.c）为例，它实现了 struct os_graphic_ops：

static const struct os_graphic_ops ili9341_ops = {
    .display_on    = lcd_display_on,
    .frame_flush   = lcd_framebuffer_flush,
    .display_area  = lcd_display_area,
};
  • lcd_display_on：控制背光/显存开关；
  • lcd_framebuffer_flush：把 framebuffer 数据整体刷到 LCD（发 ILI9341 的写显存命令 + 传输数据）；
  • lcd_display_area：把指定区域写到 LCD（无缓冲模式用）。

init 注册（屏驱动初始化时调用）：

os_graphic_t *graphic = os_calloc(1, sizeof(os_graphic_t));
graphic->ops = &ili9341_ops;
os_graphic_register("lcd", graphic);

（1）"根据所选 LCD 屏决定"到底是怎么决定的？—— 三层选择机制

Graphic 驱动同样通过 Kconfig + weave.yaml 只编译所选屏的驱动：

第一层：Kconfig 选择屏型号（drivers/graphic/Kconfig，见 3.3）——如勾选 BSP_USING_ILI9341、OS_USING_ST7789VW、OS_USING_HT240S030 等。

第二层：weave.yaml 条件编译（drivers/graphic/weave.yaml）：

graphic.c（框架层）由 OS_USING_GRAPHIC 控制必编译；每块屏的 .c 由各自的宏控制。每块屏驱动平级、各按自己的宏条件编译——这正是"每个屏驱动平级实现、各自条件编译"的体现。

6.2 移植前的全局视角：分层全景图

回顾 Graphic 设备的完整分层（本书 1.1 节已详解）：应用层 → Graphic 框架层（graphic.c）→ BSP 屏驱动（ili9341.c 等）→ 硬件层。

移植的关键洞察：

  • 只有 BSP 屏驱动和具体屏强相关（依赖屏的寄存器命令、接口 SPI/I2C/DSI、背光/电源引脚）。
  • 框架层和应用层与具体屏无关（只依赖 graphic.h 定义的抽象接口）。
  • 所以"换 LCD 屏"本质上 = 新写/移植一个 BSP 屏驱动（实现 struct os_graphic_ops 三个函数 + init 注册）。

6.3 移植需要提供的"接口契约"

要移植，必须先满足 BSP 层与框架层之间的契约——也就是 struct os_graphic_ops 的三个核心函数（见 2.4 节）：

ops 函数需实现的能力新屏上对应什么
display_on开/关显示（背光/显存）拉高/拉低背光引脚、使能/失能显存
frame_flush把 framebuffer 整体刷到屏发"写显存"命令 + 传输整屏数据（SPI/I2C/DSI）
display_area把指定区域写到屏设置窗口（set_column/set_page）+ 写区域数据

此外还需要：

  1. 屏初始化序列：上电时发送屏的初始化寄存器序列（如 ILI9341 的 0x36 方向、0x2A/0x2B 窗口、0x29 开显示等）。
  2. 像素格式匹配：屏实际支持的像素格式必须与 Kconfig 的 OS_GRAPHIC_LCD_FORMAT_* 一致（否则颜色错乱）。
  3. 通信接口：通过 SPI/I2C/DSI 操作屏寄存器（若走 SPI，参考 5.5 SPI 设备）。

6.4 移植的标准流程（5 步）

以"为一块 SPI 接口的 LCD 屏写 Graphic 驱动"为例：

第 1 步：实现屏驱动 ops 的三个函数

第 2 步：定义并导出 ops 表

static const struct os_graphic_ops my_lcd_ops = {
    .display_on    = my_lcd_display_on,
    .frame_flush   = my_lcd_framebuffer_flush,
    .display_area  = my_lcd_display_area,
};

第 3 步：写 init 并注册

第 4 步：配置像素格式与宽高（Kconfig）

确保 OS_GRAPHIC_LCD_WIDTH/HEIGHT 与屏一致、OS_GRAPHIC_LCD_FORMAT_* 与屏支持格式一致。

第 5 步：验证

用本节"示例 2（获取信息）"确认宽高/格式正确，用"示例 3（画矩形刷屏）"确认 frame_flush 正常，用"示例 4（画文字）"确认绘制函数库正常。若颜色错乱，检查 OS_GRAPHIC_LCD_FORMAT_* 与屏实际格式。

6.5 移植检查清单（快速自查）

检查项是否满足
struct os_graphic_ops 的 display_on/frame_flush/display_area 已实现并绑定☐
屏初始化序列正确（方向/窗口/开显示命令）☐
OS_GRAPHIC_LCD_FORMAT_* 与屏实际像素格式一致☐
os_graphic_register 前已填充 ops☐
新屏已在 weave.yaml 加条件编译、Kconfig 加选择项☐
frame_flush 能正确刷整屏（含 D-Cache 一致性）☐
无缓冲时 display_area 能正常显示☐

6.6 移植的价值与注意事项

价值：一旦 BSP 屏驱动移植完成，应用层代码一行不改即可在不同 LCD 屏（ILI9341/ST7789VW/OTM8009A 等）间复用。

注意事项：

  • 像素格式必须匹配：os_color_t 类型由 OS_GRAPHIC_LCD_FORMAT_* 决定，若与屏实际格式不符，颜色错乱。
  • D-Cache 一致性：刷屏涉及 DMA/CPU 访问 framebuffer，需 os_clean_dcache（graphic.c 的 frame_fill 已做）。
  • 整屏缓冲大小：os_graphic_add_framebuffer 要求 size == framebuffer_size（整屏），别用局部小缓冲。

📝 本节小结

核心要点回顾

  1. 分层抽象设计：Graphic 设备基于 5.1 框架，os_graphic_device 内嵌 os_device，通过 os_graphic_ops 与具体屏驱动解耦；os_device_ops 只有 .control，无 read/write。
  2. 双缓冲机制：framebuffer[2] + FRAME_NEXT/FRAME_SET/FRAME_FILL/FRAME_FLUSH 实现无撕裂刷屏，g_frame_id 每次 FLUSH 翻转。
  3. 颜色格式：os_color_t 由 OS_GRAPHIC_LCD_FORMAT_* 决定（RGB565/RGB888/ARGB8888），OS_COLOR 宏自动做位域转换。
  4. 绘制函数库：OS_GRAPHIC_DRAW_ENABLE 时内置 draw_ops（点/线/矩形/圆/文字），有缓冲写显存、无缓冲退化 display_area。
  5. 注册流程：os_graphic_register 配置设备类型/ops、填充 info、清空 framebuffer、注册设备并点亮屏幕。
  6. 控制命令：os_graphic_control 分发电源/信息/区域/framebuffer/绘制命令，DRAW_* 和 GPU_* 命令受编译宏控制。
  7. 更换 LCD 屏移植（见第六章）：移植核心 = 实现 struct os_graphic_ops 三个函数 + init 注册；应用层与框架层不用改；换屏本质是换 weave.yaml 选择的那个屏驱动 .c。

关键易错点速查

易错点正确做法
期望 Graphic 设备用 os_device_read/writeos_graphic_ops 只有 .control，所有操作走 os_device_control
os_graphic_add_framebuffer 传局部小缓冲要求 size == framebuffer_size（整屏）→ 分配整屏大小
像素格式不匹配OS_GRAPHIC_LCD_FORMAT_* 必须与屏实际格式一致 → 否则颜色错乱
绘制前未加缓冲就用 FRAME_FILLframebuffer_num == 0 时绘制退化写屏，但 FRAME_FLUSH 无缓冲无效 → 先 add_framebuffer
画文字前没设置字体DRAW_STRING 依赖已 ADD_FONT/SET_FONT → 先添加并设置字体
双缓冲绘制后忘了 FRAME_FLUSH绘制只写内存，不刷屏看不到 → 必须 FRAME_FLUSH
移植屏驱动没匹配像素格式颜色错乱 → configure 阶段核对 OS_GRAPHIC_LCD_FORMAT_*
刷屏没做 D-Cache 清理DMA/CPU 数据不一致 → graphic.c 已用 os_clean_dcache，移植时勿删

下一步

  • 5.35 WLAN设备：了解 OneOS WLAN 无线设备的 STA/AP 模式、扫描/加入网络、事件回调与数据收发。
OneOS-Lite 文档 | 学习阁
Copyright © 2026 学习阁