DJYGUI系列文章五：GK显示器接口

1 GK显示器接口概述

        显示器是图形显示的终端，图形的所有操作都会直接或间接的体现在显示器上面。DJYGUI支持多显示器、虚显示器和镜像显示器的功能。应用程序在调用API函数绘图前，需安装显示器，按照GK显示器标接口实现驱动函数。

        GK的底层硬件标准接口函数大体分为三类，第一类是在位图中绘图，第二类是在屏幕上绘图，第三类是显示器的控制函数。安装显示器时，将这三类接口函数注册到图形系统，当用户调用GUI Kernel API时，这些驱动函数将以回调函数的方式被调用。

2 镜像显示

        镜像显示就是在远端计算机上显示一个与本地显示器完全一样的画面，可用于实现远程协助和远程维护。远程操作多是通过通信口进行的，主要有网络、USB、串口等。要使用远程显示功能，必须在本地先安装一个显示器，然后把远程显示器当作该显示器的镜像显示器，GK提供API函数用于添加镜像显示器。值得注意的是，本地显示器可以是实际存在的，也可以是虚拟的。对于实际存在的显示器，需要编写完整的显示driver，对于虚拟的，则只需要提供一个框架，driver接口中要求的接口函数，均可以不实现。与本地显示器一样，镜像显示器同样需要在本地实现一个display驱动，但不必实现所有接口函数，只需要实现显示器接口函数集中的四个函数：

1. set_pixel_screen：在屏幕上绘制一个像素
2. fill_rect_screen：填充一块矩形屏幕区域
3. bm_to_screen：把bitmap输出到屏幕
4. line_screnn：在屏幕上面画一根线

        所有的绘制操作，最后都会在GK中变成对screen的输出操作，GK在执行对screen操作的同时，调用上述四个函数之一，把绘制命令传送到远端显示器，远端计算机在自己的本地显示器上实现这几个函数的功能。镜像显示器驱动还需要图像传输协议的配合，典型的是VNCServer，该协议在DJYOS上有移植。使用VNCServer的话，远端显示器只需要安装一个VNC客户端就可以了。

3 硬件接口

3.1set_pixel_bm：位图中画像素

bool_t (*set_pixel_bm)(struct tagRectBitmap *Bitmap, s32 x,s32 y,u32 Color,u32 Rop2Code);

参数：

Bitmap：目标位图。

x：绘图位置的横坐标，相对于位图。

y：绘图位置的纵坐标，相对于位图。

Color：画图使用的颜色，颜色格式为真彩色。

Rop2Code：二元光栅操作码。

返回值：

true：成功；false：失败。

说明：

在矩形位图中画一个像素，若显示器使用CN_CUSTOM_PF（自定义）格式，或者有硬件加速功能，应该实现这个函数，否则直接返回false。即使有硬件加速，但该加速功能不支持r2_code编码的话，也返回false。color的格式是CN_SYS_PF_ERGB8888。

3.2 line_bm：位图中画直线

bool_t (*line_bm)(struct tagRectBitmap *Bitmap,struct tagRectangle *Limit,

s32 x1,s32 y1,s32 x2,s32 y2,u32 Color,u32 Rop2Code);

参数：

Bitmap：目标位图。

Limit：限制矩形，只允许在该矩形内绘制。

x1：绘图起点的横坐标，相对于位图。

y1：绘图起点的纵坐标，相对于位图。

x2：绘图终点的横坐标，相对于位图。

y2：绘图终点的纵坐标，相对于位图。

Color：画图使用的颜色，颜色格式为真彩色。

Rop2Code：二元光栅操作码。

返回值：

true：成功；false：失败。

说明：

在矩形位图中画一条任意细直线，不含端点，若显示器使用CN_CUSTOM_PF（自定义）格式，或者有硬件加速功能，应该实现这个函数，否则直接返回false。即使有硬件加速，但该加速功能不支持r2_code编码的话，也返回false。color格式是CN_SYS_PF_ERGB8888。

另外有公交车中画直线函数line_bm_ie，与line_bm的唯一区别在于，line_bm_ie画直线包括端点，而line_bm不包含端点。

3.3fill_rect_bm：位图中填充矩形

bool_t (*fill_rect_bm)(struct tagRectBitmap *DstBitmap,

                               struct tagRectangle *Target,

                               struct tagRectangle *Focus,

                               u32 Color0,u32 Color1,u32 Mode);

参数：

DstBitmap：目标位图。

Target：目标矩形，填充范围不能超过该矩形。

Focus：聚焦矩形，当前填充矩形区域。

Color0：渐变颜色0，颜色格式为真彩色。

Color1：渐变颜色1，颜色格式为真彩色，模式为直接填充时无效。

Mode：填充模式，请参照gkernel.h宏定义组CN_FILLRECT_MODE_N。

返回值：

true：成功；false：失败。

说明：

在矩形位图中填充矩形，若显示器使用CN_CUSTOM_PF（自定义）格式，或者有硬件加速功能，应该实现这个函数，否则直接返回false。color格式是CN_SYS_PF_ERGB8888。目标矩形Target是渐变填充的整个矩形区域，聚焦矩形Focus是当前填充的可视域。Target和Focus的关系如图 41所示。如需要填充Target内的三个focus区域，需要调用该函数三次，每次使用相应的Focus参数。

图 4-1 Target和Focus关系图

3.4 blt_bm_to_bm：位图中显示矩形

bool_t (*blt_bm_to_bm)( struct tagRectBitmap *DstBitmap,

                                   struct tagRectangle *DstRect,

                                   struct tagRectBitmap *SrcBitmap,

                                   struct tagRectangle *SrcRect,

                                   u32 RopCode,u32 TransparentColor);

参数：

DstBitmap：目标位图。

DstRect：目标矩形。

SrcBitmap：源位图。

SrcRect：源矩形。

RopCode：光栅操作码。

TransparentColor：透明色，为真彩色。

返回值：

true：成功；false：失败。

说明：

在两个矩形位图中位图块传送，如果显示器使用的像素格式是CN_CUSTOM_PF，或者硬件2d加速支持位图块传送，需实现这个函数，否则直接返回false。对于有硬件加速，但部分RopCode编码不支持的情况，可以实现支持的RopCode，不支持的部分，返回false。本函数返回false的话，gui kernel会自行用逐像素方法拷贝。目标矩形和源矩形相对坐标不同，但大小相同。

3.5 get_pixel_bm：位图中读取像素

u32 (*get_pixel_bm)(struct tagRectBitmap *Bitmap,s32 x,s32 y);

参数：

Bitmap：目标位图。

x：读像素的横坐标，相对于目标位图。

y：读像素的纵坐标，相对于目标位图。

返回值：

读取的像素值，需转化为真彩色。

说明：

从矩形位图中取一像素，并转换成CN_SYS_PF_ERGB888。只有在bitmap的像素格式为CN_CUSTOM_PF时，才需要读取。如果显卡不打算支持自定义格式，本函数直接返回0。

3.6 get_rect_bm：位图中剪切矩形

bool_t (*get_rect_bm)(struct tagRectBitmap

*Src, struct tagRectangle *Rect, struct tagRectBitmap *Dest);

参数：

Src：源位图。

Rec：读取位图的矩形区域。

Dest：目标位图。

返回值：

true：成功；false：失败。

说明：

把src位图内rect矩形区域的内容复制到dest位图中，调用前，先设置好dest的FixelFormat，本函数不理会src的FixelFormat，直接使用screen的格式。本函数用于从窗口剪切矩形，而blt_bm_to_bm用于显示矩形。如果显示器使用的像素格式是CN_CUSTOM_PF，或者硬件加速支持位图间拷贝图形，需实现这个函数，否则直接返回false。由于dest->FixelFormat存在很多可能，即使有硬件加速，也存在只支持部分FixelFormat的情况，对不支持的格式，返回false。

3.7 set_pixel_screen：屏幕上画像素

bool_t (*set_pixel_screen)(s32 x,s32 y,u32 Color,u32 Rop2Code);

参数：

x：绘制像素的横坐标，相对于屏幕。

y：绘制像素的纵坐标，相对于屏幕。

Color：绘制像素的颜色，为真彩色。

Rop2Code：二元光栅操作码。

返回值：

true：成功；false：失败。

说明：

在screen中画一个像素，有frame buffer的情况下，正常显示gui不会调用这个函数，如果窗口direct_screen==true，则可能调用本函数。因此，无论是否有frame buffer，driver都必须提供并且必须实现本函数。镜像显示器的driver必须实现本函数。color的格式是CN_SYS_PF_ERGB8888，因此绘制前需转化为本地颜色格式。

3.8 line_screen：屏幕上画直线

bool_t (*line_screen)( tagRectangle *limit, s32 x1,s32 y1,s32 x2,s32 y2,

u32 Color,u32 Rop2Code);

参数：

limit：限制矩形，只绘制矩形内部的部分。

x1：绘图起点横坐标，相对于屏幕。

y1：绘图起点纵坐标，相对于屏幕。

x2：绘图终点横坐标，相对于屏幕。

y2：绘图终点横坐标，相对于屏幕。

Color：绘制像素的颜色，为真彩色，因此绘制前需转化为本地颜色格式。

Rop2Code：二元光栅操作码。

返回值：

true：成功；false：失败。

说明：

在screen中画一条任意直线，不含端点，如硬件加速不支持在screen上画线，driver可以简化，直接返回false即可。有frame buffer的情况下，正常显示gui不会调用这个函数，如果窗口direct_screen==true，则可能调用本函数，本函数返回false的话，会进一步调用set_pixel_screen函数。由于不确定本地显示器是否有frame_buffer，镜像显示器driver必须实现本函数，不能简单返回false。color的格式是CN_SYS_PF_ERGB8888，因此绘制前需转化为本地颜色格式。

此外，函数line_screen_ie也是在屏幕上画直线，但是它画的直线包含端点。

3.9 fill_rect_screen：屏幕上填充矩形

bool_t (*fill_rect_screen)(struct tagRectangle *Target,

                              struct tagRectangle *Focus,

                              u32 Color0,u32 Color1,u32 Mode);

参数：

Target：目标矩形区域。

Focus：聚焦矩形区域。

Color0：渐变颜色0，颜色格式为真彩色。

Color1：渐变颜色1，颜色格式为真彩色。

Mode：渐变填充模式。

返回值：

true：成功；false：失败。

说明：

screen中矩形填充，如硬件加速不支持在screen上矩形填充，driver可以简化，直接返回false即可。有frame buffer的情况下，正常显示gui不会调用这个函数，如果窗口direct_screen==true，则可能调用本函数，本函数返回false的话，会进一步调用set_pixel_screen函数。由于不知道本地显示器的情况，镜像显示器driver必须实现本函数，不能简单返回false。color的格式是CN_SYS_PF_ERGB8888。Target与Focus的关系如图 41所示。

3.10 bm_to_screen：屏幕上画位图

bool_t (*bm_to_screen)(struct tagRectangle *DstRect,

                    struct tagRectBitmap *SrcBitmap,s32 xSrc,s32 ySrc);

参数：

DstRect：目标矩形区域。

SrcBitmap：源位图。

xSrc：源位图中显示的区域左上角横坐标，相对于源位图。

ySrc：源位图中显示的区域左上角纵坐标，相对于源位图。

返回值：

true：成功；false：失败。

说明：

从内存缓冲区到screen位块传送，只支持块拷贝，不支持rop操作。如硬件加速不支持在screen上绘制位图，driver可以简化，直接返回false即可。有frame buffer的情况下，__GK_OutputRedraw中会调用这个函数。如果窗口direct_screen==true，也可能调用本函数。本函数返回false的话，gui kernel会进一步调用set_pixel_screen函数。即使硬件加速支持，但如果不支持具体的src_bitmap->PixelFormat，也可返回false。由于不知道本地显示器的情况，镜像显示器driver必须实现本函数，不能简单返回false。

3.11 get_pixel_screen：屏幕上读像素

u32 (*get_pixel_screen)(s32 x,s32 y);

参数：

x：目标像素的横坐标，相对于屏幕。

y：目标像素的纵坐标，相对于屏幕。

返回值：

像素值，转化为真彩色格式。

说明：

从screen中取一像素，并转换成CN_SYS_PF_ERGB8888。

3.12 get_rect_screen：屏幕上读位图

bool_t (*get_rect_screen)(struct tagRectangle *Rect,struct tagRectBitmap *Dest);

参数：

rect：读取的目标矩形区域。

dest：保存矩形区域读到的位图。

返回值：

true：成功；false：失败。

说明：

把screen内矩形区域的内容复制到bitmap，调用前，先设置好dest的FixelFormat。

3.13 disp_ctrl：控制显示器

bool_t (*disp_ctrl)(struct display_rsc *Disp);

参数：

disp：显示器指针。

返回值：

true：成功；false：失败。

说明：

控制显示器，这是由driver提供的一个应用程序的入口，该应用程序用于提供一个可视化的方式。设定该显示器所有可以由用户设定的参数，比如分辨率和和色彩参数。函数的功能不做统一规定，驱动程序的文档应该提供函数的使用说明。利用本函数，可以提供类似windows中设置显示器属性的功能。

4 GK显示器API说明

4.1 GK_ApiGetPixelFormat：查询显卡格式

u16 GK_ApiGetPixelFormat(struct tagDisplayRsc *Display)

头文件：

gkernel.h

参数：

Display：待查询的显卡

返回值：

显卡格式，也称颜色格式，如CN_SYS_PF_RGB565。

说明：

查询显卡使用的颜色格式，画位图时，如果使用跟显卡相同的颜色格式，将获得最优性能。

4.2 GK_InstallDisplay：安装显示器

bool_t GK_InstallDisplay(struct tagDisplayRsc *Display, char *Name)

头文件：

gk_display.h

参数：

Display：待安装的显示器。

Name：显示器名称。

返回值：

true：成功；false：失败。

说明：

把一台新显示器登记到显示器资源队列中。

4.3 GK_InstallDisplayMirror：安装镜像显示器

bool_t GK_InstallDisplayMirror(struct tagDisplayRsc *BaseDisplay,

                          struct tagDisplayRsc *MirrorDisplay,char *Name)

头文件：

gk_display.h

参数：

BaseDisplay：本地显示器。

MirrorDisplay：待安装的镜像显示器。

Name：显示器名称。

返回值：

true：成功；false：失败。

说明：

把一台镜像显示器登记到本地显示器。

​​​​​​​4.3 GK_SetDefaultDisplay：设置默认显示器

bool_t GK_SetDefaultDisplay(char *Name)

头文件：

gk_display.h

参数：

Name：显示器名称。

返回值：

true：成功；false：失败。

说明：

设置默认显示器。

​​​​​​​4.4 GK_GetRootWin：取显示器的默认设置

struct tagGkWinRsc *GK_GetRootWin(struct tagDisplayRsc *Display)

头文件：

gk_display.h

参数：

Display：显示器指针。

返回值：

显示器桌面指针。

说明：

取一个显示器的默认显示设置，实际上就是桌面窗口的资源节点。

​​​​​​​4.5 GK_SwitchFrameBuffer：切换帧缓冲

bool_t GK_SwitchFrameBuffer(struct tagDisplayRsc *Display,

                              struct tagRectBitmap *FrameBuf)

头文件：

gk_display.h

参数：

Display：显示器指针。

FrameBuf：帧缓冲打针。

返回值：

true：成功；false：失败。

说明：

当一个显示器有多个Frame Buffer时，用本函数切换当前Frame Buffer。

​​​​​​​4.6 GK_CreateFrameBuffer：创建帧缓冲

struct tagRectBitmap *GK_CreateFrameBuffer(struct tagDisplayRsc *Display)

头文件：

gk_display.h

参数：

Display：显示器指针。

返回值：

缓冲区指针。

说明：

为某显示器创建一个Frame Buffer。