#ident "%W%" %G%
 
/**************************************************************************
# Copyright (C) 1994 Kubota Graphics Corp.
# 
# Permission to use, copy, modify, and distribute this material for
# any purpose and without fee is hereby granted, provided that the
# above copyright notice and this permission notice appear in all
# copies, and that the name of Kubota Graphics not be used in
# advertising or publicity pertaining to this material.  Kubota
# Graphics Corporation MAKES NO REPRESENTATIONS ABOUT THE ACCURACY
# OR SUITABILITY OF THIS MATERIAL FOR ANY PURPOSE.  IT IS PROVIDED
# "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
# PURPOSE AND KUBOTA GRAPHICS CORPORATION DISCLAIMS ALL WARRANTIES,
# EXPRESS OR IMPLIED.
**************************************************************************/
 
 
See also Chapter 16 on Testing Dore in the Dore Developer's Guide.


Demonstration Programs for the SGI Iris and Sunview/CXP Configurations
----------------------------------------------------------------------


-----------------------------------------------
Building and Running the Demonstration Programs
-----------------------------------------------

The demonstration programs use the same main program and the same default 
interaction controls.  The common source code resides in the directory 
dore/demo/dui.  Other directories contain code and data that are specific 
to a demonstration program.  These are:

	dore/demo/breath
	dore/demo/flag
	dore/demo/lwave
	dore/demo/trunk

Top-level makefiles, mk.iris and mk.suncxp, are provided in the dore/demo
directory.  To build the demonstrations, ensure that the following 
environment variables are set in the makefile you will be using:

	DORE_LOC	location of the dore directory
	DORE_OBJTYPE	the machine object type
	DORE_LIB_NAME	name of the Dore library to use; typically libdore.a
	
The top-level makefiles assume that the Dore library is located in:
	
	DORE_LOC/dore/lib/DORE_OBJTYPE

If this is not the case, you will need to edit the DORLIB variable in 
the appropriate dore/demo makefile. Also, you must ensure that Dore has access
to the font and error message files. If these data files were not installed
under /usr/dore/data, the shell environment variables DORE_FONTDATA and
DORE_ERRDATA must be set to the name of the directories containing the fonts
and the error message file, respectively (see Chapter 14 of the Developer's
Guide for more information).

These top-level makefiles call the makefile in each of the breath, dui, 
flag, lwave, and trunk directories, passing in the variables just described,
to actually build the code.  So, for example, to build the demonstration 
programs on an SGI Iris, do:

	% make -f mk.iris all

When a demonstration program is built, the object files and executable
will be placed in a subdirectory within that demonstration directory,
and the subdirectory will have the same name as the machine object
type specified by DORE_OBJTYPE.  For example, the object files
and executable for the breath demonstration built on an SGI Iris would
be located in dore/demo/breath/iris.

To run one of these demonstrations, cd to its directory and type runme.
For example:

	% cd dore/demo/breath/iris
	% runme

It is possible to build the demonstrations one at a time.  To do this,
change to the desired demonstration directory and ensure that the
variables DORE_LOC, DORE_OBJTYPE, DORE_LIB_NAME, and LIBS are set in
makefile before invoking it.  Then, for example, to build and run the 
lwave demonstration on an SGI Iris:

	% cd dore/demo/lwave
	% make runme
	% iris/runme



-------------------------------------------
Interacting with the Demonstration Programs
-------------------------------------------

Each demonstration program creates its own graphics window, and responds to control
characters typed in that window, followed by a <cr>.
The following controls are common to most of the demos:

	A		toggle animation
	a|a[x|y|z]	toggle rotation around axis(axes)
	b r,g,b		set background color to r,g,b
	c		toggle backface culling
	C[012]		select color map
				0: compression of RGB into 3, 3, and 2 bits
				1: grey scale
				2: 8 color intensity rams 
	d		rotate through display representations:
				surface, point, wireframe
	h		toggle specular highlights
	S number	set level of subdivision of patches, spheres, etc.
	s		toggle shading style:
				flat, gouraud
	q, x		quit
	help		print list similar to this one
	debug		toggle debug
	DRx number	rotate by the specified number of degrees in x
	DRy number	rotate by the specified number of degrees in y
	DRz number	rotate by the specified number of degrees in z
	Dz number	zoom		
	Dtx number	translate in x
	Dty number	translate in y
	Dtz number	translate in z
	Dl number	change light intensity to the specified number
	
The demonstration programs are:

breath
	A breathing cube bounces around in a box.  The breathing is accomplished
	by recomputing the geometry of the model for each time step.  After 
	computing the new geometry, the Dore model is recreated and displayed.
	Special control characters for this program:
		B		toggle cube breathe
		P		toggle cube bounce
		C		toggle cage visibility


flag
  	This program simulates a flag waving in the wind.  It is a constraint 
	based model, simulating the flag as a network of point masses connected 
	by springs, and simulating the wind as an applied force.  There is also 
	a gravitational force and the force applied by the flag pole at the two
  	attachment points.  

	In detail, the flag is actually represented as a grid of point
	masses held together with springs.  These points and springs
	follow all of the rules of Newtonian physics, but are otherwise
	left alone.  No higher level mathematics need be done to solve
	the 'flag equation', because this is a simulation, not just a
	graphical representation of a mathematical solution.

	Special control characters for this program:
		f		release flag
		1		release top of flag
		2		release bottom
		* number 	wind direction 
		W number	wind speed (between 0. and 1.)

lwave
	This program demonstrates the wave equation applied to an L-shaped
	membrane.  Each time step of the solution is calculated and displayed
	interactively.  This involves solving a series of simultaneous
	differential equations for each time step.
	Special control characters for this program:
		LM number	mode (between 1.0 and 12.0)
		LH number    	height (between -1.0 and 1.0)
		LP number	phase (between -1.0 and 1.0)
		W number	speed (between -1000.0 and 1000.0)

trunk
  	An octopus tentacle gropes around the screen like a palm frond
  	blowing in the wind.  Experience the thrill of controlling this beast.
	Special control characters for this program:
 		Ux number	x bend (between 0. and 1.)
 		Uy number	y bend		"
 		Uz number	z bend		" 
		Us number	speed (between 0. and 6.)
