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

Project Group Name: The Red Menace 

Members:
	Dan Brook
	Austin Veino
	Dan Scanlan
	
----------------------
 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. 

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.


___ FUTURE FEATURES ___

Probably a control to allow scaling of models? Heck, we could shear them too.


---------------------------------------------------------
 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 merely 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.

 //TODO: Write a guide for compiling lib3ds for Windows.
 //TODO: Create and update a unified .pro file for lib3ds on the Mac
    

------------------------
 Getting up and running
------------------------
Find your distribution's installer at qt-project.org. If you're using
Linux, simply installing the Qt development libraries from your
system's package manager should pull in all the runtime dependencies as
well and allow you to build the project. To check if they're installed
a simple "which qmake" should return "/usr/bin/qmake" or something 
similar.

On Windows, installing MinGW with C++ and then installing Qt for MinGW
is the easiest way to go. The process is almost fully automatic, but
misses one very important thing; setting the environment variables is
not done by the installer. Once the paths for qt\bin and mingw\bin are
placed in the user's path, the project can then be compiled from this
source very easily.

On the Mac, ___ INSTRUCTIONS PENDING SUCCESSFUL CONFIG ON OUR MAC ___


-----------------------
 Building from scratch
-----------------------
Upon the initial grabbing of the sources from the repository you will
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")
                      
   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.