6. GFBG接口说明¶
GFBG的API主要分为文件操作类（open、close等）、显存映射类（mmap、munmap等）、显存控制和状态查询类（像素格式、颜色深度等）和层间效果控制和状态查询类（显示原点、显示状态等）四大类。每一类的函数都具有特定的功能和用途，开发者可以根据实际需求选择合适的函数进行调用。 其中第一类和第二类是Linux提供的常用标准接口，本小节不会赘述，主要介绍第三类和第四类的接口函数。
6.1. ioctl函数¶
GFBG 的用户态接口以 ioctl 形式体现，其形式如下：
int ioctl(int fd, unsigned long cmd, ...);
GFBG只需要3个参数，即形式为：
int ioctl(int fd, unsigned long cmd, CMD_DATA_TYPE *cmd_data);
该功能模块为用户提供以下API：
FBIOGET_VSCREENINFO ：获取屏幕的可变信息。
FBIOPUT_VSCREENINFO ：设置 Framebuffer 的屏幕分辨率和像素格式等。
FBIOGET_FSCREENINFO ：获取 Framebuffer 的固定信息。
FBIOPAN_DISPLAY ：设置从虚拟分辨率中的不同偏移处开始显示。
FBIOGET_SCREEN_ORIGIN_GFBG ：获取叠加层在屏幕上显示的起始点坐标。
FBIOPUT_SCREEN_ORIGIN_GFBG ：设置叠加层在屏幕上显示的起始点坐标。
FBIOGET_SHOW_GFBG ：获取当前叠加层的显示状态。
FBIOPUT_SHOW_GFBG ：显示或隐藏该叠加层。
FBIOGET_COLORKEY_GFBG ：获取叠加层的 colorkey。
FBIOPUT_COLORKEY_GFBG ：设置叠加层的 colorkey。
FBIOGET_VER_BLANK_GFBG ：等待叠加层的垂直消隐区到来。
FBIOPUT_LAYER_INFO ：设置图层信息。
FBIOGET_LAYER_INFO ：获取图层信息。
FBIOGET_CANVAS_BUF ：获取画布信息。
FBIO_REFRESH ：扩展模式下，启动刷新操作。
FBIOPUT_SCREEN_SIZE ：设置图层在屏幕上的显示大小。
FBIOGET_SCREEN_SIZE ：获取图层在屏幕上的显示大小。
6.1.1. FBIOGET_VSCREENINFO¶
【描述】
获取屏幕的可变信息。
【语法】
int ioctl (int fd, FBIOGET_VSCREENINFO, struct fb_var_screeninfo *var);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOGET_VSCREENINFO |
ioctl 号 |
输入 |
var |
可变信息结构体指针 |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_fb.h
【注意】
【举例】
struct fb_var_screeninfo vinfo;
if (ioctl(fd, FBIOGET_VSCREENINFO, &vinfo) < 0) {
return -1;
}
【相关主题】
6.1.2. FBIOPUT_VSCREENINFO¶
【描述】
设置 Framebuffer 的屏幕分辨率和像素格式等。
【语法】
int ioctl (int fd, FBIOPUT_VSCREENINFO, struct fb_var_screeninfo *var);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOPUT_VSCREENINFO |
ioctl 号 |
输入 |
var |
可变信息结构体指针 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_fb.h
【注意】
分辨率的大小必须在各叠加层支持的分辨率范围内。
必须保证实际分辨率与偏移的和在虚拟分辨率范围内，否则系统会自动调整实际分辨率的大小让其在虚拟分辨率范围内。
对于隔行显示设备，要求分辨率的高度必须为偶数。
如果图形层支持缩放，可以设置显示分辨率大于设备分辨率，这时候显示图像的一部分。
【举例】
struct fb_var_screeninfo vinfo;
vinfo.xres = 1920;
vinfo.yres = 1080;
vinfo.bits_per_pixel = 32;
vinfo.xres_virtual = 1920;
vinfo.yres_virtual = 2160;
if (ioctl(fd, FBIOPUT_VSCREENINFO, &vinfo) < 0) {
return -1;
}
【相关主题】
6.1.3. FBIOGET_FSCREENINFO¶
【描述】
获取 Framebuffer 的固定信息。
【语法】
int ioctl (int fd, FBIOGET_FSCREENINFO, struct fb_fix_screeninfo *fix);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOGET_FSCREENINFO |
ioctl 号 |
输入 |
fix |
固定信息结构体指针 |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_fb.h
【注意】
无。
【举例】
无。
【相关主题】
无。
6.1.4. FBIOPAN_DISPLAY¶
【描述】
设置从虚拟分辨率中的不同偏移处开始显示。
【语法】
int ioctl (int fd, FBIOPAN_DISPLAY, struct fb_var_screeninfo *var);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOPAN_DISPLAY |
ioctl 号 |
输入 |
var |
可变信息结构体指针 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_fb.h
【注意】
此接口只应在 FB 标准模式中使用。
必须保证实际分辨率与偏移的和在虚拟分辨率范围内，否则设置不成功。
最好保证 xoffset 与 yoffset 形成的偏移地址是 16byte 对齐的，否则会将 xoffset 的值减少到能使偏移地址是 16byte 对齐的位置。
对于隔行显示设备，要求分辨率的高度必须为偶数。
使用此接口设置从虚拟分辨率中的不同偏移处开始显示，实际的分辨率不变。如下图所示：（xres_virtual, yres_virtual）是虚拟分辨率，（xres, yres）是实际显示的分辨率，(xoffset, yoffset)是显示的偏移。
图 6.1 FBIOPAN_DISPLAY示意图¶
【举例】 无。
【相关主题】
无。
6.1.5. FBIOGET_SCREEN_ORIGIN_GFBG¶
【描述】
获取叠加层在屏幕上显示的起始点坐标。
【语法】
int ioctl (int fd, FBIOGET_SCREEN_ORIGIN_GFBG, cvi_fb_point *point);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOGET_SCREEN_ORIGIN_GFBG |
ioctl 号 |
输入 |
point |
坐标原点结构体指针 |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】
【举例】
无。
【相关主题】
6.1.6. FBIOPUT_SCREEN_ORIGIN_GFBG¶
【描述】
设置叠加层在屏幕上显示的起始点坐标。
【语法】
int ioctl (int fd, FBIOPUT_SCREEN_ORIGIN_GFBG, cvi_fb_point *point);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOPUT_SCREEN_ORIGIN_GFBG |
ioctl 号 |
输入 |
point |
坐标原点结构体指针 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】
如果叠加层坐标原点超出了范围（x_pos > (max_width-min_width) 或 y_pos > (max_height-min_height)），默认将坐标原点设置为（max_width-min_width，max_height-min_height），其中 max_width 和 max_height 的值是设备时序定义的最大宽高；min_width 和 min_height 分别表示可加载的最小图像的宽和高，可通过 FBIOGET_CAPABILITY_GFBG 接口中的 min_width 和 min_height 成员获取。
对于隔行显示设备，要求坐标原点的纵坐标值为偶数。
【举例】
无。
【相关主题】
6.1.7. FBIOGET_SHOW_GFBG¶
【描述】
获取当前叠加层的显示状态。
【语法】
int ioctl (int fd, FBIOGET_SHOW_GFBG, CVI_BOOL *show);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOGET_SHOW_GFBG |
ioctl 号 |
输入 |
show |
该叠加层的显示状态： - * show = CVI_TRUE: 显示当前叠加层 - * show = CVI_FALSE: 隐藏当前叠加层 |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】
对软鼠标不适用。
【举例】
无。
【相关主题】
6.1.8. FBIOPUT_SHOW_GFBG¶
【描述】
显示或隐藏该叠加层。
【语法】
int ioctl (int fd, FBIOPUT_SHOW_GFBG, CVI_BOOL *show);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOPUT_SHOW_GFBG |
ioctl 号 |
输入 |
show |
该叠加层的显示状态： - * show = CVI_TRUE: 显示当前叠加层 - * show = CVI_FALSE: 隐藏当前叠加层 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】
为正常显示，在显示之前，应将 show 的值设为 CVI_TRUE 调用 ioctl(fd, FBIOPUT_SHOW_GFBG, &show)。
显示时应保证图形层的分辨率不超出设备分辨率。
保证显示设备的能力支持所要显示的分辨率。
【举例】
无。
【相关主题】
6.1.9. FBIOGET_COLORKEY_GFBG¶
【描述】
获取叠加层的 colorkey。
【语法】
int ioctl (int fd, FBIOGET_COLORKEY_GFBG, cvi_fb_colorkey *colorkey);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOGET_COLORKEY_GFBG |
ioctl 号 |
输入 |
colorkey |
colorkey 结构体指针 |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】
【举例】
无。
【相关主题】
6.1.10. FBIOPUT_COLORKEY_GFBG¶
【描述】
设置叠加层的 colorkey。
【语法】
int ioctl (int fd, FBIOPUT_COLORKEY_GFBG, cvi_fb_colorkey *colorkey);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOPUT_COLORKEY_GFBG |
ioctl 号 |
输入 |
colorkey |
colorkey 结构体指针 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】
【举例】
cvi_fb_colorkey colorkey;
colorkey.enable = CVI_TRUE;
colorkey.value = 0xFFFF0000;
if (ioctl(fd, FBIOPUT_COLORKEY_GFBG, &colorkey) < 0) {
return -1;
}
【相关主题】
6.1.11. FBIOGET_VER_BLANK_GFBG¶
【描述】
为了操作显存时不引起撕裂现象，建议在该叠加层的消隐区对显存进行操作，通过该接口可以等待该叠加层消隐区的到来，底层原理是等待vo的下一个中断到来。
【语法】
int ioctl (int fd, FBIOGET_VER_BLANK_GFBG);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOGET_VER_BLANK_GFBG |
ioctl 号 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】
垂直消隐间隔较短，一般在几十毫秒，建议操作时间尽量短，以保证在垂直消隐区结束前完成。
【举例】
无。
【相关主题】
无。
6.1.12. FBIOPUT_LAYER_INFO¶
【描述】
设置图层信息，用于完成从 FB 的标准模式到 FB 的扩展模式切换或是 FB 的扩展模式之间的切换，同时能设置扩展模式下的刷新信息。
【语法】
int ioctl (int fd, FBIOPUT_LAYER_INFO, cvi_fb_layer_info *layer_info);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOPUT_LAYER_INFO |
ioctl 号 |
输入 |
layer_info |
图层信息结构体指针 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】
在设置完某项属性后，必须通过设置 layer_info 的 mask 设置相应的掩码，否则该项设置不会生效。
对于隔行显示设备，要求显存分辨率与屏幕显示分辨率的高度都必须为偶数。
芯片中图层自带的缩放功能可以参考 FBIOPUT_SCREEN_SIZE。
【举例】
cvi_fb_layer_info layer_info = {0};
layer_info.buf_mode = CVI_FB_LAYER_BUF_NONE;
layer_info.mask = CVI_FB_LAYER_MASK_BUF_MODE;
ret = ioctl(s32Fd, FBIOPUT_LAYER_INFO, &layer_info);
【相关主题】
无。
6.1.13. FBIOGET_LAYER_INFO¶
【描述】
获取图层信息，包括刷新模式屏幕起始点位置、画布分辨率、显存分辨率、屏幕显示分辨率。
【语法】
int ioctl (int fd, FBIOGET_LAYER_INFO, cvi_fb_layer_info *layer_info);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOGET_LAYER_INFO |
ioctl 号 |
输入 |
layer_info |
图层信息结构体指针 |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】
该接口获取到的接口数据 cvi_fb_layer_info 中，mask 成员是没有意义的，始终被填充为 CVI_FB_LAYER_MASK_BUTT。
【举例】
无。
【相关主题】
无。
6.1.14. FBIOGET_CANVAS_BUF¶
【描述】
获取画布信息。
【语法】
int ioctl (int fd, FBIOGET_CANVAS_BUF, cvi_fb_buf *canvas_buf);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOGET_CANVAS_BUF |
ioctl 号 |
输入 |
canvas_buf |
画布信息结构体指针 |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】
【举例】
无。
【相关主题】
无。
6.1.15. FBIO_REFRESH¶
【描述】
扩展模式下，启动刷新操作。
【语法】
int ioctl (int fd, FBIO_REFRESH, cvi_fb_buf *buf_info);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIO_REFRESH |
ioctl 号 |
输入 |
buf_info |
cvi_fb_buf 结构体指针 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】 无。
【举例】
无。
【相关主题】
无。
6.1.16. FBIOPUT_SCREEN_SIZE¶
【描述】
设置图层在屏幕上的显示大小。
【语法】
int ioctl (int fd, FBIOPUT_SCREEN_SIZE, cvi_fb_size *cvi_fb_size);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOPUT_SCREEN_SIZE |
ioctl 号 |
输入 |
cvi_fb_size |
cvi_fb_size 类型指针，宽高要求 2 对齐。 |
输入 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】
通过设置屏幕显示分辨率，可以对图像进行缩放。如图像大小为 800x600，则设置屏幕显示大小为 1280x720 可将图像放大到 1280x720 显示。
图形层缩放限制：输入分辨率超过 1920x1080，不支持放大。
支持缩放倍数 1~15 倍。
【举例】
无。
【相关主题】
6.1.17. FBIOGET_SCREEN_SIZE¶
【描述】
获取图层在屏幕上的显示大小。
【语法】
int ioctl (int fd, FBIOGET_SCREEN_SIZE, cvi_fb_size *cvi_fb_size);
【参数】
参数名称 |
描述 |
输入/输出 |
|---|---|---|
fd |
Framebuffer 设备文件描述符 |
输入 |
FBIOGET_SCREEN_SIZE |
ioctl 号 |
输入 |
cvi_fb_size |
cvi_fb_size 类型指针 |
输出 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功。 |
-1 |
失败。 |
【需求】
头文件：cvi_comm_gfbg.h
【注意】
无。
【举例】
无。
【相关主题】