0-readme

linux 下svgalib编的一个界面程序示例

svgalib(7)	       Svgalib User Manual	       svgalib(7)


NAME
       svgalib - a low level graphics library for linux

TABLE OF CONTENTS
       0. Introduction
       1. Installation
       2. How to use svgalib
       3. Description of svgalib functions
       4. Overview of supported SVGA chipsets and modes
       5. Detailed comments on certain device drivers
       6. Goals
       7. References (location of latest version, apps etc.)
       8. Known bugs


0. INTRODUCTION
       This is a low level graphics library for Linux, originally
       based on VGAlib 1.2 by Tommy Frandsen. VGAlib supported	a
       number  of  standard  VGA graphics modes, as well as Tseng
       ET4000 high resolution 256-color modes. As of now, support
       for  many  more	chipsets  has  been  added. See section 4
       Overview of supported SVGA chipsets and modes

       It supports transparent virtual	console	 switching,  that
       is,  you can switch consoles to and from text and graphics
       mode consoles using alt-[function key]. Also, svgalib cor-
       rects  most  of	VGAlib's textmode corruption behaviour by
       catching SIGSEGV, SIGFPE, SIGILL, and other fatal  signals
       and  ensuring  that  a program is running in the currently
       visible virtual console before setting a graphics mode.

       Note right here that SIGUSR1 and SIGUSR2 are used to  man-
       age  console switching internally in svgalib.  You can not
       use them in your programs. If your program  needs  to  use
       one of those signals, svgalib can be compiled to use other
       signals, by editing libvga.h

       This version includes code to hunt for a free virtual con-
       sole  on	 its own in case you are not starting the program
       from one (but instead over a network or modem login,  from
       within  screen(1)  or  an  xterm(1)).  Provided there is a
       free console, this succeeds if you  are	root  or  if  the
       svgalib	calling	 user own the current console. This is to
       avoid people not using the console being	 able  to  fiddle
       with it.	 On graceful exit the program returns to the con-
       sole from which it was started.	Otherwise it  remains  in
       text  mode  at the VC which svgalib allocated to allow you
       to see any error	 messages.  In	any  case,  any	 I/O  the
       svgalib	makes  in  text	 mode (after calling vga_init(3))
       will also take place at this new console.

       Alas, some games misuse their suid root priviledge and run
       as  full	 root  process.	 svgalib  cannot  detect this and
       allows Joe Blow User to open a new VC on the  console.  If



Svgalib 1.4.1		 16 December 1999			1





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       this  annoys  you, ROOT_VC_SHORTCUT in Makefile.cfg allows
       you to disable allocating a new VC for root  (except  when
       he  owns	 the  current  console) when you compile svgalib.
       This is the default.

       When the library is used by a program at	 run-time,  first
       the  chipset  is	 detected  and	the appropriate driver is
       used. This means that a graphics program will work on  any
       card  that is supported by svgalib, if the mode it uses is
       supported by the chipset driver for that card. The library
       is upwardly compatible with VGAlib.

       The set of drawing functions provided by svgalib itself is
       limited (unchanged from VGAlib) and unoptimized;	 you  can
       however	use  vga_setpage(3) and vga_getgraphmem(3) (which
       points to the 64K VGA framebuffer) in a program or  graph-
       ics library.  A fast external framebuffer graphics library
       for linear and banked 1, 2, 3 and 4 bytes per pixel  modes
       is  included  (it  also	indirectly  supports  planar  VGA
       modes). It is documented in vgagl(7).

       One obvious  application	 of  the  library  is  a  picture
       viewer.	Several are available, along with animation view-
       ers. See the 7. References at the end of this document.

       I have added a simple VGA textmode font restoration  util-
       ity  (restorefont(1))  which  may  help if you suffer from
       XFree86 textmode font corruption. It can also be	 used  to
       change  the  textmode  font.  It	 comes	with  some  other
       textmode	    utilities:	   restoretextmode(1)	   (which
       saves/restores textmode registers), restorepalette(1), and
       the script textmode(1).	If you	run  the  savetextmode(1)
       script  to  save	 textmode  information to /tmp, you'll be
       able  to	 restore  textmode  by	running	 the  textmode(1)
       script.


1. INSTALLATION
       Installation is easy in general but there are many options
       and things you should keep in mind. This document  however
       assumes that svgalib is already installed.

       If  you	need  information  on  installation see 0-INSTALL
       which comes with the svgalib distribution.

       However, even after installation of the library you  might
       need  to	 configure  svgalib  using the file /etc/vga/lib-
       vga.config.  Checkout section 4 Overview of supported SVGA
       chipsets and modes and libvga.config(5) for information.


2. HOW TO USE SVGALIB
       For  basic  svgalib  usage (no mouse, no raw keyboard) add
       #include <vga.h>	 at  the  beginning  your  program.   Use



Svgalib 1.4.1		 16 December 1999			2





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       vga_init(3)  as your first svgalib call. This will give up
       root privileges right after initialization, making setuid-
       root binaries relatively safe.

       The  function vga_getdefaultmode(3) checks the environment
       variable SVGALIB_DEFAULT_MODE  for  a  default  mode,  and
       returns	the  corresponding  mode  number. The environment
       string can either be a mode number or a mode  name  as  in
       (G640x480x2,  G640x480x16,  G640x480x256	 ,  G640x480x32K,
       G640x480x64K, G640x480x16M).  As an example,  to	 set  the
       default graphics mode to 640x480, 256 colors, use:

       export SVGALIB_DEFAULT_MODE=G640x480x256

       on  the	bash(1)	 command  line. If a program needs just a
       linear VGA/SVGA resolution (as required by vgagl(7)), only
       modes  where  bytesperpixel  in the vga_modeinfo structure
       returned by vga_getmodeinfo(3) is greater or  equal  to	1
       should be accepted (this is 0 for tweaked planar 256-color
       VGA modes).

       Use vga_setmode(graphicsmode) to set a graphics mode.  Use
       vga_setmode(TEXT) to restore textmode before program exit.

       Programs that use svgalib must  #include<vga.h>;	 if  they
       also  use the external graphics library vgagl(7), you must
       also #include<vgagl.h>.	Linking must be done  with  -lvga
       (and  -lvgagl  before -lvga, if vgagl(7) is used). You can
       save binary space by removing the unused	 chipset  drivers
       in Makefile.cfg if you only use specific chipsets. However
       this reduces the flexibility of svgalib and has a signifi-
       cant  effect  only  when you use the static libraries. You
       should better use the shared libraries and these will load
       only the really used parts anyway.

       Functions  in  the  vgagl(7)  library have the prefix gl_.
       Please see vgagl(7) for details.

       There are demos with sources  available	which  will  also
       help  to get you started, in recomended order of interest:
       vgatest(6), keytest(6), mousetest(6), eventtest(6),  fork-
       test(6),	 bg_test(6), scrolltest(6), speedtest(6), fun(6),
       spin(6), testlinear(6), lineart(6),  testgl(6),	accel(6),
       testaccel(6), plane(6), and wrapdemo(6).

       Debugging  your programs will turn out to be rather diffi-
       cult, because the  svgalib  application	can  not  restore
       textmode when it returns to the debugger.

       Happy  are the users with a serial terminal, X-station, or
       another way to log into the machine  from  network.  These
       can use

       textmode </dev/ttyN



Svgalib 1.4.1		 16 December 1999			3





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       on the console where the program runs and continue.

       However,	 the vga_flip(3) function allows you to switch to
       textmode by entering a call to it blindly into your debug-
       ger when your program stops in graphics mode.  vga_flip(3)
       is not very robust though. You  shall  not  call	 it  when
       svgalib is not yet initialized or in textmode.

       Before	continuing  your  program,  you	 must  then  call
       vga_flip(3) again to return to graphics mode. If the  pro-
       gram  will  not	make any screen accesses or svgalib calls
       before it returns to the debugger, you can omit	that,  of
       course.

       This  will  only work if your program and the debugger run
       in the same virtual linux console.


3. DESCRIPTION OF SVGALIB FUNCTIONS
       Each function has it's own section 3 manual  page.  For	a
       list of vgagl functions see vgagl(7).

   Initialization
       vga_init(3)
	      - initialize svgalib library.
       vga_disabledriverreport(3)
	      - makes svgalib not emit any startup messages.
       vga_claimvideomemory(3)
	      - declare the amount of video memory used.
       vga_safety_fork(3)
	      -	 start	a parallel process to restore the console
	      at a crash.
       vga_setchipset(3)
	      - force chipset.
       vga_setchipsetandfeatures(3)
	      - force chipset and optional parameters.

   Inquire hardware configuration
       vga_getmousetype(3)
	      - returns the mouse type configured.
       vga_getcurrentchipset(3)
	      - returns the current SVGA chipset.
       vga_getmonitortype(3)
	      - returns the monitor type configured.

   Setting video modes
       vga_setmode(3)
	      - sets a video mode.
       vga_setdisplaystart(3)
	      - set the display start address.
       vga_setlogicalwidth(3)
	      - set the logical scanline width.
       vga_setlinearaddressing(3)
	      - switch to linear addressing mode.



Svgalib 1.4.1		 16 December 1999			4





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       vga_setmodeX(3)
	      - try to set Mode X-like memory organization .
       vga_ext_set(3)
	      - set and query several extended features.
       vga_screenoff(3), vga_screenon(3)
	      - turn generation of the video signal on or off.

   Get video mode information
       vga_getxdim(3), vga_getydim(3), vga_getcolors(3)
	      - return the current screen resolution.
       vga_white(3)
	      - return the color white in the current screen res-
	      olution.
       vga_getcurrentmode(3)
	      - returns the current video mode.
       vga_hasmode(3)
	      - returns if a video mode is supported.
       vga_getmodeinfo(3)
	      - returns pointer to mode information structure for
	      a mode.
       vga_getdefaultmode(3)
	      - returns the default graphics mode number.
       vga_lastmodenumber(3)
	      - returns the last video mode number.
       vga_getmodename(3)
	      - return a name for the given video mode.
       vga_getmodenumber(3)
	      - return a number for the given video mode.

   Drawing primitives
       vga_clear(3)
	      - clear the screen.
       vga_setcolor(3)
	      - set the current color.
       vga_setrgbcolor(3)
	      - set the current color.
       vga_setegacolor(3)
	      - set the current color.
       vga_drawpixel(3)
	      - draw a pixel on the screen.
       vga_drawscanline(3)
	      - draw a horizontal line of pixels.
       vga_drawscansegment(3)
	      - draw a horizontal line of pixels.
       vga_drawline(3)
	      - draw a line on the screen.
       vga_getpixel(3)
	      - get a pixels value from the screen.
       vga_getscansegment(3)
	      - get a list of consecutive pixel values.
       vga_waitretrace(3)
	      - wait for vertical retrace.





Svgalib 1.4.1		 16 December 1999			5





svgalib(7)	       Svgalib User Manual	       svgalib(7)


   Basic (non raw) keyboard I/O
       vga_getch(3)
	      - wait for a key.
       vga_getkey(3)
	      - read a character from the keyboard without  wait-
	      ing.
       vga_waitevent(3)
	      - wait for various I/O events.

   Direct VGA memory access
       vga_setpage(3)
	      - set the 64K SVGA page number.
       vga_setreadpage(3)
	      - set the 64K SVGA page number.
       vga_setwritepage(3)
	      - set the 64K SVGA page number.
       vga_getgraphmem(3)
	      - returns the address of the VGA memory.
       vga_copytoplanar256(3)
	      - copy linear pixmap into Mode X video memory.
       vga_copytoplanar16(3)
	      -	 copy  linear pixmap into VGA 16 color mode video
	      memory.
       vga_copytoplane(3)
	      - copy linear pixmap to some planes of VGA 16 color
	      mode video memory.

   Manage color lookup tables
       vga_setpalette(3)
	      - set a color in the color lookup table.
       vga_getpalette(3)
	      - get a color in the color lookup table.
       vga_setpalvec(3)
	      - sets colors in the color lookup table.
       vga_getpalvec(3)
	      - gets colors from the color lookup table.

   Mouse handling
       vga_setmousesupport(3)
	      - enable mouse support.
       mouse_init(3), mouse_init_return_fd(3)
	      - specifically initialize a mouse.
       mouse_close(3)
	      - explicitly close a mouse.
       mouse_update(3)
	      - updates the mouse state.
       mouse_waitforupdate(3)
	      - wait for an mouse update.
       mouse_setscale(3)
	      - sets a mouse scale factor.
       mouse_setwrap(3)
	      - set what happens at the mouse boundaries.
       mouse_setxrange(3), mouse_setyrange(3)
	      - define the boundaries for the mouse cursor.



Svgalib 1.4.1		 16 December 1999			6





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       mouse_getx(3), mouse_gety(3), mouse_getbutton(3)
	      - query the mouse state.
       mouse_setposition(3)
	      - set the current mouse position.
       mouse_getposition_6d(3),			mouse_setposi-
	      tion_6d(3), mouse_setrange_6d(3)
	      - provide an interface to 3d mice.
       mouse_seteventhandler(3), mouse_setdefaulteventhandler(3)
	      - set a mouse event handler.

   Raw keyboard handling
       keyboard_init(3), keyboard_init_return_fd(3)
	      - initialize the keyboard to raw mode.
       keyboard_close(3)
	      -	 return the keyboard to normal operation from raw
	      mode.
       keyboard_update(3), keyboard_waitforupdate(3)
	      - process raw keyboard events.
       keyboard_translatekeys(3)
	      - modify scancode mappings in raw keyboard mode.
       keyboard_keypressed(3)
	      - check if a key is pressed when	in  raw	 keyboard
	      mode.
       keyboard_getstate(3)
	      -	 get  a	 pointer to a buffer holding the state of
	      all keys in raw keyboard mode.
       keyboard_clearstate(3)
	      - reset the state of all keys when in raw	 keyboard
	      mode.
       keyboard_seteventhandler(3), keyboard_setdefaulteven-
	      thandler(3)
	      - define an event handler for  keyboard  events  in
	      raw mode.

   Joystick handling
       joystick_init(3)
	      - initialize and calibrate joysticks.
       joystick_close(3)
	      - close a joystick device.