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:
[-mouse=[<mprot>[,<mdev>[,<mopt>]]]]

	* <mprot> is the mouse protocol to use:
		ms		- Microsoft
		mousesys	- MouseSystems
		logi		- Logitech
		Sun		- Sun mouse
		mman		- MouseMan
		mm		- MMSeries
		bm		- BusMouse
		ps2		- PS/2 mouse
		The default is the Microsoft protocol
	* <mdev> is the device-file to use, the default is /dev/mouse
	* <mopt> are one or more of the following:
		b<val>	- set baudrate to <val>
		d<bool>	- force enable/disable DTR line
		r<bool>	- force enable/disable RTS line

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:-mouse=microsoft


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

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

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

Arguments
+++++++++

Required:
None.

Optional:
-mouse=[<mprot>[,<mdev>[,<mopt>]]]
	* See fbdev target for description

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 segement, an area specified by the application, or be
malloc()ed by the memory-target itself.

Arguments
+++++++++

[shmid:<sid>|keyfile:<size>:<id>:<fname>|<ptr>]
	* shmid		- use existing shmid <sid>
	* keyfile	- create a new shm segment with id ftok(<fname>, <id>)
		of size <size>
	* <ptr>		- use the memory pointed to by <ptr>. <ptr> is
		expected to be a string generated by sprintf("%p").

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

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.


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

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

Duplicates all drawing operations on multible `child' targets, producing
multible 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
++++++++++++++

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

