6. GFBG Interface Description

The GFBG APIs fall into four categories: file operations (open, close, and so on), video-memory mapping (mmap, munmap, and so on), video-memory control and status queries (pixel format, color depth, and so on), and layer-effect control and status queries (display origin, display state, and so on). Each function has a specific purpose; developers can select functions according to their needs. The first two categories are common standard interfaces provided by Linux and are not detailed here. This section focuses on the third and fourth categories.

6.1. ioctl Function

The GFBG user-space interface is exposed through ioctl in the following form:

int ioctl(int fd, unsigned long cmd, ...);

GFBG requires only three parameters, in the following form:

int ioctl(int fd, unsigned long cmd, CMD_DATA_TYPE *cmd_data);

This module provides users with the following APIs:

• FBIOGET_VSCREENINFO : Get the variable screen information.

• FBIOPUT_VSCREENINFO : Set the Framebuffer screen resolution, pixel format, and other attributes.

• FBIOGET_FSCREENINFO : Get the fixed Framebuffer information.

• FBIOPAN_DISPLAY : Set display to start at a different offset within the virtual resolution.

• FBIOGET_SCREEN_ORIGIN_GFBG : Get the starting coordinates of the overlay on the screen.

• FBIOPUT_SCREEN_ORIGIN_GFBG : Set the starting coordinates of the overlay on the screen.

• FBIOGET_SHOW_GFBG : Get the display state of the current overlay.

• FBIOPUT_SHOW_GFBG : Show or hide the overlay.

• FBIOGET_COLORKEY_GFBG : Get the overlay colorkey.

• FBIOPUT_COLORKEY_GFBG : Set the overlay colorkey.

• FBIOGET_VER_BLANK_GFBG : etc.wait foroverlay layerVertical Blankingareatoto.

• FBIOPUT_LAYER_INFO : setlayerinformation.

• FBIOGET_LAYER_INFO : getlayerinformation.

• FBIOGET_CANVAS_BUF : getcanvasinformation.

• FBIO_REFRESH : extendedmodeunder, bootrefreshoperation.

• FBIOPUT_SCREEN_SIZE : setlayerinpanelondisplaysize.

• FBIOGET_SCREEN_SIZE : getlayerinpanelondisplaysize.

6.1.1. FBIOGET_VSCREENINFO

[Description]

Get the variable screen information.

[Syntax]

int ioctl (int fd, FBIOGET_VSCREENINFO, struct fb_var_screeninfo *var);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOGET_VSCREENINFO	ioctl number	Input
var	Pointer to the variable-information structure	Output

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_fb.h

[Note]

[Example]

struct fb_var_screeninfo vinfo;
if (ioctl(fd, FBIOGET_VSCREENINFO, &vinfo) < 0) {
    return -1;
}

[Related Topics]

FBIOPUT_VSCREENINFO

6.1.2. FBIOPUT_VSCREENINFO

[Description]

Set the Framebuffer screen resolution, pixel format, and other attributes.

[Syntax]

int ioctl (int fd, FBIOPUT_VSCREENINFO, struct fb_var_screeninfo *var);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOPUT_VSCREENINFO	ioctl number	Input
var	Pointer to the variable-information structure	Input

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_fb.h

[Note]

• resolutionsizemustineachoverlay layersupportresolutionrangein.

• mustensureactualresolutionwithoffset andinvirtualresolutionrangein, otherwisesystemwillautomaticadjustactualresolutionsizemakeitsinvirtualresolutionrangein.

• For interlacedlinedisplaydevice, need torequestresolutionheightmustisevennumber.

• If graphicallayersupportscaling, cansetdisplayresolutiongreater thandeviceresolution, thiswhendisplayimageonepart.

[Example]

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;
}

[Related Topics]

FBIOGET_VSCREENINFO

6.1.3. FBIOGET_FSCREENINFO

[Description]

Get the fixed Framebuffer information.

[Syntax]

int ioctl (int fd, FBIOGET_FSCREENINFO, struct fb_fix_screeninfo *fix);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOGET_FSCREENINFO	ioctl number	Input
fix	Pointer to the fixed-information structure	Output

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_fb.h

[Note]

None.

[Example]

None.

[Related Topics]

None.

6.1.4. FBIOPAN_DISPLAY

[Description]

Set display to start at a different offset within the virtual resolution.

[Syntax]

int ioctl (int fd, FBIOPAN_DISPLAY, struct fb_var_screeninfo *var);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOPAN_DISPLAY	ioctl number	Input
var	Pointer to the variable-information structure	Input

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_fb.h

[Note]

• thisconnectinterface should onlyin FB standardmodeinuse.

• mustensureactualresolutionwithoffset andinvirtualresolutionrangein, otherwisesetnotSuccess.

• mostensure well xoffset with yoffset shapebecomeoffsetaddressis 16byte alignment, otherwisewillwill xoffset valuereducetocanmakeoffsetaddressis 16byte alignmentposition.

• For interlacedlinedisplaydevice, need torequestresolutionheightmustisevennumber.

• usethisconnectportsetfromvirtualresolutioninnotsameoffset positionstartdisplay, actualresolutionnotchange. as followsFigure shown: (xres_virtual, yres_virtual) isvirtualresolution, (xres, yres) isactualdisplayresolution, (xoffset, yoffset)isdisplayoffset.

Figure 6.1 FBIOPAN_DISPLAYillustration

[Example] None.

[Related Topics]

None.

6.1.5. FBIOGET_SCREEN_ORIGIN_GFBG

[Description]

Get the starting coordinates of the overlay on the screen.

[Syntax]

int ioctl (int fd, FBIOGET_SCREEN_ORIGIN_GFBG, cvi_fb_point *point);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOGET_SCREEN_ORIGIN_GFBG	ioctl number	Input
point	Pointer to the origin-coordinate structure	Output

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note]

[Example]

None.

[Related Topics]

FBIOPUT_SCREEN_ORIGIN_GFBG

6.1.6. FBIOPUT_SCREEN_ORIGIN_GFBG

[Description]

Set the starting coordinates of the overlay on the screen.

[Syntax]

int ioctl (int fd, FBIOPUT_SCREEN_ORIGIN_GFBG, cvi_fb_point *point);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOPUT_SCREEN_ORIGIN_GFBG	ioctl number	Input
point	Pointer to the origin-coordinate structure	Input

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note]

• If overlay layerorigin exceedsoutrange (x_pos > (max_width-min_width) or y_pos > (max_height-min_height)) , defaultwilloriginsetis (max_width-min_width, max_height-min_height) , where max_width and max_height valueisdevicetimingdefinitionmaximumwidthhigh; min_width and min_height respectivelymeanscan loadminimumimagewidthandhigh, can through FBIOGET_CAPABILITY_GFBG connectportin min_width and min_height memberget.

• For interlacedlinedisplaydevice, need torequestoriginvertical coordinatevalueisevennumber.

[Example]

None.

[Related Topics]

FBIOGET_SCREEN_ORIGIN_GFBG

6.1.7. FBIOGET_SHOW_GFBG

[Description]

Get the display state of the current overlay.

[Syntax]

int ioctl (int fd, FBIOGET_SHOW_GFBG, CVI_BOOL *show);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOGET_SHOW_GFBG	ioctl number	Input
show	theoverlay layerdisplaystatus: - * show = CVI_TRUE: displaycurrentoverlay layer - * show = CVI_FALSE: hidecurrentoverlay layer	Output

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note]

• forsoftmousenotsuitableuse.

[Example]

None.

[Related Topics]

FBIOPUT_SHOW_GFBG

6.1.8. FBIOPUT_SHOW_GFBG

[Description]

Show or hide the overlay.

[Syntax]

int ioctl (int fd, FBIOPUT_SHOW_GFBG, CVI_BOOL *show);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOPUT_SHOW_GFBG	ioctl number	Input
show	theoverlay layerdisplaystatus: - * show = CVI_TRUE: displaycurrentoverlay layer - * show = CVI_FALSE: hidecurrentoverlay layer	Input

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note]

• isnormaldisplay, indisplaybefore, shouldwill show valuesetis CVI_TRUE call ioctl(fd, FBIOPUT_SHOW_GFBG, &show).

• displaywhenshouldensuregraphicallayerresolutionnotexceedoutdeviceresolution.

• ensuredisplaydevicecapabilitysupportrequireddisplayresolution.

[Example]

None.

[Related Topics]

FBIOGET_SHOW_GFBG

6.1.9. FBIOGET_COLORKEY_GFBG

[Description]

Get the overlay colorkey.

[Syntax]

int ioctl (int fd, FBIOGET_COLORKEY_GFBG, cvi_fb_colorkey *colorkey);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOGET_COLORKEY_GFBG	ioctl number	Input
colorkey	colorkey structurepointer	Output

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note]

[Example]

None.

[Related Topics]

FBIOPUT_COLORKEY_GFBG

6.1.10. FBIOPUT_COLORKEY_GFBG

[Description]

Set the overlay colorkey.

[Syntax]

int ioctl (int fd, FBIOPUT_COLORKEY_GFBG, cvi_fb_colorkey *colorkey);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOPUT_COLORKEY_GFBG	ioctl number	Input
colorkey	colorkey structurepointer	Input

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note]

[Example]

cvi_fb_colorkey colorkey;
colorkey.enable = CVI_TRUE;
colorkey.value = 0xFFFF0000;
if (ioctl(fd, FBIOPUT_COLORKEY_GFBG, &colorkey) < 0) {
    return -1;
}

[Related Topics]

FBIOGET_COLORKEY_GFBG

6.1.11. FBIOGET_VER_BLANK_GFBG

[Description]

isoperationvideo memorywhennotleadstarttearingphenomenon, recommendintheoverlay layerblankingareaforvideo memoryperform operation, throughtheconnectportcanetc.wait fortheoverlay layerblankingareatoto, bottomlayerprincipleisetc.wait forvounderoneinterrupttoto.

[Syntax]

int ioctl (int fd, FBIOGET_VER_BLANK_GFBG);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOGET_VER_BLANK_GFBG	ioctl number	Input

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note]

• Vertical Blankingbetweeninterlacedshorter, generallyintens of millisecondsseconds, recommendoperationtimeas much as possibleshort, withensureinVertical Blankingareaendbeforecomplete.

[Example]

None.

[Related Topics]

None.

6.1.12. FBIOPUT_LAYER_INFO

[Description]

setlayerinformation, used to completefrom FB standardmodeto FB extendedmodeswitchoris FB extendedmodebetweenswitch, at the same timecansetextendedmodeunderrefreshinformation.

[Syntax]

int ioctl (int fd, FBIOPUT_LAYER_INFO, cvi_fb_layer_info *layer_info);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOPUT_LAYER_INFO	ioctl number	Input
layer_info	Pointer to the layer-information structure	Input

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note]

• insetcomplete an itemattributeafter, mustthroughset layer_info mask setcorrespondingmask, otherwisetheitemsetnotwilltake effect.

• For interlacedlinedisplaydevice, need torequestvideo memoryresolutionwithpaneldisplayresolutionheightallmustisevennumber.

• chipinlayerbuilt-inscalingfunctioncanreference FBIOPUT_SCREEN_SIZE.

[Example]

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);

[Related Topics]

None.

6.1.13. FBIOGET_LAYER_INFO

[Description]

getlayerinformation, includingrefreshmodepanelstartstartpointposition, canvasresolution, video memoryresolution, paneldisplayresolution.

[Syntax]

int ioctl (int fd, FBIOGET_LAYER_INFO, cvi_fb_layer_info *layer_info);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOGET_LAYER_INFO	ioctl number	Input
layer_info	Pointer to the layer-information structure	Output

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note]

• theconnectportgettoconnectportdata cvi_fb_layer_info Medium, mask memberisno hasmeaning, alwaysbepopulateis CVI_FB_LAYER_MASK_BUTT.

[Example]

None.

[Related Topics]

None.

6.1.14. FBIOGET_CANVAS_BUF

[Description]

getcanvasinformation.

[Syntax]

int ioctl (int fd, FBIOGET_CANVAS_BUF, cvi_fb_buf *canvas_buf);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOGET_CANVAS_BUF	ioctl number	Input
canvas_buf	Pointer to the canvas-information structure	Output

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note]

[Example]

None.

[Related Topics]

None.

6.1.15. FBIO_REFRESH

[Description]

extendedmodeunder, bootrefreshoperation.

[Syntax]

int ioctl (int fd, FBIO_REFRESH, cvi_fb_buf *buf_info);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIO_REFRESH	ioctl number	Input
buf_info	cvi_fb_buf structurepointer	Input

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note] None.

[Example]

None.

[Related Topics]

None.

6.1.16. FBIOPUT_SCREEN_SIZE

[Description]

setlayerinpanelondisplaysize.

[Syntax]

int ioctl (int fd, FBIOPUT_SCREEN_SIZE, cvi_fb_size *cvi_fb_size);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOPUT_SCREEN_SIZE	ioctl number	Input
cvi_fb_size	cvi_fb_size typepointer, widthhighneed torequest 2 alignment.	Input

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note]

• throughsetpaneldisplayresolution, canforimageperform scaling. ifimagesizeis 800x600, thensetpaneldisplaysizeis 1280x720 can willimageplacelargeto 1280x720 display.

• graphicallayerscalinglimit: inputresolutionexceed 1920x1080, not supportedplacelarge.

• supportscalingtimesnumber 1~15 times.

[Example]

None.

[Related Topics]

FBIOGET_SCREEN_SIZE

6.1.17. FBIOGET_SCREEN_SIZE

[Description]

getlayerinpanelondisplaysize.

[Syntax]

int ioctl (int fd, FBIOGET_SCREEN_SIZE, cvi_fb_size *cvi_fb_size);

[Parameters]

Parameter Name	Description	Input/Output
fd	Framebuffer Framebuffer device file descriptor	Input
FBIOGET_SCREEN_SIZE	ioctl number	Input
cvi_fb_size	cvi_fb_size typepointer	Output

[Return Value]

Return Value	Description
0	Success.
-1	Failure.

[Requirements]

• Header files:cvi_comm_gfbg.h

[Note]

None.

[Example]

None.

[Related Topics]

FBIOPUT_SCREEN_SIZE