LibGGI currently includes the following targets:


========
X-target
========

Description
+++++++++++

Displays in an X window.
Emulates a linear framebuffer which is blitted to the Xserver with the
XPutImage() function. In ASYNC mode this is done when ggiFlush() is called,
and in SYNC mode it's done periodicly in the background (typicly 20 times/s).
The MITSHM extension is used when available for maximum speed.

Arguments
+++++++++

Required:
None.

Optional:
The display on which to open the X window. Default is to read the DISPLAY
environment variable.

Hotkeys
+++++++

CTRL-ALT-m	- toggle mouse-grabbing

DirectBuffer support
++++++++++++++++++++

Always.

Other features
++++++++++++++

Unaccelerated.
Multiple frames.
Panning.


===========
Xlib-target
===========

Description
+++++++++++

Displays in an X window.
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.

Arguments
+++++++++

Required:
None.

Optional:
The display on which to open the X window. Default is to read the DISPLAY
environment variable.

Hotkeys
+++++++

CTRL-ALT-m	- toggle mouse-grabbing

DirectBuffer support
++++++++++++++++++++

Never.

Other features
++++++++++++++

Accelerated if the X-server is.


============
fbdev-target
============

Description
+++++++++++

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

Arguments
+++++++++

Required:
None.

Optional:
The filename of the framebuffer target to use.  The default is to get it
from the FRAMEBUFFER environment, or /dev/fb0 if that is unset.

Additional Options:
-noinput=yes
	* Don't open any inputlibs by default.

Hotkeys
+++++++

None.

DirectBuffer support
++++++++++++++++++++

Always.

Other features
++++++++++++++

Unaccelerated, except when using KGICON.
Multiple frames.
Panning.

Examples
++++++++

GGI_DISPLAY=fbdev
GGI_DISPLAY=fbdev:/dev/fb1
GGI_DISPLAY=fbdev:-noinput=yes


============
glide-target
============

Description
+++++++++++

Uses the Glide rasterisation library to display fullscreen on a 3DFX card.

Arguments
+++++++++

Required:
None.

Optional:
None.

Hotkeys
+++++++

None.

DirectBuffer support
++++++++++++++++++++

Never.

Other features
++++++++++++++

Accelerated, one of the fastest targets when it comes to drawing-primitives.
Multiple frames.


=============
memory-target
=============

Description
+++++++++++

Emulates a linear framebuffer in main memory. This memory area can be
a shared memory segemnt, an area specified by the application, or be
malloc()ed by the memory-target itself.

Arguments
+++++++++

[-input:][shmid:<sid>|keyfile:<size>:<id>:<fname>|pointer]
	* shmid		- use existing shmid <sid>
	* keyfile	- create a new shm segment with id ftok(<fname>, <id>)
		of size <size> (preferred method !)
	* pointer	- use the memory pointed to by argptr.

IMPORTANT NOTE: 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.

Hotkeys
+++++++

None.

DirectBuffer support
++++++++++++++++++++

Always.

Other features
++++++++++++++

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 shmdemo and can be used for
things like GGI-multiplexers.

Unaccelerated.


==============
svgalib-target
==============

Description
+++++++++++

Uses the SVGAlib library to display fullscreen on a VGA-compatible card.

Arguments
+++++++++

None.

Hotkeys
+++++++

None.

DirectBuffer support
++++++++++++++++++++

Always in 320x200x8, otherwise only if SVGAlib supports linear addressing.

Other features
++++++++++++++

Unaccelerated.


=========
aa-target
=========

Description
+++++++++++

Uses the AAlib (see http://horac.ta.jcu.cz/aa/aalib/) for output and input.
Only supports 8bit palette modes.  Parses standard AA_OPTS env. var. 

Arguments
+++++++++

None.

Hotkeys
+++++++

None.

DirectBuffer support
++++++++++++++++++++

Always.

Other features
++++++++++++++

Unaccelerated.


============
multi-target
============

Description
+++++++++++

Duplicates all drawing operations on multiple `child' targets, producing
multiple indentical visuals.

Arguments
+++++++++

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.

Hotkeys
+++++++

None.

DirectBuffer support
++++++++++++++++++++

Never.

Other features
++++++++++++++

Unaccelerated.

Examples
++++++++

GGI_DISPLAY=multi:(x):(x):(x)
GGI_DISPLAY=multi:(fbdev:/dev/fb0):(fbdev:/dev/fb1)


===========
tile-target
===========

Description
+++++++++++

Emulates one big target, splitting it up into `tiles' where each tile is
drawn on separate targets (the `children').

Arguments
+++++++++

Required:
A colon (`:') separated list of tile specs.  Each tile spec is of the
form:
     <offset-x>,<offset-y>,<size-x>,<size-y>,<child>

	* <offset-x> and <offset-y> are decimal values where the tile
	  begins within the whole visual.
	  
	* <size-x> and <size-y> are decimal values for the size of the
	  tile within the whole visual.

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

Additional Options:
-usedb	  - enables  the DirectBuffer emulation.
-nodb	  - disables the DirectBuffer emulation.

Hotkeys
+++++++

None.

DirectBuffer support
++++++++++++++++++++

Depends on the -usedb/-nodb options.

Other features
++++++++++++++

Accelerated in non-DB mode if the underlying target is, otherwise unaccelerated.

Examples
++++++++

GGI_DISPLAY=tile:0,0,160,200,(x):160,0,160,200,(x)


==============
trueemu-target
==============

Description
+++++++++++

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

Arguments
+++++++++

Required:
None.

Optional: 
The target spec which to draw on (the `parent' target).  This defaults
to automatic selection (just like using ggiOpen(NULL) when GGI_DISPLAY
is not set).

Additional Options:
-parent=<mode>
-dither=<dither>
-model=<model>

      * <mode>    Force the parent target to use a specific mode
      		  (standard LibGGI mode string expected).
		  
      * <dither>  Specifies the amount of dithering. 
      		  Legal values are 0, 2 and 4, defaulting to 4.
      
      * <model>   Color model to use (only when the parent is
      		  palettized).  Legal values are rgb, cube and pastel.
		  Default depends on the parent mode.
      
Hotkeys
+++++++

CTRL-ALT-d	- change the current dithering level.
CTRL-ALT-p	- change the current color model.

DirectBuffer support
++++++++++++++++++++

Never.

Other features
++++++++++++++

Unaccelerated.

Examples
++++++++

GGI_DISPLAY=trueemu
GGI_DISPLAY=trueemu:xlib
GGI_DISPLAY=trueemu:-parent=320x200[8]:fbdev
GGI_DISPLAY=trueemu:-dither=2:-model=pastel:(multi:(x):(x))


=============
palemu-target
=============

Description
+++++++++++

Emulates palettized modes (GT_PALETTE) on another target which can only
do truecolor/greyscale/text modes or palettized modes of _higher_ depth.

Arguments
+++++++++

Required:
None.

Optional: 
The target spec which to draw on (the `parent' target).  This defaults
to automatic selection (just like using ggiOpen(NULL) when GGI_DISPLAY
is not set).

Additional Options:
-parent=<mode>

      * <mode>    Force the parent target to use a specific mode
      		  (standard LibGGI mode string expected).
		  
Hotkeys
+++++++

None.

DirectBuffer support
++++++++++++++++++++

Never.

Other features
++++++++++++++

Unaccelerated.

Examples
++++++++

GGI_DISPLAY=palemu
GGI_DISPLAY=palemu:X
GGI_DISPLAY=palemu:-parent=320x200[16]:fbdev
GGI_DISPLAY=palemu:trueemu:xlib


===============
monotext-target
===============

Description
+++++++++++

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.  

Arguments
+++++++++

Required:
None.

Optional: 
The target spec which to draw on (the `parent' target).  This defaults
to automatic selection (just like using ggiOpen(NULL) when GGI_DISPLAY
is not set).

Additional Options:
-parent=<mode>
-accuracy=<accuracy>

      * <mode>       Force the parent target to use a specific mode
      		     (standard LibGGI mode string expected).
		  
      * <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.  Defaults to 4.

Hotkeys
+++++++

CTRL-ALT-a	- changes the accuracy level (the full range may not be
		  available depending on the program's mode).

DirectBuffer support
++++++++++++++++++++

Never.

Other features
++++++++++++++

Unaccelerated.

Examples
++++++++

GGI_DISPLAY=monotext
GGI_DISPLAY=monotext:vcsa
GGI_DISPLAY=monotext:-parent=160x100[t]:-accuracy=2:fbdev


===========
vcsa-target
===========

Description
+++++++++++

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

Arguments
+++++++++

Required:
None.

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

Hotkeys
+++++++

None.

DirectBuffer support
++++++++++++++++++++

Never.

Other features
++++++++++++++

Unaccelerated.

Examples
++++++++

GGI_DISPLAY=vcsa
GGI_DISPLAY=vcsa:/dev/vcsa1


===========
file-target
===========

Description
+++++++++++

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.

Arguments
+++++++++

Required:
The filename of the file.  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.

Hotkeys
+++++++

None.

DirectBuffer support
++++++++++++++++++++

Always.

Other features
++++++++++++++

Unaccelerated.

Examples
++++++++

GGI_DISPLAY=file:/tmp/file1.raw
GGI_DISPLAY=multi:(file:/tmp/file2.ppm):(X)
GGI_DISPLAY=file:/dev/fb1

==========
sub-target
==========

Description
+++++++++++

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.

Arguments
+++++++++

None. The Argptr must contain the parent visual.

Hotkeys
+++++++

None.

DirectBuffer support
++++++++++++++++++++

Never. Maybe we add that some day ... but it's a bit dangerous ...

Other features
++++++++++++++

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.

