00-CONFIGURE -------------------------------------------- ITETRIS

This file describes configuration facilities of ITETRIS. Configuration
is specified by 'define' lines in 'tetconfig.h', found in 'src'
subdirectory.


Content.
1. Configuration arguments.
1.1  Command line options.
1.2  Shell variables.

2. Arguments, specified in tetconfig.h
2.1  Font selection.
2.2  Configuring for a different language.
2.3  Joystick support.
2.4. Setting default video mode.
2.5. Other parameters.


**************************************
1. Configuration arguments
**************************************

1.1.  Command line options.
===========================
This paragraph discusses command line arguments, used with 
'configure'

Type 'configure --help' to get the complete list of arguments.

The following arguments are the most important:

--prefix="..."

  Prefix for binaries and man page. Default prefix is "/usr/local".
  Therefore directories "/usr/local/bin" and "/usr/local/man/"
  will be used. 
  
--bindir="..."
--mandir="..."
  Directory for binaries and manual resp.
  Default values are "${prefix}/bin" and "${prefix}/man", where
  ${prefix}" is the value of --prefix argument  

--with-xbindir="..."
  Directory for X binary. If not specified, both binaries are placed
  in  ${bindir}.
  
--with-scoredir='...'
  Directory for high scores. Default: "/var/games". If you are not an
  administrator, you may wish to keep high scores locally. Use
  --with-scoredir="~" to specify your home directory for keeping scores.
  
--with-scorefile="..."
  File name for high scores, excluding path. Default "itetris.scores"      

--with-cfontdir="..."
  Console font directory (usually /usr/lib/kbd/consolefonts or
  /lib/kbd/consolefonts). If not specified, installation script
  will attempt to locate it.
  
--with-language=LANG
  Selects tetconfig_LANG.h to be the configuration file.
  SAee section 2.2 for details.  Default value: "std".  

--without-console
  Excludes console (SVGALIB) version. Typing "make' will only create
  X version. This is automatically accepted if svgalib is not installed.

--with-suidroot={auto|yes|no}
  Enables/disables 'suid root' for console version.
  --with-suidroot=auto (default) instructs configure script to use
  'suid root' depending on current svgalib version.
  X version is always built without suid root.

--without-x
  Excludes X version. Typing "make' will only create console version.
  This is automatically accepted if X11 library is missing.

--with-x=cons
  Coded as is. Selects console fonts rather than native X fonts for
  X version. See section 2.1 for details.   

--disable-joystick
  Excludes joystick support from the source code. This is automatically
  accepted, if correspnding header files are not found.


Example:
  configure --prefix="/usr" --with-xbindir="/usr/X11R6/bin" --with-x=cons --with-scoredir="~"

1.2. Shell variables
====================

The following shell variables are useful for configuration

CC - name of gcc compatible compiler.
     If not specified, the script looks for 'gcc' and then for 'egcs'.	

CFLAGS - extra flags used with the compiler.
     If not specified, assumed '-m486 -O2'.

To assign a shell variable, use 'export', 'declare -x' or 'setenv'
depending on the shell.

For example, this shell commands will configure Makefile to use 'egcs'
optimised for Pentium in 'basd' shell:

	export CC=egcs
	export CFLAGS='-mpentium -O6'
	./configure

IMPORTANT. If you changed a shell variable after configuration
and decide to reconfigure the application, use  'make wipe'
to clear the cache before starting 'configure'.


**************************************
2. Arguments, specified in tetconfig.h
**************************************

After Makefile has been created, you can continue customizing by
editing Makefile or tetconfig.h. 

Here are the hints.

2.1. Font selection.
==================

Console fonts.
--------------
The  Linux SVGAlib module supports unpacked or gzip-compressed console
fonts with  width 8 and height from 8 to 16 (height 16 is recommended).
A sample font default8x16 is included, however you most probably will
will find it with a lot of other fonts in your console font directory,
usually /usr/lib/kbd/consolefonts or /lib/kbd/consolefonts. Console
font directory is specified as 'configure' argument --with-cfontdir.
The  default  console  font  file  name is specified by  DEFAULT_FONT
parameter in tetconfig.h

An unpacked console font can be recognised by its size which is 256*h
or 256*h+4, where h is the height of the font.For example, an unpacked
8x16 console font has file size 4096 or 4100. The player also supports
compressed or uncompressed pdf fonts. Program does NOT support compound
(.cp) fonts and Unicode mapping.

If font name ends with .gz, it is treated as a gzip-compressed font,
so that guzip will be called to decompress a file to a temporary folder.
Decompressed copy will be deleted straight after processing. Make sure
that gunzip is located in a directory, listed in PATH environment string.

If font name does not end with .gz, the program tries to open it as an
uncompressed font. It the font file is missing,  .gz is appended to
its name, in attempt to find a compressed version of the font which,
if found, will be processed with gunzip,  as specified above.


ROW_DISTANCE parameter is used to specify the distance in scan
lines between rows in score table. You may need to increase it,
if you prefer a smaller font height.

The font (but not directory) can be suppressed with -F command line
argument.  See itetris manual for details.

X fonts.
--------
The X-version also support X-fonts. This is controlled by USE_X_FONT
in Makefile. Set USE_X_FONT to 0 or 1 depending on whether you want to
use console or native X fonts with X version. This parameter, however
is ignored when SVGAlib version is built.

The default X font is given by DEFAULT_X_FONT parameter in tetconfig.h
The font name can be given either in Logical Font Description (XLFD)
format (e.g. "-*-fixed-bold-r-*-*-16-*-*-*-*-80-*-*"), or as a font alias
("8x13bold").

Only X-fonts with average width 8 and height from 10 to 16 are accepted.
Fixed fonts are strongly recommended.

Use -F command line argument to redefine the font for a particular game.
(Actually you can use any keyword beginning with a small or capital F,
as -fn, -font etc.)

With X-version you can also specify font in resource string. See
USING RESOURCE SETTINGS in man page for the details.

2.2. Configuring for a different language.
========================================

The game can be configured to display text in a different language.
Look for parameters SCORE_TEXT, LEVEL_TEXT, etc in 'tetconfig.h' and
replace the text in quotes. You may wish to change the width of score
table, if your text is shorter or longer than the English equivalent,
using TABLE_WIDTH parameter (standard value 14). You should not use a value
which is more than 16 or less than 10 for the width.

You will have to select an appropriate font for a language that uses
non-Latin characters. Since some messages, such as help, scroller etc, will
still be displayed in English, it is assumed that the selected font is a
superset of the standard ASCII character set, that is all language specific
letters are located in the code range 129 - 255.

If the language, like Hebrew or Arabic, uses right-to-left writing,
you need to define RIGHT_ADJUSTMENT parameter. You may also define
TOP_SCORES_RIGHT_ADJUSTMENT parameter to use right-to-left writing
for the lines in Top Scorers list, so that the names of the top scorers
could also by displayed in the selected language.

Sample Cyrillic and Hebrew configuration files tetconfig_rus.h and
tetconfig_heb.h included.

X version allows to specify text in resource settings. See USING RESOURCE
SETTINGS section in man page for the details. 


2.3. Joystick support.
====================
Current version supports joystick through linux joystick driver.
X version can alternatively use XInput interface.

To exclude joystick support from the binary code, comment out definitions
of both JOYSTICK_DRIVER and JOYSTICK_IXINPUT in tetconfig.h, so that all
ather joystick-related parameters don't have any effect.

Joystick support is disabled automatically, in not provided by the system.
See tetris manual for using joystick in the game.


2.3.1 Using joystick driver.
----------------------------
The version 0.8.0 of the joystick driver is available from
sunsite.unc.edu, tsx-11.mit.edu and numerous mirror sites:

sunsite.unc.edu   /pub/Linux/kernel/patches/console/joystick-0.8.0.tar.gz
tsx-11.mit.edu    /pub/linux/patches/joystick-0.8.0.tar.gz

The new joystick driver is included with latest linux 2.1.xx kernels and
is also available separately from
atrey.karlin.mff.cuni.cz      /pub/linux/joystick/joystick-1.2.xx.tar.gz

This driver supports a wide range of analogue and digital joysticks,
however drivers 1.x.x up to 1.2.13 may have exhibit problems (even with
the old-style interace), especially when used in X with MOD players or
other CPU-consuming applications. The problem has been fixed in release
1.2.14, but if you can't get it, version 0.8.0 is preferred.

To include both old-style (version 0.x.x of joystick driver) and new-style
(version 1.2.8+) interfaces, code

#define JOYSTICK_DRIVER 1 

This will involve identification of current version and selecting
appropriate interace.

To include old-style interface only, code

#define JOYSTICK_DRIVER 0 

Set parameter JOYSTICK_ENABLED_DEFAULT to 0 or 1, depending on
whether the joystick support should enabled at start, if not 
explicitly specified with a command line argument or resource setting.

With the new interface, you have to specify two more calibration
arguments:

#define NEW_JOYSTICK_THRESHOLD_X xxxxx
#define NEW_JOYSTICK_THRESHOLD_Y xxxxx

It gives the minimum absolute value, that is assumed as a shift
along the coresponding axis. For example NEW_JOYSTICK_THRESHOLD_X 23000
means, that X-values in range -32768 to -23000 correspond to shift left,
values in range -22999 to +22999  to central position, and values in
range +23000 to +32767 to right shift. By increasing the value you may
fix the mentioned problem.


2.3.1 Using XInput joystick interface.
--------------------------------------

Recent releases of XFree86 comes with XInput support and
a joystick module xf86Jstk.so. Currently this module is 
a mere interface to a joystick driver (uses old style
interface and works will all drivers), and has a number of
serious bugs. Therefore curiosity appears to be the only
reason for using it.

XInput joystick support is disabled by default, and even if
it is enabled, the application will attempt to use XInput
interface only in X enviroment and if the driver could not
be used. Therefore, in order to make it effective, you
have to:

 -  Comment out definition of JOYSTICK_DRIVER and
    uncomment definition of JOYSTICK_XINPUT.

 -  Include the following lines in XF86Config:

	Section "Module"
	    Load        "xf86Jstk.so"

	Section  "XInput"
	    SubSection "Joystick"
	        Port "/dev/js0"
	        DeviceName "Joystick"
	        TimeOut 10
	        MinimumXPosition 0
	        MaximumXPosition 255
	        MinimumYPosition 0
	        MaximumYPosition 255
	        CenterX 128
	        CenterY 128
	        Delta 20
	    EndSubSection
	EndSection


Make sure that the linux joystick driver is installed, otherwise the
joystick module will crash causing application to terminate.
Set parameter JOYSTICK_ENABLED_DEFAULT in tetconfig.h to 0,
otherwise the module will crash whenever the joystick is not connected.


2.4. Setting default video mode.
==============================

In order the game to compile and work properly, you need svgalib version
1.2.10 or later.

The  latest  version  of  svgalib  can  be  found on the following
FTP sites
     sunsite.unc.edu   in   /pub/Linux/libs/graphics
     tsx-11.mit.edu    in   /pub/linux/sources/libs

as svgalib-X.X.X.tar.gz.


After the library is installed, try  'vgatest' (found in svgalib 'demos'
subdirectory, or in /usr/lib/svgalib). Try the following modes:

        640x350   16 colours (4 bit planes)
        640x480   16 colours (4 bit planes)
        640x480, 256 colours (packed-pixel, banked)

If the 256-colour mode is supported, you are recommended to use it
as your default mode. Though 16-colour mode is generally faster,
it is completely unoptimized with svgalib, so use it only if you
have no choice.

Unfortunately, quite a number of video cards are not supported
or badly supported.If the card is not recognized by svgalib,
it will automatically switch to standard VGA support, so that
you might leave the settings as they are.

However, your card may be mistaken for another type, or not
handled properly after initializing. In this case you should force
a VGA mode to be accepted by changing the value of DEFAULT_VIDEO
parameter in tetconfig.h, as

#define DEFAULT_VIDEO  VGA_MODE

Default video specification can be suppressed by -V command
line option. Consult the manual.

If you use a 16c mode, as the standard one, you may wish to avoid showing
256c pictures. Normally, in 16c mode the number of colours for a 256c image
is reduced from 256 to 16, so that the picture will look ugly.
If you comment out the line

#define SHOW_256C_IMAGE

the picture will be excluded from the binary code, so that you will also
save space.

If you use an EGA card, define parameter as

#define DEFAULT_VIDEO  EGA_MODE

so that the program will avoid any features unsupported by EGA card.
However, you may have troubles during initializing and identification.
In this case you have to edit the source code for svgalib.
A package 'egalib' is available from  'sunsite.unc.edu' in
'/pub/Linux/libs/graphics'. It is not a full package, but rather
a replacement for some 'svgalib' modules. Be careful, because
it may be designed for older versions and therefore be incompatible
with the current one. But it is a good hint anyway.

2.5. Score File Name.
===================
The directory and name of the file containing high scores are specified in
Makefile as SCOREDIR and SCOREFILE parameters resp. If directory does not
exist, it is created with 'make install' and starting file is copied with
permissions that allow every user to modify it. To run 'make install', you
must log in as 'root'.

SCOREDIR can actually start with tilde(~) to assign a relative path from
user home directory. In this case, the high scores are local to user,
and no root access is needed in order to install score file.

X-version allows to overwrite score file location with 'XITetris.scorelist'
resource line.

2.6. Other parameters.
===================
PAUSE_FILE_NAME  - Name of the file to be displayed during a pause
                   Standard name: ~/.itetris.pause
                   Can be suppressed by -P command line option.

BGLIST_FILE_NAME - Name of the file containing background music file list
                   Standard name: ~/.itetris.bgl
                   Can be suppressed by -P command line option
                   See 'Playing music in background' section in the manual
                   for details. If you do not intend to play music, set
                   #define BGLIST_FILE_NAME  NULL

TEXT_COLOUR      - Colour numbers for text, background, highlighted text
BKGR_COLOUR        and scroller text respectively.
HILITE_COLOUR      Consult 'vga_setegacolor' manual for numbers values.
SCROLL_COLOUR


COLOUR_NAME_FILE - Name of the file, containing colour names, used
                   with -C command line option.
                   This file is usually named rgb.txt and its standard
                   directory is /etc/X11. RedHat distribution tends to
                   use directory /usr/lib/X11 instead.
                   You may create another file of the similar format
                   and specify it as COLOUR_NAME_FILE.
                   Parameter is ignored in EGA mode.

COLOUR_NAME_FILE_ALT - Alternative location of file, containing colour
                   names. Used only if file specified with COLOUR_FILE_NAME
                   could not be opened. This parameter may be omitted.
                   Ignored in EGA mode.

DEFAULT_BG_RGB  -  Default colour used for background (palette number
                   is given by BKGR_COLOUR parameter, described above).

                   ""      - do not redefine palette entry; this is the
                            only available option in EGA mode
                   0RRGGBB - hexadecimal RGB colour value
                   name    - colour name from file, given as
                            COLOUR_NAME_FILE parameter
                   Can be suppressed with -C command line option.

DEFAULT_LOOP_MODE - Default loop mode for background music (see man page). 
		   1 - enable loop
		   0 - disable loop    

LOAD_DELAY      -  Delay in timer ticks (18.2 ticks = 1sec), needed to wait
                   till the tune starts.Music is played on a lower priority,
                   however the music player's priority is boosted at start
                   allowing the music file to load. The choice of delay
                   interval depends on the frequently played type of files
                   (e.g. MOD files require more time to initialize than MIDI
                   files), or type of sound card used (with GUS you have to
                   allow time needed to load MIDI patches, while you don't
                   need that for SB). For a too short interval the music
                   might never start, whereas too long interval will cause
                   considerable pauses while changing levels.

KILL_DELAY      -  Delay in timer ticks needed for a music player to
                   terminate, after receiving SIGTERM. When changing tunes,
                   this value is used as timeout between sending termination
                   signal and starting a new tune.

SCROLLER_DISABLED - Define this parameter to disable the scroller, if you
                   use a slow computer, or want to save memory: the whole
                   scroller text will be excluded from the binary code.

START_BOTTOM_DEMO - Starting bottom appearance in demo mode. Can be
                   B_SCROLLER (standard), B_HELP, or B_NONE.
                   IF B_SCROLLER is specified, when the scroller is
                   disabled, demo will start in 'Help' mode.

START_BOTTOM_GAME - Starting bottom appearance in play mode. Can be
                   B_HELP (standard), B_SHADOW or B_NONE.


