libggi

LIBGGI(7ggi)                                                      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



GGI                              04 July 1999                     LIBGGI(7ggi)