README
Author: Eric Butler <[email protected]>
        Steven Fackler <[email protected]>

---------------------------------------------------------------------------
Overview
---------------------------------------------------------------------------

In here you will find instructions for building the project and a
short description of each source file.

There is quite a bit of starter code for project 3. It contains math
utility functions and classes, code to load the application, code to load
models, and code to handle mouse/keyboard input.


---------------------------------------------------------------------------
Building the Code
---------------------------------------------------------------------------

This project uses the CMake build system (www.cmake.org). CMake is a kind of
"meta build-system," in that it creates a build system for you. It supports
many different build systems, ranging from Unix Makefiles to Visual Studio
projects to XCode projects.

1) If you don't have CMake installed, you should install it. If you're running
    Linux, it should be available through your disto's package manager
    (apt-get, pacman, ports, etc). Windows and OSX installers can be downloaded
    from http://www.cmake.org/cmake/resources/software.html
2) Open up a command prompt in the "build" directory and run "cmake ../src".
    CMake will generate the build system in the build directory. By default,
    CMake will generate Makefiles on Linux and OSX and a Visual Studio project
    on Windows. If you'd like to change that, you can pass a different
    "generator" to cmake with the -G flag. A full list of generators can be
    found at the bottom of the output generated by running "cmake". For
    example, "cmake -G 'Xcode' ../src" will generate an Xcode project on OSX.
3) You can now use the build system in the "build" directory. The default
    target will compile everything for you, and the "install" target will copy
    the p2 executable to the main "p2" directory.

***************

IMPORTANT NOTE:
Performance is a reasonable concern for this project, so if you want your code
to be fast make sure you compile with optimizations.

For debugging, use the following CMake command:

cmake -DCMAKE_BUILD_TYPE=Debug ../src

for tracing images (especially if you have global illumination and/or a distributed ray tracer) use the following CMake command:

cmake -DCMAKE_BUILD_TYPE=Release ../src

***************

WINDOWS NOTE: If you're using Windows, you'll have to add the "windows/required"
directory to your PATH environment variable so Windows can find the shared
libraries the project will use.

OSX NOTE: OpenMP may or may not work with the compiler you are using. When you
use CMake you may see warnings about not finding OpenMP. You can ignore them.

Note: Your program MUST COMPILE on the SCS Linux machines. If you use
Windows, make sure to test on Linux well in advance of the deadline.

---------------------------------------------------------------------------
Running the Program
---------------------------------------------------------------------------

p3 [-r] [-d width height] input_scene [output_file]

Options:

    -r:
        Raytraces the scene and saves to the output file without
        loading a window or creating an opengl context.
    -d width height
        The dimensions of image to raytrace (and window if using
        and opengl context. Defaults to width=800, height=600.
    input_scene:
        The scene file to load and raytrace.
    output_file:
        The output file in which to write the rendered images.
        If not specified, default timestamped filenames are used.

Instructions:

    Press 'r' to raytrace the scene. Press 'r' again to go back to
    go back to OpenGL rendering. Press 'f' to dump the most recently
    raytraced image to the output file.

    Use the mouse and 'w', 'a', 's', 'd', 'q', and 'e' to move the
    camera around. The keys translate the camera, and left and right
    mouse buttons rotate the camera.

    If not using windowed mode (i.e., -r was specified), then output
    image will be automatically generated and the program will exit.

---------------------------------------------------------------------------
C++ Notes
---------------------------------------------------------------------------

For the sake of simpler math routines and data structures, the code uses
C++ over straight C. The code tries to stay away from most features of the
language to keep it as simple as possible. This project attempts to break
you into C++ easily.

Questions about virtual functions, classes, or any C++ idioms are welcome.

---------------------------------------------------------------------------
Source Files and Directory Structure
---------------------------------------------------------------------------

The code base is rather big, so here's a description of the top-level
directories and every header/source file pair we give you. You are free
to edit any of them and add as many as you like, as long as the program
behavior remains the same.

You should have a look at:
- writeup.txt
- src/p3/raytracer.cpp and hpp
- src/scene/*.hpp

Note: we omit the '.cpp' or '.hpp' from the source file names
in the follow listing.

Legend:
#   - must edit this file
*   - should look at (header) file

README              -- this file
writeup.txt#        -- Description of your project and implementation.

models/             -- models used in scenes.
images/             -- textures used in scenes.
scenes/*            -- scenes on which to test your program.
reference_shots/*   -- images of each scene created with the referece solution

src/build/*         == Build system stuff.
    CMakeLists.txt  -- Compiler flags can be adjusted by editing the list in
                        here.

src/p3/             == Project-specific files. Main file to edit is here.
    main            -- Main function, application backend, and scene rendering.
    raytracer#      -- Shell for implementation. This is the main file you
                        must edit.

src/application/    == General application files. You can ignore all of it.
    application     -- SDL backend, runs main loop.
    camera_roam     -- Functions for camera control via mouse and keyboard.
    imageio         -- Functions to load and save PNG files.
    opengl          -- Header to include correct OpenGL headers.
    scene_loader    -- Code to load a scene from a file.

src/math/           == Math utilities.
    camera*         -- Camera class with functions to mutate.
    color           -- A class for RGB colors and related functions.
    math            -- Basic header and a few generic functions.
    matrix          -- 3D, 4D matrix classes and several related functions.
    quaternion      -- Quaternion class and several related functions--very
                        useful for 3D rotations.
    vector          -- 2D, 3D, 4D vector classes and many related functions.

src/scene/          == Scene-specific files and rendering. You can ignore all
                        of this (though you'll need to use it the raytracer).

src/tinyxml/        == XML parser, used with scenes. You can ignore this.