Computer Graphics Final Project (91.427)
========================================

Project Group Name: The Red Menace 

Members:
	Dan Brook
	Austin Veino
	Dan Scanlan
	
---------------------------
 Quick Summary of Features
---------------------------
  * Load any 3DS file at runtime by giving a path to that object (argv[1])
    For example:

       ./finalproject models/Ackbar/Ackbar.3DS

  * Control the distance of the model / scene from the viewport with the
    scroll wheel, or for really large scenes like the house example, use 
    + and - keys to increment that displacement at larger intervals. This
    is designed to limit overall frustration (not only when testing!)

  * Control the position/rotation of the model with left/right click-and-
    drag, as well as move the field of view with W (up), S (down), A (left),
    and D (right) so you can zoom into the more interesting parts of a scene.

  * Change the scaling of the loaded model with the Scene Scaling Factor
    spinbox. BUG: Unforunately right now, this impacts lighting somewhat,
    scaling UP makes the object darker, and down makes it blindingly light.

  * Choose either perspective (frustum) projection or orthographic so see
    the stark difference between the two.

  * Reset the scene to the as-initially-loaded state. We had discussed that
    this was a nice thing to do for when you've been playing with a scene
    long enough and want to get to a fresh state.

  * Turn light sources on and off, as well as add/subtract colors from the 
    left side and right side of the scene with slider widgets. 


-------------------------------
 Detailed Project Introduction
-------------------------------
This application will open any 3ds model and allow the user to pan around
it, change colors, and toggle / mutate light sources that impact the object.
The window that spawns at run-time is dominated (size-wise) with an OpenGL
frame buffer called a QGLWidget (a framebuffer encapsulated within a window).
This allows us to have the comforting features of familiar GUI controls, while
also being able to interact with a 3d environment and any scene in it.
The mouse can be used to click and drag within the scene to change its
rotation, and the sliders to the right use "signals" from the window to 
reflect the current value of the rotation parameters. 

The interface has been extended to be able to load ANY .3DS -type model that
the user wants to send at it! To run, simply execute:

     ./finalproject path/to/the/model.3ds

This project builds on its predecessor, using similar lighting controls
because they were deemed rather neat last time. We've extended the Qt-based
interface to be able to choose perspective or orthographic projection ON THE
FLY, which is really just project #2 but in a new twist. Because the
projection matrices and configuration are updated with the widget resize
handler, we've done a little bizarre trickery to accomplish the proper
reactions with the projection selection (calling resize() with the current
window sizes ... sneaky, no?)

You can now use the scroll wheel to pull a scene closer and push it farther
away. This feature was desperately needed with the advent of runtime model
loading (because some are huge and some are tiny, it depends on the creator).
Additionally, W will move the buffer window clipping area UP, S will move it
down, A will move it left, and D will move it right. This is made to look
smoother by using a QTimerEvent to loop quickly in very small intervals,
rather than the evil way of using OS-dependent keyboard repeat rates to do
this.

Lastly, because of oddities when it comes to mutating the display frame a
bunch of times, a reset button has been included to "put Humpty Dumpty back
together again".


---------------------------------------------------------
 A quick summary of the ins-and-outs of the Qt Framework
---------------------------------------------------------
Qt is a C++ based widget and application framework for designing cross-
platform GUIs. If you have used VLC then you've used Qt.

The chief advantages of Qt are its open source licensing, cross-platform
building and runtime environments, widget styling that matches that of
the targeted build system, and a robust system of event handling known 
as signals and slots, which allow multiple-path communication between 
objects and their controllers.

Now where does OpenGL (this is a graphics project after all) fit in here?
Qt provides a widget called QGLWidget, which is essentially its very own
OpenGL frame buffer that can be embedded into a graphical application. 
What's great about this is that anything involving menus, controls, or
other text in a pure-OpenGL system is far too difficult by itself, but
by using a framework under which the frame buffer will sit, we can (in
theory) build a more interesting/robust application. Additionally, 
starting from scratch using an entirely different approach than the Angel
code does will make using C++ and its actual object-oriented approach a
little more sane and easier to code under source control like GitHub.


----------------------------------------------
 Some broad project goals (by no means rigid)
----------------------------------------------
Implementing [some of] the following ideas are possibly within our grasp!

 - Use the mouse to change looking direction (up/down, left/right)

 - Add a set of controls for additional light source(s)

 - Have the application take an argument or use a widget to place a file
    name (of a .3ds file) and load it up into the frame buffer using lib3ds.

 - PLATFORM INDEPENDENCE! -- With the exception of lib3ds, the entire project
    has only mere Qt dependencies. You'll see in the .pro file that the only
    external library linked against is lib3ds, which is available freely
    at: http://code.google.com/p/lib3ds/. However, it's packaged in most
    GNU/Linux systems and is available on macports with [relatively] little 
    pain.


------------------------
 Getting up and running
------------------------
Due to timing constraints, we have limited functionality to the GNU/Linux
platform. Installing lib3ds in this environment is very simple in almost every
distribution we've looked at. So combined with having the Qt development
headers, building is very simple.

On Debian, for example, you'll have to:
     apt-get install lib3ds-dev
     apt-get install libqt4-dev

Now, onto the building instructions...


-----------------------
 Building from scratch
-----------------------
Upon the initial cloning of the repository you will simply need to run
'qmake' from the project directory itself. The qmake will parse the .pro
file as well as the target system's build parameters to create a makefile
that resolves all the includes and other system-specific details so building
a binary/executable for your system is then just a simple matter of running
'make'.

There are a few different make targets to take note of, but we won't
really be concerned with them except for making a "release-able" 
Windows .exe file (dynamically-linked against the non-debug libraries.

   make clean     - cleans the source directory of object and other
                      temporary build files
                      
   make           - will produce the default/incremental build
                      (which is going to be "debug")
                      
   make debug     - builds and dynamically-links against the debug
                      versions of the Qt libraries
                      (runs when you just type "make" by default)
                      
   make release   - builds and dynamically-links against normal
                      libraries that are suitable for distribution.


------------------
 GitHub and stuff
------------------
Be careful when you commit! While I have mostly debugged the .gitignore file
to work with the Qt framework's temp files on Windows and Linux, nothing is 
guaranteed to work quite right (is it ever?), so simply do a "make clean" 
before committing, please. Thishis will save many a headache when it comes to
compiling the source on a different environment.