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