LibGGI is a fast, simple, small and flexible user-space graphics library developed by the GGI Project. 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.
The following outlines the environment variables, intended for the user, which affect the behaviour of LibGGI:
If set, assumes that you want to use the X target. Can be overriden by the GGI_DISPLAY variable.
Specifies the default target (used when the application calls ggiOpen(NULL))
target[:targetargs]
Multiple inputs can be specified by this notation:
(i1):(i2) ...
If neither this variable nor DISPLAY is set, then the following targets are tried in order until one works: fbdev, svga, aa
Specifies extra LibGII input sources for all visuals (an opened display). See libgii(7) for details on the format.
You can also append the name of a specific target to the environment variable name to specify extra input sources for that target. For example:
$ export GGI_INPUT=linux-mouse:auto # all targets $ export GGI_INPUT_multi=linux-mouse:auto # for multi-target only
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 set-mode implementation.
The format is: (all on one line, of course)
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 number 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.
Denotes visible size, which is the area visible to the user. Totally optional, as dimensions without a specifier are considered to be the visible dimensions.
(x,y) dimensions, in pixels.
Denotes virtual size, the total drawing area available to the application. The virtual size must be equal or greater than the visible size.
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.
Denotes number of frames available to the application. Applications can switch between different frames for double-buffering, etc.
Delimits the graphics type.
One of:
Colored
Palettized (indexed-color) mode
Greyscale
Text (character-cell) mode
Pixel depth in number of bits.
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
Example 1. Examples of GGI_DEFMODE strings
just the visible size
same size, but double-height virtual screen
only virtual size defined
(default-fontsized) text mode with 80x40 characters
text mode with 100 virtual lines
640x400 at 8 bits per pixel
same as above, but palettized
320x200 with 32768 colors (hicolor)
320x200 with 16-bit pixels (also hicolor)
320x200, with 32-bit pixels, 16777216 colors (truecolor)
The debugging level for LibGGI:
debug output is off; debugging is off
all debug output is on
You may also bitwise 'or' any of the following together:
debug core
debug mode setting
debug color handling
debug drawing
misc debugging output
debug dynamic library handling
debug event handling
Turn on synchronous debugging output, flushing the output buffers before returning from DPRINT calls.
Specifies which framebuffer device file the fbdev target should use.
If set, causes a new virtual console to be allocated for some Linux-console-based targets (currently fbdev and glide).
This variable specifies the framerate for targets emulating SYNC mode (manual sync). The default is 20fps. If you are experiencing problems with the X target over realtively slow remote connections it might be due to connection overload. You might want to try with a lower GGI_MANSYNC_FPS setting.
Displays in an X window.
Emulates a linear framebuffer which is blitted to the X server with the XPutImage function. In ASYNC mode this is done when ggiFlush is called, and in SYNC mode it is done periodicly in the background (with the framerate specified by GGI_MANSYNC_FPS). The MITSHM extension is used when available for maximum speed.
display-x : [-inroot | -inwin=winid] [display]
The X display to connect to, otherwise defaults to the display specified in DISPLAY
Run in root window
Run in already-existing window with id winid
In this target, Ctrl-Alt-m toggles mouse grabbing. It will try to emulate a "relative" mouse device, i.e. one that can be moved arbitrarily far in any direction without ever leaving the window. This is useful for game controls, where loosing focus is generally undesireable. Note that grabbing must be turned off in order to leave the window.
Other features:
| DirectBuffer (direct framebuffer access) always available. |
| Unaccelerated |
| Multiple frames |
| Panning |
Uses Xlib primitives to do drawing. Faster than X target when using drawing primitives on on accelerated X server. Blitting is slower when running local to the X server.
This target has the same options and hotkeys as X target.
Other features:
| DirectBuffer never available. |
| Accelerated if the hosting X server is. |
Uses the XFree86 DGA extension to do fullscreen direct framebuffer access on X servers which support this. The bad thing about the DGA extension is that it requires root access in order to map /dev/mem, which means that you have to be root to use this target.
The display to connect to can be optionally specified. Otherwise the display in DISPLAY is used.
The environment variable GGI_DGA_FBDEV is used to specify a framebuffer device to mmap instead of /dev/mem. This allows you to use the DGA target without root privileges!
Other features:
| DirectBuffer always available. |
| Unaccelerated |
| Multiple frames |
| Panning |
Uses the AAlib, an ASCII art library, for output and input.
The standard AAlib AA_OPTS variable is parsed.
Other features:
| DirectBuffer always available. |
| Unaccelerated |
Uses the Linux /dev/fb* devices to do fullscreen graphics.
display-fbdev : [-noinput] [framebuffer]
The filename of the framebuffer target to use. The default is to get it from the FRAMEBUFFER environment, or the framebuffer associated with the current console if that is unset.
Do not open any input libraries by default.
Other features:
| DirectBuffer always available. |
| Accelerated when using KGIcon or matroxfb. |
| Multiple frames |
| Panning |
Renders an image into a file. The file can be a framebuffer device (e.g. /dev/fb0), in which case a reasonable representation of the image will be drawn on the console so long as the program's mode matches the framebuffer's mode.
Note: This target generates no input ! The multi target can be used in order to see (and control) what the program does (using a normal target) and then generate a snapshot when the program exits.
display-file : [-flushcmd="command to execute"] [-flushframe=n] [-flushtime=t] {filename}
filename is the file to render the images to. If the filename is a PPM file (has the extension .ppm), then the image will be generated at ggiClose time. Otherwise the file is a custom `GGIFILE' format and is generated continuously.
The file target can be used to generate movies from running LibGGI applications. To do this, set -flushcmd to a shell command to execute at the times given by one of the two other parameters. This looks typically like ppmtogif foo.ppm >foo.%04d.gif. The command is passed through a printf(3) which has the current count of saved frames as an argument (or rather as 10 arguments to allow a few more complex commands).
This shell command is either executed at every n-th invocation of ggiFlush or every t seconds, where t can have fractional components.
Note, that the invocation of the shell command will slow down the program, so make sure you use a reasonable value, if you use the -flushtime argument.
The primary file is updated before every invocation of the shell command.
Other features:
| DirectBuffer always available. |
| Unaccelerated. |
Uses the Glide rasterisation library to display fullscreen on a 3DFX graphics card.
The 3DFX card to use can be optionally specified as a number. (0 means the first card, 1 the second, etc.)
Environment variables:
specifies the maximum update frequency your monitor can handle (in Hz). Default is 70Hz.
specifies the maximum horizontal frequency your monitor can handle (in kHz). Default is 48kHz.
if this is set applications will be halted on console switchaway. The default is to continue running.
Other features:
| DirectBuffer never available. |
| Accelerated, one of the fastest targets when it comes to drawing-primitives. |
| Multiple frames. |
Emulates a linear framebuffer in main memory. This memory area can be a shared memory segemnt, an area specified by the application, or be malloced by the memory target itself.
display-memory : [-input] [shmid:sid | keyfile:size:id:fname | pointer]
If the "-input" option is set, an input buffer of INPBUFSIZE as #define'd in ggi/display/memory.h (default is 8192 bytes) is allocated at the start of the requested memory area. This is useful, when running on shared memory, because it enables you to use SendEvent to give input to other processes sharing that segment. This is demonstrated in cube3d and can be used for things like GGI multiplexers.
use existing shared memory ID sid
create a new shm segment with id ftok(fname, id) of size size (preferred method !)
use the memory pointed to by argptr (only available to applications calling ggiOpen).
Important: If you specify a memory area to use - be sure it's big enough as no checks can or will be made that a certain mode fits into it.
Other features:
| DirectBuffer support always available. |
| Unaccelerated. |
Uses the SVGAlib library to display fullscreen on a VGA-compatible graphics card.
Other features:
| DirectBuffer is available for the 320x200x8 mode. For other modes, support is only available if SVGAlib supports linear addressing. |
| Unaccelerated |
Uses the Linux /dev/vcsa* devices to render text modes onto the console.
display-vcsa : [-shade] [-ascii] [vcsa device]
The filename of the device file, defaulting to /dev/vcsa which draws on the current virtual console.
The -shade option turns on `shading mode', which changes the color mapping so that it chooses characters which emulate a shading effect. This makes a big improvement if using (some might say abusing :) the vcsa target for graphical purposes.
The -ascii option limits the color mapping to only using ASCII characters. The default mode uses IBM special characters (the solid block mainly, and others when using -shade).
Other features:
| No DirectBuffer support. |
| Unaccelerated. |
Emulation targets are those that run on top of one or more other targets.
Emulates palettized modes (GT_PALETTE) on another target which can only do text modes, by representing the graphics as ASCII characters. The effect is the much the same as the AAlib target, but does not depend on any external libraries.
display-monotext : [-a=accuracy [-x=accuracy | -y=accuracy]] [target-spec]
A value between 1 and 5 which determines how accurately to map the graphics to ASCII characters. Lower values are less accurate, but can represent a wider range of intensity levels.
The default is X=2 and Y=4.
Same as above, but sets both the X and Y accuracy to the specified value.
Other features:
| DirectBuffer never supported. |
| Unaccelerated. |
Duplicates all drawing operations onto multiple `child' targets, producing identical output on multiple visuals.
display-multi : {target-spec:...}
Required: A colon (`:') separated list of target specs to draw on. Because target specs can (and often do) contain colons, they need to be enclosed in parentheses.Other features:
| DirectBuffer never supported. |
| Unaccelerated. |
Emulates palettized modes (GT_PALETTE) on another target which can only do truecolor/greyscale/text modes or palettized modes of higher depth.
display-palemu : [-parent=mode] {target-spec}
Force the parent target to use a specific mode (standard LibGGI mode string expected).
Specifies the target which to draw on (the `parent' target). This defaults to automatic selection (just like using ggiOpen(NULL) when GGI_DISPLAY is not set).
Other features:
| DirectBuffer never supported. |
| Unaccelerated. |
Emulates one big target, splitting it up into `tiles' where each tile is drawn on separate targets (the `children').
display-tile : [-usedb | -nodb] {offset-x,offset-y,size-x,size-y,child-target-spec:...}
decimal values of the coordinates at which the tile begins within the whole visual.
are decimal values for the size of the tile within the whole visual.
a target spec. Since target specs can (and often do) contain colons, it needs to be enclosed in parentheses.
enables the DirectBuffer emulation. This is the default. DirectBuffer emulation works regardless of whether the child visuals support DirectBuffer or not.
disables the DirectBuffer emulation. Instead, LibGGI primitives are passed to each of the child visuals with the necessary clipping and translation. Thus, if a child visual supports acceleration, then the operation on that area will be accelerated.
Emulates tes truecolor modes (GT_TRUECOLOR) on another target which can only do palette modes or truecolor modes of different sizes/depths. Uses dithering and special palettes to get the highest possible quality.
display-trueemu : [-parent=mode] [-dither=dither] [-model=model] {target-spec}
Force the parent target to use a specific mode (standard LibGGI mode string expected).
Specifies the amount of dithering. Legal values are 0, 2 and 4, defaulting to 4.
When the target is running, Ctrl-Alt-d changes the dithering level.
Color model to use (only when the parent is palettized). Legal values are rgb, cube and pastel. Default depends on the parent mode.
When the target is running, Ctrl-Alt-p changes the current color model.
Specifies the target which to draw on (the `parent' target). This defaults to automatic selection (just like using ggiOpen(NULL) when GGI_DISPLAY is not set).
Other features:
| DirectBuffer never supported. |
| Unaccelerated. |
These targets can only be opened explicitly by applications; setting GGI_DISPLAY to one of these causes undefined behaviour.
Creates a `child' visual within a "parent". This can be thought of as a window and the sub target is intended for simple windowing systems.
No textual arguments. argptr must contain the parent visual.
Other features:
| DirectBuffer not supported. |
| Accelerated to the point of the parent. Calls are mapped through with modified clipping and coordinates.. |
| The sub target behaves a bit special with respect to the setmode call. It uses the "visible" size for the top left corner position of the window within the visual, and the "virtual" size for window width and height. Note, that moving/resizing the window does _not_ cause any drawing action. You have to perform those yourself. All it does for you is providing a virtual visual within an existing one, which is convenient to allow for window system canvases to be about any GGI program. |
| Various LibGGI hackers. |
| Converted to DocBook and man page by Steve Cheng <steve@ggi-project.org> |