1.\" Copyright (c) 1997 S�ren Schmidt 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer, 9.\" in this position and unchanged. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. The name of the author may not be used to endorse or promote products 14.\" derived from this software without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.Dd November 7, 1999 29.Dt VGL 3 30.Os 31.Sh NAME 32.Nm VGLBitmapAllocateBits , 33.Nm VGLBitmapCopy , 34.Nm VGLBitmapCreate , 35.Nm VGLBitmapDestroy , 36.Nm VGLBitmapPutChar , 37.Nm VGLBitmapString , 38.Nm VGLBlankDisplay , 39.Nm VGLBox , 40.Nm VGLCheckSwitch , 41.Nm VGLClear , 42.Nm VGLEllipse , 43.Nm VGLEnd , 44.Nm VGLFilledBox , 45.Nm VGLFilledEllipse , 46.Nm VGLGetXY , 47.Nm VGLInit , 48.Nm VGLLine , 49.Nm VGLKeyboardInit , 50.Nm VGLKeyboardEnd , 51.Nm VGLKeyboardGetCh , 52.Nm VGLMouseInit , 53.Nm VGLMouseMode , 54.Nm VGLMouseSetImage , 55.Nm VGLMouseSetStdImage , 56.Nm VGLMouseStatus , 57.Nm VGLPanScreen , 58.Nm VGLSetBorder , 59.Nm VGLSetPalette , 60.Nm VGLSetPaletteIndex , 61.Nm VGLSetVScreenSize , 62.Nm VGLSetXY , 63.Nm VGLTextSetFontFile 64.Nd Video Graphics Library functions 65.Sh LIBRARY 66.Lb libvgl 67.Sh SYNOPSIS 68.Fd #include <sys/fbio.h> 69.Fd #include <sys/consio.h> 70.Fd #include <sys/kbio.h> 71.Fd #include <vgl.h> 72.Ft int 73.Fn VGLInit "int mode" 74.Ft void 75.Fn VGLEnd "void" 76.Ft void 77.Fn VGLCheckSwitch "void" 78.Ft int 79.Fn VGLTextSetFontFile "char *filename" 80.Ft int 81.Fn VGLKeyboardInit "int code" 82.Ft void 83.Fn VGLKeyboardEnd "void" 84.Ft int 85.Fn VGLKeyboardGetCh "void" 86.Ft int 87.Fn VGLMouseInit "int mode" 88.Ft void 89.Fn VGLMouseMode "int mode" 90.Ft int 91.Fn VGLMouseStatus "int *x" "int *y" "char *buttons" 92.Ft void 93.Fn VGLMouseSetImage "VGLBitmap *AndMask" "VGLBitmap *OrMask" 94.Ft void 95.Fn VGLMouseSetStdImage "void" 96.Ft byte 97.Fn VGLGetXY "VGLBitmap *object" "int x" "int y" 98.Ft void 99.Fn VGLSetXY "VGLBitmap *object" "int x" "int y" "byte color" 100.Ft void 101.Fn VGLLine "VGLBitmap *object" "int x1" "int y1" "int x2" "int y2" "byte color" 102.Ft void 103.Fn VGLBox "VGLBitmap *object" "int x1" "int y1" "int x2" "int y2" "byte color" 104.Ft void 105.Fn VGLFilledBox "VGLBitmap *object" "int x1" "int y1" "int x2" "int y2" "byte color" 106.Ft void 107.Fn VGLEllipse "VGLBitmap *object" "int xc" "int yc" "int a" "int b" "byte color" 108.Ft void 109.Fn VGLFilledEllipse "VGLBitmap *object" "int xc" "int yc" "int a" "int b" "byte color" 110.Ft VGLBitmap * 111.Fn VGLBitmapCreate "int type" "int xsize" "int ysize" "byte *bits" 112.Ft void 113.Fn VGLBitmapDestroy "VGLBitmap *object" 114.Ft int 115.Fn VGLBitmapAllocateBits "VGLBitmap *object" 116.Ft int 117.Fn VGLBitmapCopy "VGLBitmap *src" "int srcx" "int srcy" "VGLBitmap *dst" "int dstx" "int dsty" "int width" "int hight" 118.Ft void 119.Fn VGLBitmapPutChar "VGLBitmap *Object" "int x" "int y" "byte ch" "byte fgcol" "byte bgcol" "int fill" "int dir" 120.Ft void 121.Fn VGLBitmapString "VGLBitmap *Object" "int x" "int y" "char *str" "byte fgcol" "byte bgcol" "int fill" "int dir" 122.Ft void 123.Fn VGLClear "VGLBitmap *object" "byte color" 124.Ft void 125.Fn VGLSetPalette "byte *red" "byte *green" "byte *blue" 126.Ft void 127.Fn VGLSetPaletteIndex "byte color" "byte red" "byte green" "byte blue" 128.Ft void 129.Fn VGLSetBorder "byte color" 130.Ft int 131.Fn VGLSetVScreenSize "VGLBitmap *object" "int vxsize" "int vysize" 132.Ft int 133.Fn VGLPanScreen "VGLBitmap *object" "int x" "int y" 134.Ft void 135.Fn VGLBlankDisplay "int blank" 136.Sh DESCRIPTION 137.Nm Libvgl 138is a library that enables the programmer access to the graphics 139modes supported by the console driver (syscons). The library takes care of 140programming the actual video hardware, and provides a number of simple 141functions to do various graphic operations. 142There is also support for a 143mouse via the standard mouse system in 144.Fx , 145see 146.Xr mouse 4 , 147including the ability to transparently have a mouse pointer superimposed on 148the graphic image currently being worked on. 149The library takes care of screen switching by storing the current image in 150memory before switching to another virtual console, and restoring when the 151user switches back. 152This allows several graphic applications at once, but 153on different virtual consoles. 154.Pp 155Below is a short description of the various functions: 156.Pp 157.Fn VGLInit 158initialize the library and set up the graphic mode 159.Va mode . 160.Pp 161.Fn VGLEnd 162terminate graphic mode, and restore the screenmode that was active before 163.Fn VGLInit 164was called. 165.Pp 166.Fn VGLCheckSwitch 167if the program goes into longer periods of processing without doing 168any graphics output, calling this function occasionally will allow 169the system to switch screens. 170.Pp 171.Fn VGLTextSetFontFile 172instruct the char/string functions to use the font in file 173.Pa filename 174instead of the builtin font. 175.Pp 176.Fn VGLKeyboardInit 177set up the keyboard in the 178.Dq raw 179I/O mode and 180specify the key code to be used. 181.Va code 182must be 183.Dv VGL_XLATEKEYS , 184.Dv VGL_CODEKEYS , 185or 186.Dv VGL_RAWKEYS . 187When 188.Dv VGL_XLATEKEYS 189is specified, the keyboard translate the raw keyboard scan code into 190a character code. 191If 192.Dv VGL_RAWKEYS 193is used, the raw keyboard scan code is read as is. 194.Dv VGL_CODEKEYS 195is the intermediate key code; each key is assigned a unique code whereas 196more than one raw scan code may be generated when a key is pressed. 197.Pp 198.Fn VGLKeyboardEnd 199when you have finished using the keyboard, call this function. 200.Pp 201.Fn VGLKeyboardGetCh 202read one byte from the keyboard. As the keyboard I/O is in the 203.Dq raw 204input mode, the function will not block even if there is no input data, 205and returns 0. 206.Pp 207.Fn VGLMouseInit 208initialize the mouse. 209The optional on-screen mouse pointer is shown if the 210argument is 211.Dv VGL_MOUSESHOW . 212.Pp 213.Fn VGLMouseMode 214either shows the mouse pointer if the argument is 215.Dv VGL_MOUSESHOW , 216or hides the mouse pointer if the argument is 217.Dv VGL_MOUSEHIDE . 218.Pp 219.Fn VGLMouseStatus 220returns the current mouse pointer coordinates and button state in 221.Va x , y , 222buttons. 223The return value reflects if the mouse pointer 224is currently shown on screen or not. 225.Pp 226.Fn VGLMouseSetImage 227with this function it is possible to change the image of the mouse pointer 228on screen. 229.Pp 230.Fn VGLMouseSetStdImage 231this function restores the mouse pointer to the standard arrow. 232.Pp 233.Fn VGLGetXY 234retrieves the color of the pixel located at 235.Va x , y , 236coordinates of the 237.Va object 238argument, and returns it as a byte value. 239.Pp 240.Fn VGLSetXY 241sets the color of the pixel located at 242.Va x , y , 243coordinates of the 244.Va object 245argument to 246.Va color 247byte value. 248.Pp 249.Fn VGLLine 250draw a line from 251.Va x1 , y1 252to 253.Va x2 , y2 254in color 255.Va color . 256.Pp 257.Fn VGLBox 258draw a box with upper left hand corner at 259.Va x1 , y1 260and lower right hand corner at 261.Va x2 , y2 262in color 263.Va color . 264.Pp 265.Fn VGLFilledBox 266draw a filled (solid) box with upper left hand corner at 267.Va x1 , y1 268and lower right hand corner at 269.Va x2 , y2 270in color 271.Va color . 272.Pp 273.Fn VGLEllipse 274draw an ellipse centered at 275.Va xc , yc 276make it 277.Va a 278pixels wide, and 279.Va b 280pixels high in color 281.Va color . 282.Pp 283.Fn VGLFilledEllipse 284draw a filled (solid) ellipse centered at 285.Va xc , yc 286make it 287.Va a 288pixels wide, and 289.Va b 290pixels high in color 291.Va color . 292.Pp 293.Fn VGLBitmapCreate 294create a bitmap object and initialize it with the specified 295values and bit data. 296.Va type 297must be 298.Dv MEMBUF 299for the in-memory bitmap. 300.Va bits 301may be NULL so that bitmap data may be associated later. 302.Pp 303There also is a macro, 304.Fn VGLBITMAP_INITIALIZER "type" "xsize" "ysize" "bits" 305to initialize a statically declared bitmap object. 306.Pp 307.Fn VGLBitmapDestroy 308free the bitmap data and the bitmap object. 309.Pp 310.Fn VGLBitmapAllocateBits 311allocate a bit data buffer for the specified object. 312.Pp 313.Fn VGLBitmapCopy 314copy a rectangle of pixels from bitmap 315.Va src 316upper left hand corner at 317.Va srcx , srcy 318to bitmap 319.Va dst 320at 321.Va dstx , dsty 322of the size 323.Va width , height . 324.Pp 325.Fn VGLBitmapPutChar 326write the character 327.Va ch 328at position 329.Va x , y 330in foreground color 331.Va fgcol . 332If 333.Va fill 334is != 0, use the color 335.Va bgcol 336as background otherwise the background is transparent. 337The character is drawn in the direction specified by the argument 338.Va dir . 339.Pp 340.Fn VGLBitmapString 341write the string 342.Va str 343at position 344.Va x , y 345in foreground color 346.Va fgcol . 347If 348.Va fill 349is != 0, use the color 350.Va bgcol 351as background otherwise the background is transparent. 352The string is drawn in the direction specified by the argument 353.Va dir . 354.Pp 355.Fn VGLClear 356clears the entire bitmap to color 357.Va color . 358.Pp 359.Fn VGLSetPalette 360this function sets the palette used, the arguments 361.Va red , green , blue 362should point to byte arrays of 256 positions each. 363.Pp 364.Fn VGLSetPaletteIndex 365set the palette index 366.Va color 367to the specified RGB value. 368.Pp 369.Fn VGLSetBorder 370set the border color to color 371.Va color . 372.Pp 373.Fn VGLSetVScreenSize 374change the virtual screen size of the display. Note that this 375function must be called when our vty is in the foreground. 376And 377.Va object 378must be 379.Va VGLDisplay . 380Passing a in-memory bitmap to this function results in error. 381.Pp 382The desired virtual screen width may not be achievable because 383of the video card hardware. In such case the video driver (and 384underlaying video BIOS) may choose the next largest values. 385Always examine 386.Va object->VXsize 387and 388.Va VYsize 389after calling this function, in order to see how the virtual screen 390is actually set up. 391.Pp 392In order to set up the largest possible virtual screen, you may 393call this function with arbitrary large values. 394.Pp 395.Dl VGLSetVScreenSize(10000, 10000); 396.Pp 397.Fn VGLPanSreen 398change the origin of the displayed screen in the virtual screen. 399Note that this function must be called when our vty is in the 400foreground. 401.Va object 402must be 403.Va VGLDisplay . 404Passing a in-memory bitmap to this function results in error. 405.Pp 406.Fn VGLBlankDisplay 407blank the display if the argument 408.Va blank 409\*(Ne 0. 410This can be done to shut off the screen during display updates that 411the user should first see when it's done. 412.Ss Program termination and signal processing 413It is important to call 414.Fn VGLEnd 415before terminating the program. 416Care must be taken if you install signal handlers and try to call 417.Fn VGLEnd 418and 419.Xr exit 3 420to end the program. 421If a signal is caught while the program is inside 422.Nm libvgl 423functions, 424.Fn VGLEnd 425may not be able to properly restore the graphics hardware. 426.Pp 427The recommended way to handle signals and program termination is to 428have a flag to indicate signal's delivery. 429Your signal handlers set this flag but do not terminate 430the program immediately. 431The main part of the program checks the flag to see if it is 432supposed to terminate, and calls 433.Fn VGLEnd 434and 435.Xr exit 3 436if the flag is set. 437.Pp 438Note that 439.Fn VGLInit 440installs its internal signal handlers for 441.Dv SIGINT , SIGTERM , SIGSEGV , 442and 443.Dv SIGBUS , 444and terminates the program at appropriate time, 445after one of these signals is caught. 446If you want to have your own signal handlers for these signals, 447install handlers 448.Em after 449.Fn VGLInit . 450.Pp 451.Dv SIGUSR1 452and 453.Dv SIGUSR2 454are internally used by 455.Nm libvgl 456to control screen switching and the mouse pointer, 457and are not available to 458.Nm libvgl 459client programs. 460.Sh AUTHORS 461.An S\(/oren Schmidt Aq sos@FreeBSD.org 462.Sh HISTORY 463The 464.Nm vgl 465library appeared in 466.Fx 3.0 . 467