Fractal Landscape extensions for DX by William Nell
-----------------------------------------------------------------------------

This directory contains all the C++ source code (and documentation) needed to
compile the fractal landscape extensions for DX.  To build the library
check the top "make.init" file in the "lib" directory.  It has some variables
that may need to be changed to compile the library succesfully.  The library
can be compiled as either an outboard module or a new DX executable.  By
default, it is set up to build a new executable.  To change to an outboard
module see the root "Makefile" for instructions.

To compile the library you will need a C++ compiler (g++ 2.5.8 or higher
will do just fine and other C++ compilers should work as well).  You will
also need the pnm (Portable aNy Map) libraries on your system.

After compiling the library you can invoke it using the "dx++" shell script
found in the "bin" directory.  You should set following environment variable
so it will work correctly: (otherwise it will default to ~/fractal)

	DXFRACTAL		directory where the library was built
				(e.g. ~/fractal)

Here is a brief listing of all the files and what they contain:

	Makefile		root makefile
	README			this file

	adt:			abstract data type directory
	  Makefile		makefile for abstract data type subsystem
	  Stack.h		templatized stack class
	  String.h		simple string class
	  String.c
	  Vector.h		templatized adjustable vector class
	  Vector.c
	  hash.h		templatized hash table
	  hash.c
	  shash.h		specialization of hash table keyed by char*
	  primes.c		table of prime numbers for hash table

	bin:			directory containing shell scripts and binaries
	  dx++			shell script to start up extended DX
	  all-source		count src lines in system or list all src files
	  make-dxmodules	shell script for making dxmodules.h
	  make-test-pics	script to test out different system functions

	common:			common/misc code and definitions for library
	  Makefile		makefile for common dir
	  SimpleObject.h	definition of object that provides printing
	  Object.h		extended object that supplies MOP info
	  Object.c
	  misc.h		misc definitions/declarations
	  misc.c
	  FreeList.h		class that provides fast memory allocation
	  FreeList.c
	  new.h			provides memory tracking (when activated)
	  new.c
	  timer.h		simple timer class for performance checking
	  timer.c
	  tsearch.h		templatized versions of bsearch and lsearch

	doc:			documentation directory
	  doc.html		WWW document + pictures
	  todo.txt		list of bugs and things yet to do

	dx++:			Data Explorer interface code
	  README		readme
	  Makefile		makefile for dx++ dir
	  dx++.h		C++ wrappers around common DX functions
	  dx++.c
	  dxarray.h		C++ wrapper around DX Array object
	  dxarray.c
	  dxiarray.h		specialized wrapper around irregular Arrays
	  dxfield.h		C++ wrapper around DX Field and landscape fns.
	  dxfield.c
	  dxcolor.h		C++ wrapper around DX Colormap object
	  dxcolor.c
	  dxinit.c		init. code used when built as shared lib
	  dxmain.c		main file when compiling as an outboard module
	  dxmodules.c		code for new DX modules
	  dxmodules.mdf		DX module descriptions for all new modules
	  rgbtogif.c		convert DX .rgb files to .gif

	examples:		examples of using new modules in DX
	  2dfbm.cfg		test 2d fractal brownian motion module
	  2dfbm.net
	  cloud.cfg		test cloud module
	  cloud.net
	  color.cfg		test color modules
	  color.net
	  crater.cfg		test crater module
	  crater.net
	  erode.cfg		test erosion modules
	  erode.net
	  ocean.cfg		test ocean module
	  ocean.net
	  ocp.cfg		generate a neat picture
	  ocp.net
	  planet.cfg		test planet module
	  planet.net
	  planet2.cfg		test planet module (+ warping around a sphere)
	  planet2.net
	  raise.cfg		test raise module
	  raise.net
	  ssyn.cfg		test spectral synthesis module
	  ssyn.net
	  scale-heights.net	height scaling macro
	  smooth.net		smoothing macro (using DX Filter module)
	  spherify.net		macro to warp field onto a sphere
	  test.script		script file to test different modules

	fractal:		fractal landscape code
	  Makefile		makefile
	  hmap.h		basic field class for making landscapes
	  hmap.c
	  crater.c		generate craterized fields
	  erode.c		field erosion code
	  gen.c			fbm and spectral synthesis code
	  planet.h		generate fractal planet
	  planet.c
	  cloud.h		generate clouds using functional textures
	  cloud.c		(3d clouds not completed)
	  texture.h		functional texture class
	  texture.c		(+ other unfinished textures)
	  ocean.h		simulate ocean waves (not completed)
	  ocean.c
	  perlin.h		perlin noise function & turbulence functions
	  perlin.c
	  noise.h		perlin noise function & turbulence functions
	  noise.c		(alternate & unfinished implementation)
	  main.c		main program for non-DX interface to library

	include:		directory where all includes go

	lib:			directory where all .o files go
	  make.init		common definitions for all makefiles

	math:			directory for mathematical functions
	  Makefile		makefile
	  array.h		min/max and scaling arrays of numbers
	  complex.h		complex number class
	  complex.c
	  conv.h		filter and convolution functions
	  conv.c
	  fft.h			FFT and inverse FFT code
	  fft.c
	  ftab.h		function tables for fast function evaluation
	  ftab.c
	  matrix3d.h		3d transformation matrices
	  matrix3d.c
	  plane.h		plane class
	  plane.c
	  point.h		3d point class
	  point.c
	  quadric.h		quadric surfaces (only ellipsoid for now)
	  quadric.c
	  real.h		common mathematical functions and defs.
	  real.c
	  trig.h		common trig functions
	  vector.h		3d vector class
	  vector.c

	pics:			sample pictures
	  cloud2d.gif		sample output of Cloud module
	  color.gif		sample output of TerrainColoring modules
	  crater.gif		sample output of Crater module
	  erode.gif		sample output of erosion modules
	  fbm.gif		sample output of TwoDfbm module
	  ocean.gif		sample output of Ocean module
	  planet.gif		sample output of Planet module
	  raise.gif		sample output of Raise module
	  ssyn.gif		sample output of SpectralSynthesis module

	pnm++:			C++ interface to pnm library
	  Makefile		makefile
	  pnm++.h		PNM, PBM, PGM and PPM classes
	  pnm++.c
	  xel++.h		Xel class (PNM element)

	render:			directory of simple rendering code
	  Makefile		makefile
	  color.h		simple color classes (RGB, GrayScale, etc.)
	  color.c
	  palette.h		palette class (i.e. set of colors)
	  palette.c
	  terrain.h		terrain palette class (used for landscapes)
	  terrain.c
	  light.h		light class
	  world.h		class providing simple viewing environment and
				rendering functions

For more detailed info see the source code in each directory and the HTML
documentation.


Misc Notes:
-------------------------------------------------------------------------------
  to run DX in gdb do this:

  setenv DXROOT /usr/lpp/dx
  setenv LANG C
  setenv LIBPATH /usr/lib:/lib

  rocky:~/fractal/dx++> gdb dxexec++

  Current directory is /u/cs790/nell/fractal/dx++/
  GDB is free software and you are welcome to distribute copies of it
   under certain conditions; type "show copying" to see the conditions.
  There is absolutely no warranty for GDB; type "show warranty" for details.
  GDB 4.13 (rs6000-ibm-aix3.2), Copyright 1994 Free Software Foundation, Inc...
  (gdb) run -R

  to run in script mode, add: -B < script-file

-------------------------------------------------------------------------------
If you are using the extensions compiled as a shared library you will probably
get errors about "memory corruption" from DX.