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