lib/libvgl/vgl.3

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