第 5 章 - GUIX 显示驱动程序
GUIX 显示驱动程序定义抽象绘图画布和物理显示硬件之间的软件接口。 GUIX 显示驱动程序实现了最低级别的绘图函数，这些函数实际上会更改画布内存中的像素颜色信息，并将画布内存传输到双缓冲系统中的物理显示帧缓冲区。
GUIX 显示驱动程序由包含物理显示参数和指向低级别驱动程序函数的一组函数指针的结构定义。 通过使用这些间接函数指针，抽象画布和小组件绘图函数可以完全独立于硬件详细信息。
GUIX 为每种支持的颜色深度和颜色格式提供了一组完整的、功能齐全的默认绘图函数。 实现没有特定硬件加速功能或其他硬件特定注意事项的显示驱动程序时，这些默认的绘图函数通常足以最终实现驱动程序。 对于这些最简单的驱动程序，通常需要在驱动程序软件中实现的唯一函数是用于配置硬件设备的函数。 这通常涉及初始化各种硬件寄存器，以定义 LCD 显示时钟、显示尺寸等。对于所有其他函数，驱动程序实现只需初始化 GX_DISPLAY 函数指针，指向所需颜色深度和格式的默认函数实现。
实现自定义显示驱动程序时，最佳做法是首先使用要支持的颜色深度的默认软件实现来初始化显示驱动程序绘图函数指针，然后在需要调用自定义函数实现的地方替换这些函数指针（若有）。 为了帮助实现这一点，有一个默认的设置函数可用于每种支持的颜色深度和格式。 例如，如果你要编写一个 16 位 5:6:5 格式 RGB 显示驱动程序，则自定义驱动程序通常要执行的第一项操作就是为此颜色深度调用通用设置例程：
UINT my_custom_565_display_driver(GX_DISPLAY *display)
{
/* Perform standard function pointer setup. */
_gx_display_driver_565rgb_setup(display, GX_NULL, my_buffertoggle);
}
上面的参数 my_buffer_toggle 是指向显示驱动程序缓冲区切换函数的指针（如果驱动程序为单缓冲且直接绘制到硬件帧缓冲区，则可能是 GX_NULL）。
如果要编写自定义显示驱动程序，则需要在自定义驱动程序源中包含 gx_display.h 头文件，该文件是内部使用头文件，不适用于应用程序级软件。
GUIX 显示级绘图函数接收指向 GX_DRAW_CONTEXT 结构的指针作为输入。 GX_DRAW_CONTEXT 结构定义当前绘图操作的剪裁坐标以及所使用的画笔和颜色。 每个绘图函数都接收特定于函数要求的其他参数作为输入。
GX_DISPLAY 驱动程序入口点的签名定义为
UINT <device>_graphics_driver_<format>(GX_DISPLAY *diplay)
虽然此函数的名称完全由实现者决定，但 GUIX 提供的驱动程序的约定是在“设备”字段中使用特定于硬件的设备名称，在上面的“格式”字段中使用颜色格式。<><>
此函数必须初始化作为输入提供的 GX_DISPLAY 结构，并执行所需的任何硬件设置。 GX_DISPLAY 结构包含下列字段。
| 字段 | 说明 |
|---|---|
| ULONG gx_display_id | 如果创建了特定驱动程序的多个实例，则该字段供应用程序使用。 |
| CHAR *gx_display_name | 用于标识驱动程序的可选名称。 |
| GX_DISPLAY *gx_display_created_next | 该字段由 GUIX 初始化，用于创建和维护所有 GX_DISPLAY 实例的列表。 |
| GX_DISPLAY *gx_display_created_previous | 该字段由 GUIX 初始化，用于创建和维护所有 GX_DISPLAY 实例的列表。 |
| GX_VALUE gx_display_color_format | 该字段应反映此驱动程序支持的图形数据格式。 颜色格式类型是在 gx_api.h 头文件中定义的。 |
| GX_VALUE gx_display_width | 应将此字段初始化为保持物理显示宽度（以像素为单位）。 |
| GX_VALUE gx_display_height | 应将此字段初始化为保持物理显示高度（以像素为单位）。 |
| GX_COLOR *gx_display_color_table | 这是指向用于将颜色 ID 值转换为颜色格式特定颜色值的表的指针。 |
| GX_PIXELMAP *gx_display_pixelmap_table | 这是指向此显示的活动像素图表的指针。 |
| GX_FONT *gx_display_font_table | 这是指向此显示的活动字体表的指针。 |
| GX_COLOR *gx_display_palette | 对于调色板模式驱动程序，这是指向活动调色板的指针。 对于不使用调色板的驱动程序，该指针为 GX_NULL。 |
| UINT gx_display_pixelmap_table_size | 活动像素图表中的条目数。 |
| UINT gx_display_font_table_size | 活动字体表中的条目数。 |
| UINT gx_display_palette_size | 调色板中的条目数（如果有）。 |
| ULONG gx_display_handle | 指定显示内容的唯一标识符或句柄。 |
| UINT gx_display_driver_ready | 当驱动程序准备好进行操作时，此字段用于向 GUIX 发出信号。 在某些情况下，驱动程序可能需要若干级别的初始化和配置，在此期间，GUIX 不得尝试使用该驱动程序。 当驱动程序准备好处理绘制请求时，应将此标志设置为 1。 |
| VOID *gx_display_driver_data | 此字段供驱动程序实现使用。 如果驱动程序需要创建和引用 GX_DISPLAY 结构中不可用的附加信息，则驱动程序应使用此结构字段为此附加数据分配空间并指向此附加数据。 特定于驱动程序的额外数据的示例可能包括由驱动程序使用的 DMA 通道或显示帧缓冲区连接到的 SPI 通道。 |
| VOID (*gx_display_driver_drawing_initiate)(struct GX_DISPLAY_STRUCT *display, struct GX_CANVAS_STRUCT *canvas) | 这是一个函数指针，如果不为 NULL，则由 gx_canvas_drawing_initiate 函数调用。 对于使用图形加速器或硬件图形显示列表的显示驱动程序，此函数可用于开始新的显示列表。 此函数指针可以为 NULL。 |
| VOID (*gx_display_driver_palette_set)(struct GX_DISPLAY_STRUCT *display, GX_COLOR *palette, INT count) | 这是指向用于安装调色板的函数的指针。 除非驱动程序在调色板（也称为颜色查找表或 CLUT）模式下运行，否则此函数为 NULL。 |
| VOID (*gx_display_driver_simple_line_draw)(GX_DRAW_CONTECT *context, INT x1, INTy1, INT x2, INT y2) | 这是指向用于实现一般线条绘制（无抗锯齿）的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_simple_wide_line_draw)(GX_DRAW_CONTECT *context, INT x1, INTy1, INT x2, INT y2) | 这是指向用于实现一般宽线条绘制（无抗锯齿）的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_anti_aliased_line_draw)(GX_DRAW_CONTECT *context, INT x1, INTy1, INT x2, INT y2) | 这是指向用于实现一般抗锯齿线条绘制的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_anti_aliased_wide_line_draw)(GX_DRAW_CONTECT *context, INT x1, INTy1, INT x2, INT y2) | 这是指向用于实现一般抗锯齿宽线条绘制的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_horizonal_line_draw)(GX_DRAW_CONTECT *context, INT x1, INT x2, INT y) | 这是一个用于实现水平线绘制的特殊情况的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_horizonal_pixelmap_line_draw)(GX_DRAW_CONTECT *context, INT x1, INT x2, INT y, GX_PIXELMAP *map) | 这是指向用于实现单个像素图行绘制的函数的指针。 此函数在内部用于模式填充形状。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_vertical_line_draw)(GX_DRAW_CONTECT *context, INT y1, INT y2, INT x) | 这是一个用于实现水平线绘制的特殊情况的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_horizonal_pattern_line_draw)(GX_DRAW_CONTECT *context, INT x1, INT x2, INT y) | 这是指向用于实现水平模式线条绘制的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_vertical_pattern_line_draw)(GX_DRAW_CONTECT *context, INT y1, INT y2, INT x) | 这是指向用于实现垂直模式线条绘制的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_canvas_copy)(struct GX_CANVAS_STRUCT *source, struct GX_CANVAS_STRUCT *dest) | 这是指向用于将画布数据从一个画布复制到另一个画布的函数的指针。 源画布无效矩形用于定义复制区域。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_canvas_blend)(struct GX_CANVAS_STRUCT *source, struct GX_CANVAS_STRUCT *dest) | 这是指向用于将源画布中的画布数据与目标画布中的现有数据进行 alpha 混合的函数的指针。 源画布无效矩形用于定义混合区域。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_pixelmap_blend)(GX_DRAW_CONTEXT *context, INT xpos, INT ypos, GX_PIXELMAP *pmp, GX_UBYTE alpha) | 这是指向用于在绘图上下文定义的背景画布上混合像素图的函数的指针。 所提供的 Alpha 值可以是像素图数据中包含的 alpha 通道的补充。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_pixelmap_draw)(GX_DRAW_CONTEXT *context, INT xpos, INT ypos, GX_PIXELMAP *pmp) | 这是指向用于在绘图上下文定义的画布上绘制像素图的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_jpeg_draw)(GX_DRAW_CONTEXT *context, INT xpos, INT ypos, GX_PIXELMAP *pmp) | 这是指向用于解码 jpg 图像并直接呈现到画布上的函数的指针。 仅当定义了 GX_SOFTWARE_DECODER_SUPPORT 时才提供此函数。 此函数指针可以为 NULL。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_png_draw)(GX_DRAW_CONTEXT *context, INT xpos, INT ypos, GX_PIXELMAP *pmp) | 这是指向用于解码 png 图像并直接呈现到画布上的函数的指针。 仅当定义了 GX_SOFTWARE_DECODER_SUPPORT 时才提供此函数。 此函数指针可以为 NULL。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_pixelmap_rotate)(GX_DRAW_CONTEXT *context, INT xpos, INT ypos, GX_PIXELMAP *pmp INT angle, INT rot_cx, INT rot_cy) | 这是指向函数的指针，用于旋转像素图并将结果直接呈现到画布上。 此函数由 gx_canvas_pixelmap_rotate API 为每种支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID *gx_display_driver_pixel_write)(GX_DRAW_CONTEXT *context, INT x, INT y, GX_COLOR color) | 这是指向用于将一个像素写入画布内存的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID *gx_display_driver_block_move) (GX_DRAW_CONTEXT *context， GX_RECTANGLE *block， INT xshift， INT yshift) | 这是指向用于在画布中移动像素块的函数的指针。 此函数主要用于快速滚动窗口内容。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_pixel_blend)(GX_DRAW_CONTEXT *context, INT x, INT y, GX_COLOR color, GX_UBYTE alpha) | 此函数用于将传入的像素颜色值与画布内存中 x、y 位置上的现有颜色值进行 alpha 混合。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| GX_COLOR (*gx_display_driver_native_color_get)(GX_COLOR rawcolor) | 此函数将颜色从 GUIX 内部使用的 32 位 A:R:G:B 颜色格式转换为画布和显示的本机颜色格式。 对于在较低颜色深度运行的显示驱动程序，可能会丢失一些颜色信息。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| USHORT (*gx_display_driver_row_pitch_get)(USHORT width) | 返回给定所请求画布宽度的一行图形数据的字节计数或步幅。 此函数用于计算创建画布所需的内存区域的大小。 由于硬件扫描线对齐的限制，行间距和宽度并不总是相同的。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_buffer_toggle)(struct GX_CANVAS_STRUCT *canvas, GX_RECTANGLE *dirty_area) | 这是指向用于在双缓冲内存系统的工作帧缓冲区和可见帧缓冲区之间切换的函数的指针。 此函数必须首先指示硬件开始使用新的帧缓冲区，然后将新的可见缓冲区的修改部分复制到配套缓冲区，以确保两个缓冲区保持同步。 |
| VOID (*gx_display_driver_polygon_draw)(GX_DRAW_CONTEXT *context, INT num_points, GX_POINT *vertices | 指向用于绘制多边形的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_polygon_fill)(GX_DRAW_CONTEXT *context, INT num_points, GX_POINT *vertices | 指向用于绘制实心多边形的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_circle_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r) | 指向用于绘制圆形的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_anti_aliased_circle_draw) (GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r) | 指向用于绘制抗锯齿圆形的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_wide_circle_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r) | 指向用于绘制宽轮廓圆形的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_wide_anti_aliased_circle_draw) (GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r) | 指向用于绘制宽轮廓抗锯齿圆形的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_circle_fill)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r) | 指向用于绘制实心圆的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_arc_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r, INT start_angle, INT end_angle) | 指向用于绘制圆弧的函数的指针。为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_anti_aliased_arc_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r, INT start_angle, INTend_angle) | 指向用于绘制抗锯齿圆弧的函数的指针。为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_wide_arc_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r, INT start_angle, INT end_angle) | 指向用于绘制宽轮廓圆弧的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_anti_aliased_wide_arc_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r, INT start_angle, INTend_angle) | 指向用于绘制抗锯齿圆弧的函数的指针。为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_arc_fill)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r, INT start_angle, INT end_angle) | 指向用于绘制实心圆弧的函数的指针。为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_pie_fill)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r, INT start_angle, INT end_angle) | 指向用于绘制实心饼图的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_ellipse_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, INT a, INT b) | 指向用于绘制椭圆的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_anti_aliased_ellipse_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, INT a, INT b) | 指向用于绘制椭圆的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_wide_ellipse_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, INT a, INT b) | 指向用于绘制宽轮廓椭圆的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_anti_aliased_wide_ellipse_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, INT a, INT b) | 指向用于绘制宽轮廓椭圆的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_ellipse_fill)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, INT a, INT b) | 指向用于绘制实心椭圆的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_8bit_glyph_draw)(GX_DRAW_CONTEXT *context, GX_RECTANGLE *draw_area, GX_POINT *map_offset, constGX_GLYPH *glyph) | 指向用于使用当前绘图上下文的笔刷在画布上绘制一个 8 位锯齿文字字形的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_4bit_glyph_draw)(GX_DRAW_CONTEXT *context, GX_RECTANGLE *draw_area, GX_POINT *map_offset, const GX_GLYPH *glyph) | 指向用于使用当前绘图上下文的笔刷在画布上绘制一个 4 位锯齿文字字形的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |
| VOID (*gx_display_driver_1bit_glyph_draw)(GX_DRAW_CONTEXT *context, GX_RECTANGLE *draw_area, GX_POINT *map_offset, const GX_GLYPH *glyph) | 指向用于使用当前绘图上下文的笔刷在画布上绘制一个 1 位单色文字字形的函数的指针。 为每个支持的颜色深度和颜色格式提供此函数的默认实现。 |