--------------------------------------------------------------------------------
				GOBLIN README
--------------------------------------------------------------------------------
Created: 3/25/05
Updated: 3/05/07

Overview
--------
Goblin, an architecture for building augmented reality, virtual reality, and 3D
applications and games.  Implemented using C# and Managed DirectX.  See
"Docs\Goblin Proposal.v1.2.doc" and "Docs\Goblin Requirements.doc" for details.

There is currently one game, Botica, built using Goblin.  You can download
Botica from the Goblin website, http://www.cs.columbia.edu/~eaddy/goblin.

Requirements
------------
o Windows XP
o Microsoft DirectX 9.0c                      (required to run Goblin)
o Microsoft .NET Framework 1.1.4322 or higher (required to run Goblin)
o Microsoft Visual Studio .NET 2003/2005      (required to build Goblin)

Anti-Requirements
-----------------
Edit-and-Continue currently does not work for Goblin if it is compiled with
Visual Studio.NET 2005.  See Notes.

Installation
------------
1. Extract Goblin package (using WinZip or tar xzf Goblin.tar.gz)
2. Add <INSTALL DIR>\Common to your PATH (in System Properties->Advanced->
   Environment Variables)
3. Run INSTALL.BAT

Package Contents (THIS IS OUT OF DATE!)
----------------
\Goblin

	README.TXT    - This file
	PACKLIST.TXT  - List of files in package
	INSTALL.BAT   - Registers Patcher.dll
	TEST.BAT      - Launches Goblin and Notepad to allow the user to test EnC

	Goblin.vcproj - Goblin "Launcher" project

	\Engine - Goblin source code

		TEST.BAT    - Launches Goblin with EnC enabled
		BUILD.BAT   - Builds Goblin
		Patcher.log - Patcher log file (created when Goblin is run with
			      EnC enabled)
		Watcher.log - Watcher log file (created when Goblin is run with
			      EnC enabled)

		\BIN\DEBUG

			Goblin.exe - Goblin application
			Goblin.log - Goblin log file

	\Patcher - EnC Patcher source code (Unmanaged C++ COM object)

		README.TXT         - Patcher readme
		ENABLE.BAT         - (see below)
		DISABLE.BAT        - (see below)
		ENABLE_BREAK.BAT   - (see below)
		DISABLE_BREAK.BAT  - (see below)
		BUILD.BAT          - Builds Hello.* files and creates the bugreport
			             files needed for EnC.
		Hello.cs           - Simple console app (C#)
		Hello.vb           - Simple console app (VB.NET)
		Hello.js           - Simple console app (JScript.NET)
		Hello.jsl          - Simple console app (J#)
		Hello.cpp          - Simple console app (Managed C++)
		IlxLogSettings.xml - Log settings configuration file

		\DEBUG

			Patcher.dll - Patcher DLL

	\Watcher - EnC Watcher source code (C#)

		Watcher.exe        - Watcher application

		Watcher.exe.config - All the CodeDomProviders we've ever heard of.
                                     This determines which languages EnC supports.
                                     We've only verified support for C#, VB.NET, and
                                     JScript.NET.
\Common - Helper classes

	\ILXLog         - Logging COM object

	\ILXCrashFinder - Obtains stack trace from C++ exception

NOTE: Helper classes and projects under the "Common" directory are copyright
ILX Systems/Thomson Financial.  Redistribution of source code or binaries is
not permitted.

--------------------------------------------------------------------------------

Mapping Concerns in Goblin
--------------------------

To help understand how concerns are separated and distributed in Goblin, we have
annotated each program statement in the source code to indicate the features and
requirements the statement implements.  The following paper gives more details:

  Marc Eaddy, Alfred Aho, and Gail C. Murphy, "Identifying, Assigning, and
  Quantifying Crosscutting Concerns," in the ICSE Workshop on Assessment of
  Contemporary Modularization Techniques (ACoM 2007), Minneapolis, MN, May 22,
  2007.

We used statement annotation comments to annotate at the statement level.  This
is described by the following paper:

  Marc Eaddy and Alfred Aho, "Statement Annotations for Fine-Grained Advising,"
  in Proceedings of the Third ECOOP Workshop on Reflection, AOP and Meta-Data for
  Software Evolution (RAM-SE 2006), Nantes, France, July 4, 2006.

The Wicca# Compiler (wsc) can parse these statement annotations and generate the
metrics described in the ACOM paper.  Wsc is part of the Wicca package which you
can download from http://www.cs.columbia.edu/~eaddy/wicca.  Use the following
command-line to generate the metrics (this will also build Goblin.Engine.dll):

C:\PROJECTS\> wicca\bin\wsc.exe -nologo -concern:all -imgdir:"C:\temp\ConcernStats" -unsafe
        -r:"C:\WINDOWS\Microsoft.NET\DirectX for Managed Code\1.0.2902.0\Microsoft.DirectX.Direct3D.dll"
        -r:"C:\WINDOWS\Microsoft.NET\DirectX for Managed Code\1.0.2910.0\Microsoft.DirectX.Direct3DX.dll"
        -r:"C:\WINDOWS\Microsoft.NET\DirectX for Managed Code\1.0.2902.0\Microsoft.DirectX.dll"
        -r:C:\PROJECTS\Common\Columbia.Utilities.dll
        -r:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\mscorlib.dll
        -r:C:\PROJECTS\Wicca\Morpher\bin\Phx.Aop.dll
        -r:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.dll
        -r:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Drawing.dll
        -r:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Windows.Forms.dll
        -r:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Xml.dll
        Goblin\Engine\Engine.cs Goblin\Engine\D3DX\AssemblyInfo.cs Goblin\Engine\D3DX\dxmut.cs
        Goblin\Engine\D3DX\dxmutdata.cs Goblin\Engine\D3DX\dxmutenum.cs Goblin\Engine\D3DX\dxmutexception.cs
        Goblin\Engine\D3DX\dxmutgui.cs Goblin\Engine\D3DX\dxmutmesh.cs
        Goblin\Engine\D3DX\dxmutmisc.cs Goblin\Engine\D3DX\dxmutSettingsDlg.cs
        Goblin\Engine\Devices\InputDevice.cs Goblin\Engine\Devices\InputDeviceDriver.cs
        Goblin\Engine\Devices\InputDeviceMapper.cs Goblin\Engine\Devices\InputDevice_6DOF.cs
        Goblin\Engine\Devices\InterSense\InterSense.cs
        Goblin\Engine\Devices\InterSense\InterSenseSocket.cs
        Goblin\Engine\Devices\InterSense\InterSenseStation.cs
        Goblin\Engine\Devices\InterSense\ISDllBridge.cs
        Goblin\Engine\Physics\Collision.cs
        Goblin\Engine\Scene\Bounds.cs
        Goblin\Engine\Scene\MyMeshContainer.cs
        Goblin\Engine\Scene\SceneGraph.cs
        Goblin\Engine\Scene\Nodes\CameraNode.cs
        Goblin\Engine\Scene\Nodes\Node.cs
        Goblin\Engine\Scene\Transformers\AccelerationTransformer.cs
        Goblin\Engine\Scene\Transformers\CollisionSticker.cs
        Goblin\Engine\Scene\Transformers\CombinerTransformer.cs
        Goblin\Engine\Scene\Transformers\DXCameraTransformer.cs
        Goblin\Engine\Scene\Transformers\ICollisionListener.cs
        Goblin\Engine\Scene\Transformers\IgnoreCollision.cs
        Goblin\Engine\Scene\Transformers\InverterTransformer.cs
        Goblin\Engine\Scene\Transformers\TrackerTransformer.cs
        Goblin\Engine\Scene\Transformers\Transformer.cs
        Goblin\Engine\Scene\Transformers\VelocityTransformer.cs
        Goblin\Engine\Scene\Transformers\Xfrm.cs
        Goblin\Engine\Utilities\MyUtility.cs

The above assumes you've unzipped Goblin in C:\PROJECTS\Goblin and Wicca in
C:\PROJECTS\Wicca, and you've already built Wicca.  The references aren't strictly
necessary to obtain the concern statistics.  Make sure you fix the paths for your
machines.  "wcs -help" will explain the command-line options.

Testing Goblin and EnC
----------------------
1. Run <INSTALL DIR>\TEST.BAT. This will launch Goblin and also opens
   Engine\Engine.cs in Notepad.

The Goblin application window should appear, showing a 3D model of our Lab at
Columbia and a spinning Tiger.

2. In Notepad, search (CTRL+F) for the "OnFrameRender" method.
3. In the call to device.clear(), modify the background color from 0x00000000
   to 0x000000FF.
4. Save your changes (CTRL+S).

After about a second, you should see the background color in Goblin change from
black to blue.

5. In the "OnFrameMove" method, change the line from:

	aniFramiacs.rotationY(elapsedTime);

   to

	aniFramiacs.rotationY(elapsedTime*10);

After about a second, you should see the tiger spinning 10 times faster than
before.

Enabling/Disabling EnC
----------------------
EnC is enabled by setting some environment variables.  You should do this
from a Command Prompt instead of setting them in System Properties or
else EnC will be enabled for all managed/.NET processes on your machine.

Enabling:
1. Run Patcher\ENABLE.BAT

Disabling:
1. Run Patcher\DISABLE.BAT

Calling ENABLE_BREAK.BAT causes Patcher to invoke the Just-In-Time Debugger
via DebugBreak().  You can then put breakpoints in Patcher and debug.

Enabling debugging:
1. Run Patcher\ENABLE_BREAK.BAT

Disabling debugging
1. Run Patcher\DISABLE_BREAK.BAT

Building the Projects
---------------------
1. Open Goblin.sln in Visual Studio .NET 2003. You may see some error prompts
   which you should be able to safely ignore.
2. In Visual Studio .NET 2003, add the following directory to Tools->
   Options...->Projects->VC++ Directories->Executable files:

	<INSTALL DIR>\Common
3. Right click on Solution and select "Rebuild All"

Troubleshooting
---------------
Check Patcher.log and Watcher.log for errors.  If you make a change to a source
file that causes a compile error you'll see the error in Watcher.log.  If you
made a change that is not supported by Edit-and-Continue you'll see errors in 
Patcher.log.

Optimizations
-------------
1. Collision Detection

For LigerHunter, when many robots are displayed (~16) collision detection (CD)
functions dominate the running time:

	IsRayColliding()	- 11.9%
	IsCollision()		- 9.1%

A robot performs many CD checks: for determining its spawn point, collision
detection, collision response, obtaining random waypoints, and for determining
if the prey is in its line-of-sight (IsRayColliding).

Solution: Reduce need for CD calls. For some reason, robots keep getting
spawned inside other objects still causing them to be frozen in place.
However, many CD calls are still getting made since it triggers the collision
response.  Fixing this will reduce the calls without any penalties.

Solution: Reduce rate of non-mandatory CD calls.  This might make the robot
more sluggish and "dumber" since it won't adjust to things like collisions
and tracking the prey as quickly.

2. DirectX GC Handles

Using the DirectX Frame class causes many gcroot<> function calls to appear
high in the running time list.

Solution: Create our own Frame class.

Notes
-----
1. If you modify the Goblin project make sure you synchronize the changes with
   BUILD.BAT.  For example, if you add a source file you must update BUILD.BAT.

2. You should always build Goblin using BUILD.BAT before trying to use Edit-
   and-Continue to ensure that the Goblin.exe.bugreport file is up-to-date.

3. If you want to use a .NET profiler like Numega DevPartner Community Edition,
   you must rename or remove the following environment variables:
   
	COR_PROFILER
	COR_PROFILER_DLL
	Cor_Enable_Profiling
  
   These variables are needed to enable Edit-and-Continue but in setting these
   it prevents other "legitimate" profilers from working.

4. Edit-and-Continue will only work for Goblin if P5Glove.dll is built using the
   Managed C++ compiler from VS 2003, and if Goblin, Botica, and Engine are built
   from the command-line using the build.bat file, which uses the C# compiler v1.1.
   This is the only way to ensure that all refs target .NET v1.1.  In addition,
   Watcher and its referenced assemblies (CSharpParser) must target .NET v1.1.
   
   If you install VS 2005, you won't be able to get EnC to work because the VC++
   2003 DLL will have been removed by the VS 2005 install and P5Glove.dll appears
   to depend on it.  I keep getting:
   
   System.Reflection.TargetInvocationException: Exception has been thrown by the
   target of an invocation. ---> System.IO.FileNotFoundException: File or assembly
   name P5Glove, or one of its dependencies, was not found.  File name: "P5Glove"
   at Goblin.Apps.Botica..ctor()

--------------------------------------------------------------------------------

Release Notes
-------------

1.1
---
x Annotated every statement in Engine to indicate what requirement it implements
x Annotated every statement in Engine to indicate what feature it implements

1.0
----
x Basic scene graph support
x IS900/IS600 tracker support (direct and via network)
x Device config file
x 6DOF device abstraction
x Application plug-ins
x Transformers for controlling node motion
x Basic pathfinding AI
x Collision detection (ray/polygon, sphere/sphere, mesh/mesh)
x Basic AR experience (Lab model, tracked head-worn display)
x Basic AR game: "LigerHunter"
x Edit-and-Continue support
x Aspect-Oriented Programming support
x Prototyped Aspect-Oriented Programming
x Improve HMD registration
x Cool application icon
x AR rendering (real objects rendered black)
x Simple AI node controller (ChaseAI)
x Real objects occlude virtual objects
x Hand gesture for firing crossbow
x Support projectile weapon: "Crossbow"
x Smarter AI
x Application plugins
x Support P5 Glove
x Basic LigerHunter levels
x Screenshot

--------------------------------------------------------------------------------

TODO
----
o Goblin should be able to locate files by looking in the launch
  directory
o Support monster: "Robotica" [Erik] [Game]
	x Find model
	x Add model to scene graph
	o Animations
		x Movement
		x Attacking
		x Death sequence
		o Audio
			o Movement
			o Menacing
			o Death
		o Impact marks
	x Projectile collision detection with Robot [Erik]
		o Audio and video feedback
	o Shadows
	o Robot fires laser at player's head
	x Multiple robots [John]
x Configuration file [John] [Platform]
	o Assign tracker to node/cameras
	x Head-eye and other tracker transformations
	x ISenseServer network address
o Miscellaneous [Platform]
	o Video overlay [Benko]
	o Stereo [Marc]
	o Lighting [Erik]

Later...
o Support multiple users [Benko] [Platform]
x Aspect-Oriented Programming [Marc] [Platform]
	o Logging
	o Profiling
o Distribution by sending C# code [Platform]
o Dynamic script compilation [Platform]
o Create object hierarchy [Platform]
o Support for more devices [Platform]
o Implement another prototype using Goblin [Platform]
o Support melee weapon: "Light saber" [Game]
	o Find model
	o Add model to scene graph
	o Make Tracker #4 its controller
o Support melee weapons: "Bullwhip", "Chainwhip", "Deadly Chinese Yo-Yo" [Game]
o Support projectile weapons: "Throwing knives", "Paintball", "Snowballs",
  "Web", "Shurikan" [Game]
o Support defense: "Dune shield" [Game]
o Improve UI [Platform]
	o Voice recognition [Benko]
	o Gesture recognition [Benko]
	o 3D marking menus
	o Console overlay
o Scene graph [Platform]
	o Remove CombinedTransformaions.  Implement hierarchical
      transformations using Transformer.
    o Create graph traversal visitor method ala Studierstube (double dispatch)
	o Animation
		o Key frame
		o Skeletal
	o BSP tree
		o Bounding boxes
		o Visual culling
		o Collision detection
o Networking [Platform]
	o Message-based
	o "Agent" messages
o Plugins [Marc] [Platform]
	o Device plugins
	o Interface-based plugins
	o Autonomous plugins
	o Dynamically compiled

--------------------------------------------------------------------------------

TODO for video
--------------
o occlude player (so robots disappear when they are behind player)
o update model (so it matches current lab setup)
o have robots not collide (they spend too much time stuck together and not moving)
o camera calibration (need better registration for camera, fov, tracker offset, etc.)
o gun calibration
o have robots chase player not camera (can switch between the two)
o some bolts don't always hit the robot
o some bolts don't stick into the wall properly (they appear to stick 'inside' the wall)
o need ceiling for the lab so bolts don't go off into space
o make it easy to setup the scene
o Need sound

--------------------------------------------------------------------------------

Credits
-------
Hrvoje Benko   (benko@cs.columbia.edu)
Marc Eaddy     (eaddy@cs.columbia.edu)
Erik Peterson  (edp2002@columbia.edu)
John Waugh     (jrw2005@columbia.edu)
Sean White     (swhite@cs.columbia.edu)

IlxLog and IlxCrashFinder are copyrights of ILX Systems (Thomson Financial).

Goblin icon courtesy of Juan Manzano (www.topicons.com)

--------------------------------------------------------------------------------
