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 provided 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 target,
such as multi to display simultaneously on multiple displays at
once, and tile to tile your display to different 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_DISPLAY variable.
GGI_DISPLAY
Specifies the default target used when the application 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
ggiSetMode 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 overridden 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 visible 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 character 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 allocated for some
Linux-console-based targets (currently 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.
