LIBGGI(7ggi)

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 <URL: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, assumes that you want to use the X target. Can be overriden by the GGI_DISPLAY variable.

GGI_DISPLAY
    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

GGI_INPUT
    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

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 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.

    'S' 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> (x,y) dimensions, 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 graphics type.

    <scheme>
        One of:

        C   Colored

        P   Palettized (indexed-color) mode

        K   Greyscale

        T   Text (character-cell) mode

    <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[C/16]
        320x200 with 16-bit pixels (also hicolor)

    320x200[C24/32]

    320x200[GT_32BIT]
        320x200, with 32-bit pixels, 16777216 colors (truecolor)

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

GGI_DEBUGSYNC
    Turn on synchronous debugging output, flushing the output buffers before returning from DPRINT 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 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.

DISPLAY TARGETS

  PRIMARY TARGETS

X   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 ]

    display
        The X display to connect to, otherwise defaults to the display specified in DISPLAY

    -inroot
        Run in root window

    -inwin=winid
        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

Xlib
    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.

DGA 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

aa  Uses the AAlib <URL:http://horac.ta.jcu.cz/aa/aalib/>, an ASCII art library, for output and input. The standard AAlib AA_OPTS variable is parsed. Other features: DirectBuffer always available. Unaccelerated

fbdev
    Uses the Linux /dev/fb* devices to do fullscreen graphics.

    display-fbdev : [ -noinput ] [ framebuffer ]

    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.

    -noinput
        Do not open any input libraries by default.

Other features: DirectBuffer always available. Accelerated when using KGIcon or matroxfb. Multiple frames Panning

file
    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.

glide
    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:

    GGI_GLIDE_MAXFREQ
        specifies the maximum update frequency your monitor can handle (in Hz). Default is 70Hz.

    GGI_GLIDE_MAXHFREQ
        specifies the maximum horizontal frequency your monitor can handle (in kHz). Default is 48kHz.

    GGI_GLIDE_HALTONSWITCH
        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.

memory
    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 ] ]

    -input
        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.

    shmid:sid
        use existing shared memory ID sid

    keyfile:size:id:fname
        create a new shm segment with id ftok(fname, id) of size size (preferred method !)

    pointer
        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.

svgalib
    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

vcsa
    Uses the Linux /dev/vcsa* devices to render text modes onto the console.

    display-vcsa : [ -shade ] [ -ascii ] [ vcsa device ]

    vcsa device
        The filename of the device file, defaulting to /dev/vcsa which draws on the current virtual console.

    -shade
        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.

    -shade
        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

Emulation targets are those that run on top of one or more other targets.

monotext
    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 ]

    -x=accuracy

    -y=accuracy
        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.

    -a=accuracy
        Same as above, but sets both the X and Y accuracy to the specified value.

Other features: DirectBuffer never supported. Unaccelerated.

multi
    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.

palemu
    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

    -parent=mode
        Force the parent target to use a specific mode (standard LibGGI mode string expected).

    target-spec
        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.

tile
    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:...

    offset-x

    offset-y
        decimal values of the coordinates at which the tile begins within the whole visual.

    size-x

    size-y
        are decimal values for the size of the tile within the whole visual.

    child-target-spec
        a target spec. Since target specs can (and often do) contain colons, it needs to be enclosed in parentheses.

    -usedb
        enables the DirectBuffer emulation. This is the default. DirectBuffer emulation works regardless of whether the child visuals support DirectBuffer or not.

    -nodb
        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.

trueemu
    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

    -parent=mode
        Force the parent target to use a specific mode (standard LibGGI mode string expected).

    -dither=dither
        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.

    -model=model
        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.

    target-spec
        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.

  SPECIAL TARGETS

These targets can only be opened explicitly by applications; setting GGI_DISPLAY to one of these causes undefined behaviour.

sub 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.

AUTHOR
Various LibGGI hackers. Converted to DocBook and man page by Steve Cheng <steve@ggi-project.org>

SEE ALSO
env.txt and targets.txt from the LibGGI distribution for any updates to the information here. libgii(7) The LibGGI API Manual