
                                    libggi
                                       
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. 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
          
   Example 1. 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, 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
