(C) 1995-96 Deischinger Harald

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Cthugha-L 1.1
*************

                                                An Oscilloscope on Acid
                                                          DOCUMENTATION

                                                           August, 1997

Overview
********

What the press says
===================

   The following short quotes are about the original DOS Version of
Cthugha. Cthugha-L can do everything the original can, and a lot of
things more.

     It gives credence to the phrase 'I can see music'...There is no
     real way to describe the patterns except as weird.
   `Australian PC Review Oct '94'

     *Wavy Data*
     Upon first observation, oscilloscopes seems a bit ho-hum. After
     all, devices that graphically represent electrical waveforms on a
     display screen tend to fall a bit short on the sex appeal scale.
     But if you spend some time exploring the ways high-end
     oscilloscopes can visualize data, you may start to think the
     machines are on drugs . . .  Cthugha 5.1, an oscilloscope program
     for PC sound cards, has tuned in, turned on, and decidedly dropped
     out from the humdrum world of scientific analog signal processing.
     The product of Australian code jock Kevin "Zaph" Burfitt, Cthugha
     takes your sound card's CD, line, or microphone input and displays
     it as a swirling, hypnotic, 256-color confection for your eyes.
     Although Cthugha currently requires MS-DOS, a VGA monitor, and a
     Sound Blaster or Gravis UltraSound sound card, the complete C
     source code is part of the package, so you can port it, if you're
     so inclined.
   `WIRED 3.03 (p. 156: Music to Your Eyes)'

What does this software do then ?
=================================

   Audio input seeded image processing.  Hook up your CD player to the
input of your sound card, or use your CD-ROM player (if you've got one).
Run cthugha-L -- then play your coolest music.  -- and wow, does your
screen look like a 90's lava lamp or what?

   Cthugha 'listens' to your music, and changes the display dynamically
to the sound.

   Ever looked at an oscilloscope of your voice or of music? -- Think
of this as an oscilloscope on acid.

Who's this Cthugha dude anyway ?
================================

   *Cthugha* is hard to pronounce (Kuth-ooo-Ga), and spell.  The name
is an ancient name from the occults.  The following is an extract from
the texts that describe him (it) the best.

     Cthugha resembles an enormous burning mass continually varying in
     shape.  It dwells at or near the star Fomalhaut, from whence it
     may be called.  It is one of the most obscure and remote of all
     the Great Old Ones.
   `Call of Cthulhu - Chaosium'

   When Cthugha is summoned he is always accompanied by Fire Vampires.

     There appeared thousands of tiny points of light. ... The myriad
     points of light were living entities of flame!  For wherever they
     touched, fire sprang up.
   `The dweller in Darkness, by August Derleth'

Fast Start
==========

   Try one of these command lines to test Cthugha-L:
        No soundcard           :   cthugha -x
        Soundcard (Line In)    :   cthugha -L 100
        Soundcard (CD In)      :   cthugha -C 100

   For dispaly using X11 use `xcthugha' instead of `cthugha'.

   Once Cthugha is running, try F1 to bring up the Help Screen.

Flavors of Cthugha-L
====================

`cthugha'
     displays directly on the console. To do that it uses `svgalib'.

`xcthugha'
     This program displays the graphics using X11.

     `xcthugha' also runs in True and High Color displays, but it will
     run slower then. Currently `xcthugha' will not run on all possible
     displays.

     You can run `xcthugha' as an screen saver, if you use the option
     `--saver'.

     The screen saver allocates the sound card only if it is activated.
     You have full access to the sound card if the screen saver is not
     active. To return from the screen saver simply move the mouse, or
     press the q key.

     See the manual page for `xset', how to use a screen saver with X11.

`cthugha-server'
     This program is used to access a remove sound card. Using
     `cthugha-server' you can use one sound card for a lot of other
     machines to run Cthugha.

     Simply start `cthugha-server' on a machine with soundcard.  Then
     run Cthugha on any machine, but use the additional parameter `-N
     hostname' (1).

   ---------- Footnotes ----------

   (1)  `hostname' is the name of the machine running `cthugha-server'

Configuration
*************

   You can set a lot of options for Cthugha. When starting Cthugha
searches a lot of places for options (in the given order):

  1. Some command line options

  2. `/usr/local/lib/cthugha/cthugha.ini'

  3. `~/.cthugha.auto'

  4. `~/.cthugha.ini'

  5. `./cthugha.ini'

  6. `LIB_DIR/cthugha.ini' (LIB_DIR is specified by the parameter
     `--path')

  7. X11 resource database

  8. Command line options

Format of the entries
=====================

   Cthugha reads all the ini files, but options in later files override
option in more general files.  The format of the entries is very much
the same, as in the X11 resource database.

   The general form is: `cthugha.PROG.OPTION: VALUE' or
`cthugha.PROG.FEATURE.NAME: VALUE'.

`PROG'
     is `svga' for the console version, `xwin' for `xcthugha' running
     normally, `xsav' for `xcthugha' running as screen saver, `serv'
     for `cthugha-server'.

`OPTION'
     is the same as the long option name (see the next chapter for a
     list) without the leading dashes.

`FEATURE'
     is one of `wave', `flame', `display', `palette', `pcx',
     `translate' or `object'.

`NAME'
     is the name of one the features (palette name, wave function, ...)
     you would like to turn on or off.

`VALUE'
     is the value to use, you can leave this blank, then the option is
     not changes. For options, that don't take a parameter you have to
     use `yes' or `no' (1).

   You can use a `?' as a wildcard for `PROG', `OPTION', `FEATURE' or
`NAME'.

   The entries in the X11 resource database are the same, as in the ini
files. The app defaults file (usually in
`/usr/X11R6/lib/X11/app-defaults') is named `Cthugha'.

   For some examples see `cthugha.ini.example' in the extra directory.

   ---------- Footnotes ----------

   (1)  Or one of the many equivalent forms like `on', `off', `1', `0'

Parameters
**********

   For a short list use `cthugha --help'.

   Mose of the options can also be used in a negative form to disable
the feature. This is simply done by including a `no-' in front of the
options.

   When giving the options at the command line, you can use
abbreviations (like `--no-priv' as short for `--no-private-cmap').

Sound and CD Options
====================

   If you don't specify a special input source, Cthugha uses the current
settings. Cthugha does not change the settings back after exit. You have
to do that manually if you want that.

   You should specify at least one source of input. Where you do that
(ini-file or command line) does not matter. But if no sound source is
given, it might happen that Cthugha does not get the sound even if you
specified a volume with programs like `mixer'.

`-L, --line VOL'
     Use Line In as input with volume `VOL'. This is a shortcut for
     `--mixer line:VOL'.

`-M, --mic VOL'
     Use Mic (microphone) as input with volume `VOL'. This is a shortcut
     for `--mixer mic:VOL'.

`-C, --cd VOL'
     Use CD as input with volume `VOL'. This is a shortcut for `--mixer
     cd:VOL'.

`--mixer DEV:VOL'
     Set the mixer "device" `DEV' to volume `VOL'.  Note that things
     like "bass" or "treble" are also mixer "devices".

`-x, --no-sound'
     Debug mode (no sound-source). Cthugha uses some random noise.

`-N, --network HOST[:PORT]'
     Use `cthugha-server' running at `HOST'. If the connection should
     get lost you can reconnect by pressing n.

     You can specify the port number used by the server. You should not
     need to specify that (only if you changed it with `--srv-port').

`--play NAME'
     Use a file as source for the sound. Cthugha plays the file over
     and over again. Cthugha currently only recognizes Microsoft wav
     files - all others are treated as raw data (8 bit).

     You should also give the `--snd-fork' option when using `--play'.

`--play-silent NAME'
     Uses the file as source for Cthugha, but don't play any sound.

`--exec PROG'
     Start an external program to play the sound. That program only has
     to write the sound data to stdout, the real playing is done by
     Cthugha.  There are 2 programs included in this distribution to
     play MOD and Mpeg Layer3 files.

`--exec-silent PROG'
     Like `--exec', but the sound is not really played.

`--mod FILE'
     is a shortcut for `--exec "/usr/local/lib/cthugha/cth-nspmod
     FILE"'. This plays MOD files.

`--mp3 FILE'
     is a shortcut for `--exec "/usr/local/lib/cthugha/cth-amp FILE"'.
     This plays Mpeg Layer3 files.

`-c, --track N'
     Use CD as input, and start playing track `N'. This option does not
     change the volume used for the CD. So you also also have to use the
     `--cd' parameter.

`-v, --rate N'
     Set sample rate to `N'. The default rate is set to 44000Hz.

`-2, --stereo'
     Default to Stereo (2 channels). This is set by default.  The
     switch `--no-stereo' is equivalent with `--mono'.

`-1, --mono'
     Default to Mono (1 channel). `--no-mono' means the same as
     `--stereo'.

`--cd-stop'
     Stops CD on exit (only if CD was selected as input)

`--cd-random'
     Play tracks in random order.

`--cd-loop'
     Start again after all tracks are played.

`--cd-eject'
     Eject CD at end.

`--cd-autoplay'
     Immediately start CD.

`--snd-sync'
     Reset the soundcard after reading the sound.  You should not need
     this switch. You can try it if you have problems, but it will only
     slow things down, and might produce unwanted clicks.

`--snd-fork'
     Starts an extra process for reading from the sound card. This is
     automatically enabled with the `--play' and `--exec' options.

`--snd-fragments N'
     Sets how many sound fragments should be used. You might try to use
     a small value, like 2 or 4. (You will then get recording overruns,
     but that is normal). Simply use the default value (0 = let the
     system decide).

Startup options
===============

   All options in this section may be specified as a number (e.g.
`--flame 2'). Most may also be specified by the name of the desired
value  (e.g. `--display Up'). If you specify a name the case is ignored.

`-f, --flame N'
     Start with flame `N' (name or number).

`-w, --wave N'
     Start with wave `N' (number or name).

`-t, --translation N'
     Start with translation `N' (number or name).

`-p, --palette N'
     Start with palette `N' (number or name).

`-d, --display N'
     Start with display `N' (number or name).

`-P, --pcx N'
     Start with PCX `N' (number or name).

`-a, --table N'
     Start with table (how the palette is used by the wave function) `N'
     (only number).

`-m, --massage N'
     Start with massage `N' (only number). This defines an additional
     processing for the sound.

`-o, --object N'
     Start with object `N' (number or name). This is an 3-D wireframe
     used by some of the wave functions.

Change options
==============

   Cthugha automatically changes the way the data is displayed to the
screen after some time, and after special events. All of this features
work independent from another.

   Setting a timevalue to 0 disables the corresponding feature. All the
times are given in 1/100th of a second.

`-T, --time N'
     Minimum time before changing. Default is 500 (5 seconds).

     Cthugha will change the display after: time + rand() % random.
     Where time and random are given by this and the next option.

`-R, --random N'
     Extra random time before changing. Default is 1000 (10 seconds).

`--silence-time N'
     Time before silence change. That means that Cthugha changes the
     display automatically, when `N' 1/100sec no sound comes in and
     after that there is again sound (like the pause between two tracks
     on a CD). Default is 150 (1.5 seconds).

`-Q, --quiet-time N'
     If no sound comes on for `N' 1/100sec Cthugha displays some
     messages. Default is 500 (5 seconds).

`--fire-level N'
     Set the fire level to `N'. Default is 1000.  This controls how
     often the display is changed on beats. Lower values let the screen
     change more often.

     This is simmilar to the "beat" options in older versions of
     Cthugha.

`-l, --lock'
     Start in locked mode. That means that the display is not changed
     automatically.

`-q, --quiet-file FILE'
     Load alternate quiet messages from `FILE'. These are messages are
     display if for a long time no sound comes in.

     If a line in `FILE' starts with a `@' then Cthugha runs `fortune'
     to get a message.

`--little'
     Only change one option at a time.  You can get nice results if you
     set low values for `--time' and `--random' and enable this option.
     This way you get a constant change, but no chaos.

Disable options
===============

   Use these options to turn off some of the features of cthugha. You
might want to do that if cthugha is running too slow or use uses too
much memory.

`-i, --no-ipal'
     Disable Inbuilt Palettes.

`-e, --no-epal'
     Disable External Palettes. By default Cthugha searches for palette
     files in:
       1. `./'

       2. `./map/'

       3. `/usr/local/lib/cthugha/map/'

       4. `LIB_DIR/map/' Where LIB_DIR is specified by the parameter
          `--path'.

`-X, --no-use-pcx, --no-pcx'
     Disable usage of PCX image files.  Cthugha search for PCX files in
     the following directories:
       1. `./'

       2. `./pcx/'

       3. `/usr/local/lib/cthugha/pcx/'

       4. `LIB_DIR/pcx' Where LIB_DIR is specified by the parameter
          `--path'.

`--no-trans'
     Disable translation tables. Translation tables are used to define
     almost any affect you can think of. They are search for in the
     directories:
       1. `./'

       2. `./tab/'

       3. `/usr/local/lib/cthugha/tab/BUFF_WIDTHxBUFF_HEIGHT'

       4. `/usr/local/lib/cthugha/tab/'

       5. `LIB_DIR/tab' Where LIB_DIR is specified by the parameter
          `--path' and BUFF_WIDTHxBUFF_HEIGHT is the size of the buffer
          in dezimal (e.g. 320x200).

`-s, --no-flashlight'
     Disable usage of Flashlights. When Flashlights are enabled Cthugha
     can change the colors used based on the frequencies of the
     incoming sound. A lot of loud low frequency parts will change the
     colors with a low index, while a lot of high frequency parts will
     change the colors with a high index.

     You should turn off this feature, if you run Cthugha with
     `--no-private-cmap', because then changing the palette takes very
     much time.

     This feature was called FFT in version 0.8 of Cthugha-L.

`-F, --no-fft'
     Disable usage of FFT. Cthugha can compute the FFT of the sound
     data and draw that instead. The current implementation is not very
     efficient, so computing the FFT takes quite a long time.

     This is different from FFT in version 0.8 (see flashlight).

Display and Buffer options
==========================

   If you think Cthugha is too slow or too fast :-) you can change the
size of the display. Larger buffers and lager displays take more time
for computation and display.

   This is done by the parameters `--disp-mode' and `--buff-size'. Both
require an argument. You can specify a small number for a predefined
(common) resolution. See `cthugha --help' for available sizes.  Or you
can specify a completely different size by giving width and height
(e.g. `--buff-size 410x630').

   Special disp-mode values only work with the X11-version and are
ignore by `cthugha'.

   I recommend a display size that is at least twice as wide and high
as the buffer (e.g. 320x200 buffer and 640x400 display).

   Not all wave and display functions work on all resolutions. If the
resolution is too small than the next wave/display function is used.

`-D, --disp-mode MODE'
     Set graphics mode. Default is 0 (320x200). This option also works
     with X11. The drawing area is set to the specified size.

     When using X11 you can also specify a special resolution in the
     from: WIDTHxHEIGHT.

     Available predefined modes:  0:320x200  1:320x240  2:320x400
     3:360x480 4:640x480  5:800x600  6:1024x768 7:1280x1024 8:1600x1200

     When running as screen saver or with DGA support `xcthugha' will
     only use the part of the screen, that you specify with this option.
     So you can have a (physical) screen size of 1280x1024, but display
     only with 800x600.

`--mit-shm'
     Use the MIT Shared Memory Extensions when displaying with X11. This
     option brings an significant increase in speed.

     This is option is enabled by default. You should only deactivate
     it if you have problems.

`--disp-direct'
     Display directly to screen. This is disabled by default.

     For `cthugha' this is available only in 320x200-mode.  For
     `xcthugha' this has an effect only when using DGA. Having a linear
     frame buffer and no hardware double buffering.

     Using this options can increases the speed, but it can also
     decrease the speed, simply try out what is true for you.  Some
     flicker occurs when text is displayed.

`--dga'
     Enable the support for the DGA extensions. DGA is an XFree86
     extension to allow direct frame buffer access. You need XFree86
     3.2 or newer for this to work.

     You need root privileges to use DGA.

`--no-buff, --dga-soft-buff'
     Force software double buffering with DGA. This can be faster than
     the hardware buffering enabled by default.

`-r, --sync'
     This option causes `cthugha' to wait for a resync before the buffer
     is displayed on the screen. So screen update and video refresh are
     synchronized. `--sync' causes a slight decrease in speed.  With
     `cthugha' this option is disabled by default.

`-S, --buff-size SIZE'
     Set the buffer size. Default is 320x200.  (1)

     Available predefined modes:  0:160x100  1:320x200  2:320x300
     3:360x480 4:640x480

     You can also specify a special mode in the form WIDTHxHEIGHT.

`--tile, --tile-x, --tile-y'
     Tile the buffer to screen horizontally and vertically, or only one
     of the two.

`--mirror, --mirror-x, --mirror-y'
     Mirror the buffer to screen horizontally and vertically, or only
     one of the two. By default mirroring is allowed, but Cthugha won't
     do from the start on. By explicitly using on of this options
     Cthugha will start mirroring. Using this in the `no-' form will
     disable mirroring.

`--text-time'
     Set the time after which some text (like silence messages) is
     automatically removed from the screen.

`--on-root, --in-window'
     With `--on-root' `xcthugha' draws on the root window instead of a
     window. `--in-window' forces to draw in a window. `--no-on-root'
     is a synonym for `--in-window' and `--no-in-window' is a synonym
     for `--on-root'.

`--private-cmap'
     This options has only an effect when running under X11 with 256
     colors.  If `--private-cmap' is enabled (this is the default)
     Cthugha uses an own colormap for display. To see the correct colors
     you have to move the mouse over the display window.

     When disabling the private colomap, you should turn off the
     flashlight support `--no-flashlight'.

   ---------- Footnotes ----------

   (1) Note that in older version of Cthugha the last 4 lines of a
buffer were not displayed to the screen. The default size there was
320x204. Tab files for the original DOS version are 320x204.

General options
===============

`--stretch'
     Allow stretching of translation tables to fit buffer size.  With
     this option you no longer need to recreate the tab files for every
     different buffer size you use. Of course a table created for the
     desired size looks better than a table stretched to that size.

`-E, --path LIB_DIR'
     Specifies an additional directory where to search for tab, map and
     pcx-files. Cthugha also searches for an ini file
     `LIB_DIR/cthugha.ini'.

`--dbl-load'
     Allow loading of 2 or more palettes, translation tables or PCXes
     with the same name.  By default Cthugha will not load such a file
     if it already loaded one of the same name.

`--save'
     Save current wave, flame, display and some more things  at end.
     Also saves the buffer last on screen. With `--pcx FILE' you can
     resume you cthugha-session if you specify the saved file there.

     The settings are saved in the file `${HOME}/.cthugha.auto'.

     `--save' does not save the display but the buffer. There is a small
     difference.

`--prt-file FILE'
     File used to save screen at PrintScreen or with `--save'. If you
     save more than once Cthugha automatically appends a number.  So
     the first saved file is `FILE', the second is `FILE.1', the third
     is `FILE.2' and so on.

     When Cthugha is running you can save the current display by
     pressing #.

     *WARNING:* Using the PrintScreen key can causes a quite dramatic
     crash.

`--no-esc'
     If this option is given then the esc-key is ignored.  You should
     no longer need this switch, I still keep it just in case.

`--verbose=LVL'
     Set the amount of extra information to print. The higher `LVL', the
     more information. The parameter is optional. Using only `--verbose'
     sets a level of 3.

`--saver'
     Run `xcthugha' as screen saver.

`-?, --help'
     Print help information.

Server options
==============

`--server'
     Starts `cthugha', `xcthugha' in server mode. In this mode the
     programs can also accept connection like `cthugha-server'.

`-E, --srv-wait'
     Time to wait after the saver sent the sound to its clients. The
     time is given in 1/1000 of a second. The default value is 0.1
     second.

     If you set a high value here `cthugha-server' send not so much data
     of the network. But if the value is too high, not enough data is
     sent (the clients have to wait - delays in the display). On the
     other hand if you set a very low value very much data is sent -
     waste of resources.

`--srv-port'
     The port used by the server (`cthugha-server' or
     `cthugha'/`xcthugha' in server mode).

     Default value is 5555. You should change this only if you have
     problems. Don't forget to specify this port also for the clients
     accessing the server (with `--network').

`--clt-port'
     The port used by the clients to receive sounds from the server.
     The default value is 5556. The clients use the port specified and
     the next one.

     You can use this option to use more than one client on one machine
     (e.g. `xcthugha-saver' and `xcthugha' at the same time).

Keyboard Commands while running Cthugha
=======================================

   Sometimes there are problems with function keys. You can alway use
the normal number keys instead of the function keys. Pressing `1' is
the same as pressing `F1'.

`F1 ?'
     Help

`F2'
     Select Display

`F3'
     Select Wave

`F4'
     Select Flame

`F5'
     Select Translation

`F6'
     Select Palette

`F7'
     Select PCX

`-/+'
     Drop/Increase the sample rate by 1000Hz

`</>'
     Drop/Increase the noise threshold (blanking level)

`a'
     Write current setting to INI file

`w/W'
     Next/prev wave function

`f/F'
     Next/prev flame function

`p/P'
     Next/prev palette

`b/B'
     Next/prev table (how it uses the palette)

`d/D'
     Next/prev display function (up/down etc)

`t/T'
     Next/prev Translation Table

`m/M'
     Next/prev Massage the audio (figure that one out!!)

`g'
     Change the offset-table for the general flame functions

`<space>'
     Randomally changes something (maybe the same)

`l'
     Lock modes (No random switching)

`c'
     CD player interface/ sound control panel

`*'
     Stereo/Mono toggle

`s'
     Toggle Flashlight

`e'
     Toggle FFT

`x/X'
     Test PCX (displays next/prev)

`n'
     Reconnect to `cthugha-server'

`i'
     Information about current display-parameters (toggle)

`#'
     Print Screen. Saves the currently displayed picture to a file.

     *Warning:*  Using the Print key can cause a quite dramatic crash.

`<esc>/q'
     Remove text from screen or Exit if no text is on screen.

     <esc> does nothing if `--no-esc' is given as option.

Installation
************

Packages
========

   Cthugha-L is split into 3 packages:

`cthugha-L-1.1.src.tgz'
     This package holds only the source. You have to compile everything
     yourself.

`cthugha-L-1.1.bin.tgz'
     This package also holds the precompiled binaries and the
     documentation as postscript file.  The precompiled binaries are
     compiled with gcc-2.7.2.1 for ELF.

`cthugha-L-1.1.xtr.tgz'
     The extra package contains a lot of palettes, translation tables
     and pcx-files.

Configure
=========

   Before compiling Cthugha-L you might want to specify some setting in
the file `configure'. You should not change any of the `Makefile's.

   You should set, where to install Cthugha to, and set the places where
Cthugha searches for header files and libraries.

   If you want to compile Cthugha-L for a non-Linux system you can use
the `USE_' options in that file. You propably have to turn off most
things.

Make
====

   After you have set everything in the file `configure' you can run
`make' to really generate the programs, the documentation and the
translation tables (1).

   You can already now try out Cthugha. Try running Cthugha with the
option `-E ./extra', so that Cthugha can find the translation tables.

   ---------- Footnotes ----------

   (1) Since version 1.0 Cthugha generates the translation tables when
it is starting. But some translation tables are so complex, that that
method would take too much time, so they are generated the old fashion
way.

Install
=======

   If Cthugha compiled successfully you can run `make install'.  This
copies all the files to the right places (as specified in `configure').
You should do that as root. `make install' tries to set all the
necessary file rights.

Uninstall
=========

   If you want to get rid of Cthugha (I don't know why that could
happen) you can remove it by running `make uninstall'.  The entry in
the file `/usr/info/dir' is not removed automatically.

Problems you might have
=======================

*The compiler complains about missing header files.*
     Check the settings in `configure'.

     If the missing file is `ncurses.h', but you have a header file
     named `curses.h' than that file will be good enough.

*gcc can not find some libraries.*
     Check if the paths in `configure' are set correctly.

     A problem (I have it sometimes) with shared libraries is, that you
     don't have the "library without version number".  For example if
     you have `libXaw.so.6' and *no* `libXaw.so' you should add a link
     with
                    ln -s libXaw.so.6 libXaw.so

     You should add such links for all your shared libraries.

*gcc still can not find some libraries.*
     Check if you have installed `svgalib' and a new version of
     XFree86. `xcthugha' needs XFree86 3.2 (or newer) for all the
     features to work. For older versions you have to disable some
     things, especially the DGA and screen saver support.

Technical Stuff
***************

General Stuff
=============

   * I've testes Cthugha-L with a SoundBlaster 16. Cthugha-L should work
     with (almost) every soundcard supported by Linux.

   * You CD-ROM *must* be connectd to your soundcard. It is not enough
     that it can play audio CDs. The important thing is, that the
     computer get's the sound data.

     If there is a small audio cable (inside your computer) from your
     CD-ROM to your Soundcard it should work. If there is no such
     connection the only chance left is the program `cdda2wav' (by Heiko
     <`heiko@colossus.escape.de'>). That program reads the audio data
     from the CD and stores it to your harddisk. You can then use that
     data with the `--play' option.

   * Cthugha-L is my first real program for Linux. So there are some
     things I don't know. Especially about the network code I'm not
     100% sure everything is done the right way. The same is for the
     X11 code.

     There may also be some problems with the CD-ROM code. If someone
     has a problem with a drive and/or knows how to fix it - please
     tell me.

     Of course, if you have any other ideas, changes or problems send
     me a mail. I'm happy about every response I get about Cthugha-L.

Palette Files
=============

   The format is the same that `fractint' uses.  If not all color
indexes are specified then they default to black.  The color values are
specified in RGB tuples (0-255), where 0 is black -- one line per color
index.  Easy !

     255 255 255 comments index 0
     ... ... ...
     255 255 255 comments color index 255

   If you come up with a good palette file, email to me
(`k3096e5@c210.edvz.uni-linz.ac.at').

Translation Tables
==================

   These tables (TAB files) are used to design just about *any* effect,
without recompiling the source to Cthugha!!!

   Since version 1.0 you can use the translation table in 2 different
ways.  Cthugha can generate the table when it is starting, or you can
generate the tables in advance. The later is used for tables, that take
very long (or for which you don't have the source).

   To create the default Translation tables you can use the shell script
`mktab.sh'. Call it with with the desired buffer size as parameters
(e.g. `mktab.sh 640 200') and wait.

   Some of the program to create the translation tables have quite a
lot of options, experiment with them - if you create a new nice
translation table send me the options you used (or the modifications to
the code you made).

Here's how they work
--------------------

   This is a bit technical. You need this part only if you want to
write new translation-table-generation-programs (nice word, isn't it).

   You generate a table, `BUFF_WIDTH'x`BUFF_HEIGHT', of integers.  The
integer represents the *source* pixel for this *destination* pixel.  In
other words: The numbers specify where each pixel comes from.

     e.g  in a small 3x3 world, to rotate to the left.. 
     
     1, 2, 0,   so pixel 1 is moved to position 0, and so on
     4, 5, 3,
     7, 8, 6

   What kind of integers are used (`short' or `long') depends on the
size of the buffer (If > 64k longs are used). `tint' and `utint' are
defined in `cth_buffer.h' to give you the right kind of integer to use.

   Read the source of some `mk*.c' files to try to work out how it
works, or send me some email!

tabheader, tabinfo
------------------

   Since version 0.3 Cthugha uses an improved format for tab-files.
The new format starts with a header (`tab_header' defined in
`translate.h').

   You can convert (add the header) old tab-files to new ones by using
`tabheader'. To display the header use `tabinfo'.

   Usage of `tabheader' and `tabinfo':

     tabheader [in-tab-file] [size-x  size-y] [description] > [out-tab-file]
     tabinfo [tab-file]

PCX Files
=========

   PCX files are pictures uses by Cthugha. They are display from time to
time when the display is changed. You can also force the next PCX to the
screen by pressing X. Cthugha also uses the palette stored in a PCX
file.

   For information about the format of such an image, read a book about
file formats. PCX is a very simple form of saving pictures, it is used
mainly for historic reasons (the DOS version used it). Maybe in future
versions also other file formats will be supported.

Contact/Legal
*************

   * *Mail*.

     Forward messages/postcards/CDs/money to me:

          Deischinger Harald
          Am Edhuegel 45
          4115  Kleinzell
          AUSTRIA
          
          email: `k3096e5@c210.edvz.uni-linz.ac.at'
          WWW: `http://www.geocities.com/CapeCanaveral/Lab/6386'

   * *WWW-Page*.

     The official Cthugha WWW Page is `http://www.afn.org/~cthugha'.
     This gives you a lot of information about Cthugha in general, Zaph
     and also some other related material.

     This page is maintaned by Jeff The Riffer
     (`riffer@freenet.ufl.edu').

   * *Newsgroup*.

     The official Cthugha newsgroup is `alt.graphics.cthugha'.

   * *FTP*.

     You can get Cthugha-L from the following sites:
            ftp.afn.org           /cthugha
            sunsite.unc.edu       /pub/Linux/apps/sound

     `ftp.afn.org' holds all the Cthugha material available. There you
     can also find Cthugha for other platforms.

   * *SHAREWARE*

        * Free for non-commercial use  -  Send a Postcard to show your
          appreciation If you have more money than you know what to do
          with, then send me a CD of something you like listening to
          with Cthugha on the screen...

          Really, there's no point sending me a cheque for $20-$30,
          because its going to cost to get it cashed anyway, and I'd
          probably go out and buy a CD with the money, so - if you want
          to send more than a postcard,  why not just send a CD instead
          ??

        * Commercial users register for US$50 (you can also use another
          currency) or send 2 CDs.

        * If you can't afford to register send a video tape (PAL
          preferably) of public performance or send a postcard :-)

        * If you forward this program on to friends, make it available
          on a BBS, etc please include all the document
          (un-adulterated).

        * If you run a shareware house/store, the disk you sell this
          program on is not allowed to be sold for more than US$20.

   * *DISCLAIMER* this software is provided 'as is' without warranty of
     any kind implied or expressed.

   If it works, great.  If it doesn't, then that's your bad luck - send
us some mail and we will try to fix it.

Other Things
************

Other Operating Systems
=======================

   You can find the other versions via the Cthugha home page
`http://www.afn.org/cthugha'.

   * *DOS* - Cthugha V5.1 and V5.3

     This version of Cthugha-L is based on cthugha V5.1 and V5.3 by
     Kevin Burfitt. Most things from the DOS-version work exactly the
     same way in the Linux-Version.  Cthugha-L has a lot of additional
     features.

   * *PowerMac* - MaCthugha

     Rus Maxham (`rus@interstice.com') has done a port of Cthugha for
     the PowerMac.

   * *xf86cthugha*.

     A special version of Cthugha-L supporting DGA (Direct Graphics
     Access) with XFree86.

     Mark Vojkovich (`mvojkov@ucsd.edu') has done this version. You can
     also find it at `ftp.afn.org' or via the WWW page.

     DGA support is now fully integrated into this distribution. You
     can use `xcthugha --dga' to enable this feature.

   * *Win95*.

     Kevin Burfitt (`zaph@torps.apana.org.au') is currently working on a
     new version of Cthugha for Windows 95.

Good CDs to watch
=================

   *The Cure*; *Dire Straits*: Brothers in Arms; *Ella Fitzgerald*:
really!!, the 20's songs - trp@Cs.Nott.AC.UK; *Enigma*; *Enya*:
Excellent with all white palettes - jsee+@andrew.cmu.edu; *Nine Inch
Nails*; *Peter Gabriel*; *Pink Floyd*: The Dark Side Of The Moon,
Momentary lapse of reason, actually, anything by Pink Floyd will do...;
*Orbital*; *Smashing Pumpkins*; *Metallica*: Orion - use the crawling
worms mode :-) Use Lightning for most tracks, And Justice for all;
*Hendrix*; *Manic Depression*; *Pete Namlook*; *Klaus Schulze*;
*Kraftwerk*; *Aphex Twin*; *The Church*; *Future Sound of London -
Lifeforms *; *Violent Femmes*; *10,000 Maniacs*: Our time in Eden;
*Eagles*: Hotel California; *Ice Cube*: The Predator; *Dr Atmo and the
Basalt Boys*: The Whole Traffic; *Frank Zappa*: Guitar I, II and III;
*Amorphus Androginous*; *Yello*: Essential Yello

TIPS
====

*How can I register Cthugha ?*
     You can send me a postcard, its all I ask...  if you have too much
     money and don't know what to do with it, then send me a CD of
     something that looks cool with Cthugha!

     If you write your postcard in German (or some other language having
     *Sie* and *Du*), please use the *Du* (I'm not that important).

     Please send me more postcards!

*I think I found a bug - what can I do ?*
     Please mail me and tell me about it, I will try to fix it.  It can
     always happen that I miss something when I release a new version.

*I can't remember how to spell CTHUGHA.*
     Well here's how Zaph remembers:
       1. It starts with a 'C'

       2. It's got the word 'THUG' in it

       3. Followed by 'HA'
          Easy, really (You'd be surprised how many permutations we get)

*`xcthugha --saver', `xcthugha --dga'*
     `xcthugha' has some problems getting the correct colors, when
     running under certain window managers. Now I found a workaround
     for that problems.

     There is only one thing you should do: Set your window manager so,
     that it does not decorate the windows named "xcthugha-saver" and
     "xcthugha-dga".  Take a look at the manual of your window manager,
     how to do that.

     It is possible, that this is not working for some very strange
     window manager. If you have any problems (or a solution) please
     tell me about it.

*So you want to add/modify the source code*
    *Rule #1:*
          Go for it!!!  This is a free project - make it big!

    *Rule #2:*
          Send me some Email telling me which bits you are playing with,
          and I will keep you up to date if I (or anyone else) make any
          major changes to the code.

    *Rule #3:*
          Put your name/email address in the code, that way you get to
          share the fame :-)

    *Rule #4:*
          There is no Rule #4

    *Rule #5:*
          *Please* keep me up to date, with any little functions or
          ideas you have... The program is evolving quickly, and I'd
          love to incorporate your ideas!

    *Rule #6:*
          Translation tables: If you design a weird and wonderful
          translation table, send me either the table or (even better)
          the code used to generate it!

    *Rule #7:*
          Don't Panic

*When using FFT,*
     don't set the sample rate too high (not higher than 22000 Hz).
     Many sound sources (radio) don't have any frequency parts above
     that limit -- so half of FFT buffer will be a flat line.

*How to show Cthugha on the wall?*
     There are a lot of methods for doing that.
    *Video projectors*
          Like a dia projector, only that you connect your computer and
          look. This is expensive.

    *Overhead projectors*
          Special device you connect to your computer and use with the
          overhead projector.  Also expensive.

    *Warper*
          Build your own projector device. See the included text file
          `warper.txt' (by Noah Spurrier). This is cheap.

*Some more tips*
        * You can use all you map files from fractint.  Most are
          included in the extra distribution.

        * Use "strange" buffer sizes. 1024x70 is good as a screen saver
          for a slow machine.

        * Send me a postcard. I have received not too many so far.

