LIBGGI(I) LibGGI Reference LIBGGI(I) NAME libggi - A fast, simple, small and flexible user-space graphics library DESCRIPTION LibGGI is a fast, simple, small and flexible user-space graphics library developed by the GGI Project (http://www.ggi-project.org/>. It attempts to abstract the many different graphics output systems existing under Unix (and in the future, other platforms). The support for all of these different types of displays and hardware are pro- vided by dynamically-loaded mini-libraries. LibGGI can transparently (to the LibGGI-using application) display graphics on an X window, under SVGAlib, fbcon (Linux framebuffer driver), or the glide library, through their respective graphics drivers, or targets. There are also some other targets which display through another tar- get, such as multi to display simultaneously on multiple displays at once, and tile to tile your display to differ- ent monitors. LibGGI supports acceleration of graphics primitives where possible. LibGGI is a very generic piece of software, that will run on about every platform that has remotely heard of POSIX (ports to other systems such as Win32 are underway) and on many display subsystems. ENVIRONMENT VARIABLES The following outlines the environment variables, intended for the user, which affect the behaviour of LibGGI: DISPLAY If set, LibGGI assumes that you want to use the X target. This setting is overriden by the GGI_DIS- PLAY variable. GGI_DISPLAY Specifies the default target used when the applica- tion calls ggiOpen with NULL argument. The default target is specified using a target- spec: targetname [ :targetargs ] where targetname is the name of the target, and targetargs are any target- specific arguments. If neither this variable nor DISPLAY is set, then the following targets are tried in order until one works: fbdev, svga, aa EXAMPLE GGI_DISPLAY SETTINGS $ GGI_DISPLAY=aa ./flying_ggis # see ASCII art flying GGIs $ GGI_DISPLAY=multi:(Xlib:crono:0.0):(X::0.0) ./demo # see demo on both machine next door and local X at the same time GGI_INPUT_target_n GGI_INPUT_target GGI_INPUT GGI_INPUT_target specifies extra LibGII input sources and/or filters for visuals using target. Multiple inputs can be specified by enclosing each input-spec in parentheses and separating them with semicolons: (i1):... The inputs specified by GGI_INPUT_target_n are only opened at the nth call of ggiOpen. This is used for misbehaving applications that do not allow the user to specify inputs for the different targets that it opens. The GGI_INPUT variable specifies input settings for all other targets not specified using the other two variable forms. EXAMPLE GGI_INPUT STRINGS $ export GGI_INPUT=linux-mouse:auto # all targets $ export GGI_INPUT_multi=linux-mouse:auto # for multi target only GGI_DEFMODE Specifies the default mode, which is used for mode negotiation with LibGGI applications. Specifically, when GGI_AUTO or GT_AUTO are specified in a mode setting call they will be replaced with values from GGI_DEFMODE before calling the target's own ggiSet- Mode implementation. The format is: (all on one line) S <x> x <y> x <depth> V <x> x <y> D <x> x <y> F <frames> [ <scheme> <depth> / <size> ] Anything and everything can be omitted, except tokens indicating what the next token is. Any omitted values default to GGI_AUTO (or GT_AUTO for the graphtype). Whitespace and '.' symbols are ignored. Character tokens are case-insensitive. If certain values are not possible, they are overrid- den by the target. S Denotes the visible size of the visual. Totally optional, as dimensions without a specifier are considered to be the visible dimensions. <x> <y> The width (x) and height (y), in pixels. V Denotes virtual size, the total drawing area available to the application. The virtual size must be equal or greater than the visi- ble size. D Denotes the number of dots per pixel. For graphics modes, this is always 1x1, and for text modes, this is the size of the charac- ter cell. F Denotes number of frames available to the application. Applications can switch between different frames for double-buffering, etc. [ ] Delimits the graphic type. <scheme> One of: C GT_TRUECOLOR P GT_PALETTE K GT_GREYSCALE T GT_TEXT <depth> Pixel depth in number of bits. <size> Size of pixel in number of bits, including padding. Instead of scheme, depth, size, it is also possible to specify the graphtype by using one of the following: GT_1BIT, GT_2BIT, GT_4BIT, GT_8BIT, GT_15BIT, GT_16BIT, GT_24BIT, GT_32BIT, GT_TEXT16, GT_TEXT32 EXAMPLES OF GGI_DEFMODE STRINGS 640x480 just the visible size 640x480#640x960 same size, but double-height virtual screen #1024x768 only virtual size defined 80x40[T] (default-fontsized) text mode with 80x40 characters #x100[T] text mode with 100 virtual lines 640x400[8] 640x400 at 8 bits per pixel 640x480[GT_8BIT] same as above, but palettized 320x200x15 320x200[C15] 320x200 with 32768 colors (hicolor) 320x200[C16]/ 320x200 with 16-bit pixels (also hicolor) 320x200[C2432]/ 320x200[GT_32BIT] 320x200, with 32-bit pixels for 16777216 colors (truecolor) 640x480F2[GT_16BIT] 16-bit-color 640x480 with two buffers GGI_DEBUG The debugging level for LibGGI: 0 or unset debug output is off; debugging is off 255 all debug output is on You may also bitwise-or any of the following together: 2 debug core 4 debug mode setting 8 debug color handling 16 debug drawing 32 misc debugging output 64 debug dynamic library handling 128 debug event handling The debugging output can be quite verbose and in most cases you should redirect stderr so that it does not interfere with your program's output. GGI_DEBUGSYNC Turn on synchronous debugging output, flushing the output buffers before returning from GGIDPRINT calls. FRAMEBUFFER Specifies which framebuffer device file the fbdev target should use. GGI_NEWVT If set, causes a new virtual console to be allo- cated for some Linux-console-based targets (cur- rently fbdev and glide). GGI_MANSYNC_FPS This variable specifies the framerate for targets emulating synchronous mode. The default is 20fps. If you are experiencing problems with the X target over relatively slow remote connections it might be due to connection overload. You might want to try with a lower GGI_MANSYNC_FPS setting. GGI 22 August 2001 LIBGGI(I)