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 withough 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 FreeBSD 3.0 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 (libvgl) 65.Sh SYNOPSIS 66.Fd #include <vgl.h> 67.Ft int 68.Fn VGLInit "int mode" 69.Ft void 70.Fn VGLEnd "void" 71.Ft void 72.Fn VGLCheckSwitch "void" 73.Ft int 74.Fn VGLTextSetFontFile "char *filename" 75.Ft int 76.Fn VGLKeyboardInit "int code" 77.Ft void 78.Fn VGLKeyboardEnd "void" 79.Ft int 80.Fn VGLKeyboardGetCh "void" 81.Ft int 82.Fn VGLMouseInit "int mode" 83.Ft void 84.Fn VGLMouseMode "int mode" 85.Ft int 86.Fn VGLMouseStatus "int *x" "int *y" "char *buttons" 87.Ft void 88.Fn VGLMouseSetImage "VGLBitmap *AndMask" "VGLBitmap *OrMask" 89.Ft void 90.Fn VGLMouseSetStdImage "void" 91.Ft byte 92.Fn VGLGetXY "VGLBitmap *object" "int x" "int y" 93.Ft void 94.Fn VGLSetXY "VGLBitmap *object" "int x" "int y" "byte color" 95.Ft void 96.Fn VGLLine "VGLBitmap *object" "int x1" "int y1" "int x2" "int y2" "byte color" 97.Ft void 98.Fn VGLBox "VGLBitmap *object" "int x1" "int y1" "int x2" "int y2" "byte color" 99.Ft void 100.Fn VGLFilledBox "VGLBitmap *object" "int x1" "int y1" "int x2" "int y2" "byte color" 101.Ft void 102.Fn VGLEllipse "VGLBitmap *object" "int xc" "int yc" "int a" "int b" "byte color" 103.Ft void 104.Fn VGLFilledEllipse "VGLBitmap *object" "int xc" "int yc" "int a" "int b" "byte color" 105.Ft VGLBitmap * 106.Fn VGLBitmapCreate "int type" "int xsize" "int ysize" "byte *bits" 107.Ft void 108.Fn VGLBitmapDestroy "VGLBitmap *object" 109.Ft int 110.Fn VGLBitmapAllocateBits "VGLBitmap *object" 111.Ft int 112.Fn VGLBitmapCopy "VGLBitmap *src" "int srcx" "int srcy" "VGLBitmap *dst" "int dstx" "int dsty" "int width" "int hight" 113.Ft void 114.Fn VGLBitmapPutChar "VGLBitmap *Object" "int x" "int y" "byte ch" "byte fgcol" "byte bgcol" "int fill" "int dir" 115.Ft void 116.Fn VGLBitmapString "VGLBitmap *Object" "int x" "int y" "char *str" "byte fgcol" "byte bgcol" "int fill" "int dir" 117.Ft void 118.Fn VGLClear "VGLBitmap *object" "byte color" 119.Ft void 120.Fn VGLSetPalette "byte *red" "byte *green" "byte *blue" 121.Ft void 122.Fn VGLSetPaletteIndex "byte color" "byte red" "byte green" "byte blue" 123.Ft void 124.Fn VGLSetBorder "byte color" 125.Ft int 126.Fn VGLSetVScreenSize "VGLBitmap *object" "int vxsize" "int vysize" 127.Ft int 128.Fn VGLPanSreen "VGLBitmap *object" "int x" "int y" 129.Ft void 130.Fn VGLBlankDisplay "int blank" 131.Sh DESCRIPTION 132.Nm Libvgl 133is a library that enables the programmer access to the graphics 134modes supported by the console driver (syscons). The library takes care of 135programming the actual video hardware, and provides a number of simple 136functions to do various graphic operations. There is also support for a 137mouse via the standard mouse system in 138.Fx , 139see 140.Xr mouse 4 , 141including the ability to transparently have a mouse pointer superimposed on 142the graphic image currently being worked on. 143The library takes care of screen switching by storing the current image in 144memory before switching to another virtual console, and restoring when the 145user switches back. This allows several graphic applications at once, but 146on different virtual consoles. 147 148Below is a short description of the various functions: 149.Pp 150.Fn VGLInit 151initialize the library and set up the graphic mode 152.Em mode . 153.Pp 154.Fn VGLEnd 155terminate graphic mode, and restore the screenmode that was active before 156.Fn VGLInit 157was called. 158.Pp 159.Fn VGLCheckSwitch 160if the program goes into longer periods of processing without doing 161any graphics output, calling this function occasionally will allow 162the system to switch screens. 163.Pp 164.Fn VGLTextSetFontFile 165instruct the char/string functions to use the font in file 166.Em filename 167instead of the builtin font. 168.Pp 169.Fn VGLKeyboardInit 170set up the keyboard in the ``raw'' I/O mode and 171specify the key code to be used. 172.Em code 173must be 174.Em VGL_XLATEKEYS , 175.Em VGL_CODEKEYS , 176or 177.Em VGL_RAWKEYS . 178When 179.Em VGL_XLATEKEYS 180is specified, the keyboard translate the raw keyboard scan code into 181a character code. 182If 183.Em VGL_RAWKEYS 184is used, the raw keyboard scan code is read as is. 185.Em VGL_CODEKEYS 186is the intermediate key code; each key is assigned a unique code whereas 187more than one raw scan code may be generated when a key is pressed. 188.Pp 189.Fn VGLKeyboardEnd 190when you have finished using the keyboard, call this function. 191.Pp 192.Fn VGLKeyboardGetCh 193read one byte from the keyboard. As the keyboard I/O is in the ``raw'' 194input mode, the function will not block even if there is no input data, 195and returns 0. 196.Pp 197.Fn VGLMouseInit 198initialize the mouse. The optional on-screen mouse pointer is shown if the 199argument is 200.Em VGL_MOUSESHOW . 201.Pp 202.Fn VGLMouseMode 203either shows the mouse pointer if the argument is 204.Em VGL_MOUSESHOW , 205or hides the mouse pointer if the argument is 206.Em VGL_MOUSEHIDE . 207.Pp 208.Fn VGLMouseStatus 209returns the current mouse pointer coordinates and button state in 210.Em x , y , 211buttons. The return value reflects if the mouse pointer 212is currently shown on screen or not. 213.Pp 214.Fn VGLMouseSetImage 215with this function it is possible to change the image of the mouse pointer 216on screen. 217.Pp 218.Fn VGLMouseSetStdImage 219this function restores the mouse pointer to the standard arrow. 220.Pp 221.Fn VGLGetXY 222retrieves the color of the pixel located at 223.Em x , y , 224coordinates of the 225.Em object 226argument, and returns it as a byte value. 227.Pp 228.Fn VGLSetXY 229sets the color of the pixel located at 230.Em x , y , 231coordinates of the 232.Em object 233argument to 234.Em color 235byte value. 236.Pp 237.Fn VGLLine 238draw a line from 239.Em x1 , y1 240to 241.Em x2 , y2 242in color 243.Em color . 244.Pp 245.Fn VGLBox 246draw a box with upper left hand corner at 247.Em x1 , y1 248and lower right hand corner at 249.Em x2 , y2 250in color 251.Em color . 252.Pp 253.Fn VGLFilledBox 254draw a filled (solid) box with upper left hand corner at 255.Em x1 , y1 256and lower right hand corner at 257.Em x2 , y2 258in color 259.Em color . 260.Pp 261.Fn VGLEllipse 262draw an ellipse centered at 263.Em xc , yc 264make it 265.Em a 266pixels wide, and 267.Em b 268pixels high in color 269.Em color . 270.Pp 271.Fn VGLFilledEllipse 272draw a filled (solid) ellipse centered at 273.Em xc , yc 274make it 275.Em a 276pixels wide, and 277.Em b 278pixels high in color 279.Em color . 280.Pp 281.Fn VGLBitmapCreate 282create a bitmap object and initialize it with the specified 283values and bit data. 284.Em type 285must be 286.Em MEMBUF 287for the in-memory bitmap. 288.Em bits 289may be NULL so that bitmap data may be associated later. 290.Pp 291There also is a macro, 292.Fn VGLBITMAP_INITIALIZER "type" "xsize" "ysize" "bits" 293to initialize a statically declared bitmap object. 294.Pp 295.Fn VGLBitmapDestroy 296free the bitmap data and the bitmap object. 297.Pp 298.Fn VGLBitmapAllocateBits 299allocate a bit data buffer for the specified object. 300.Pp 301.Fn VGLBitmapCopy 302copy a rectangle of pixels from bitmap 303.Em src 304upper left hand corner at 305.Em srcx , srcy 306to bitmap 307.Em dst 308at 309.Em dstx , dsty 310of the size 311.Em width , height . 312.Pp 313.Fn VGLBitmapPutChar 314write the character 315.Em ch 316at position 317.Em x , y 318in foreground color 319.Em fgcol . 320If 321.Em fill 322is != 0, use the color 323.Em bgcol 324as background otherwise the background is transparent. 325The character is drawn in the direction specified by the argument 326.Em dir . 327.Pp 328.Fn VGLBitmapString 329write the string 330.Em str 331at position 332.Em x , y 333in foreground color 334.Em fgcol . 335If 336.Em fill 337is != 0, use the color 338.Em bgcol 339as background otherwise the background is transparent. 340The string is drawn in the direction specified by the argument 341.Em dir . 342.Pp 343.Fn VGLClear 344clears the entire bitmap to color 345.Em color . 346.Pp 347.Fn VGLSetPalette 348this function sets the palette used, the arguments 349.Em red , green , blue 350should point to byte arrays of 256 positions each. 351.Pp 352.Fn VGLSetPaletteIndex 353set the palette index 354.Em color 355to the specified RGB value. 356.Pp 357.Fn VGLSetBorder 358set the border color to color 359.Em color . 360.Pp 361.Fn VGLSetVScreenSize 362change the virtual screen size of the display. Note that this 363function must be called when our vty is in the foreground. 364And 365.Em object 366must be 367.Em VGLDisplay . 368Passing a in-memory bitmap to this function results in error. 369.Pp 370The desired virtual screen width may not be achievable because 371of the video card hardware. In such case the video driver (and 372underlaying video BIOS) may choose the next largest values. 373Always examine 374.Em object->VXsize 375and 376.Em VYsize 377after calling this function, in order to see how the virtual screen 378is actually set up. 379.Pp 380In order to set up the largest possible virtual screen, you may 381call this function with arbitrary large values. 382.Pp 383.Dl VGLSetVScreenSize(10000, 10000); 384.Pp 385.Fn VGLPanSreen 386change the origin of the displayed screen in the virtual screen. 387Note that this function must be called when our vty is in the 388foreground. 389.Em object 390must be 391.Em VGLDisplay . 392Passing a in-memory bitmap to this function results in error. 393.Pp 394.Fn VGLBlankDisplay 395blank the display if the argment 396.Em blank 397!= 0. This can be done to shut off the screen during display updates that 398the user should first see when it's done. 399.Sh AUTHORS 400.An S�ren Schmidt Aq sos@FreeBSD.org 401.Sh HISTORY 402The 403.Nm vgl 404library appeared in 405.Fx 3.0 . 406