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