cleaned up source

include/AppCore.hpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: AppCore.hpp,v 1.6 2005/07/17 06:19:18 cozman Exp $
+//  $Id: AppCore.hpp,v 1.7 2005/07/19 01:31:37 cozman Exp $
 
 #ifndef PHOTON_APPCORE_HPP
 #define PHOTON_APPCORE_HPP
@@ -154,7 +154,7 @@ public:
     double getElapsedTime();
 
     // Function: getFramerate
-    //  Gets number of frames per second the application is currently being run at.
+    //  Gets number of frames per second the application is currently processing
     //
     // Returns:
     //  Current frames per second.

include/Application.hpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: Application.hpp,v 1.8 2005/05/15 02:51:10 cozman Exp $
+//  $Id: Application.hpp,v 1.9 2005/07/19 01:31:37 cozman Exp $
 
 #ifndef PHOTON_APPLICATION_HPP
 #define PHOTON_APPLICATION_HPP
@@ -23,8 +23,7 @@ namespace photon
 {
 
 // Class: Application
-//  Abstract main class, all photon applications should derive from API-specific
+//  Abstract main class, all photon applications should derive from Application.
-//  implementations of Application.
 //
 //  Derived classes are made entrypoint via <ENTRYPOINT>.
 class Application
@@ -45,7 +44,7 @@ public:
     // Function: main
     //  Pure virtual, must be defined by derived class, using some preprocessor
     //  magic (<MAINCLASS>) on the derived class
-    //  this becomes the entry point for a Amph application.
+    //  this becomes the entry point for a Photon application.
     //
     // Parameters:
     //  args - <ArgList> containing arguments passed to program.

include/Log.hpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: Log.hpp,v 1.6 2005/05/15 02:51:10 cozman Exp $
+//  $Id: Log.hpp,v 1.7 2005/07/19 01:31:37 cozman Exp $
 
 #ifndef PHOTON_LOG_HPP
 #define PHOTON_LOG_HPP
@@ -51,7 +51,7 @@ public:
     //  Remove a sink from the log by name.
     //
     //  Parameters:
-    //      sinkName - Name of sink to remove.
+    //   sinkName - Name of sink to remove.
     void removeSink(const std::string& sinkName);
 
     // Function: removeSink
@@ -112,11 +112,11 @@ public:
     //  Flushes the log, is generally not required.  Output is handed to the
     //  sinks when flush is called.
     void flush();
-    
+
 private:
-    std::stringstream buffer_;
+    std::stringstream buffer_;      // buffer used for accumulating messages
-    LogLevel lastLevel_;
+    LogLevel lastLevel_;            // last log level, used when outputting
-    std::list<LogSinkPtr> sinks_;
+    std::list<LogSinkPtr> sinks_;   // list of attached sinks
 };
 
 }

include/ResourceManager.hpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: ResourceManager.hpp,v 1.9 2005/07/04 03:06:48 cozman Exp $
+//  $Id: ResourceManager.hpp,v 1.10 2005/07/19 01:31:37 cozman Exp $
 
 #ifndef PHOTON_RESOURCEMANAGER_HPP
 #define PHOTON_RESOURCEMANAGER_HPP
@@ -116,7 +116,7 @@ void ResourceManager<resT, ResDescT>::newResource(const std::string& name,
 template<class resT, class ResDescT>
 resT& ResourceManager<resT, ResDescT>::getResource(const std::string& name)
 {
-    MapIterator resource( resourceMap_.find(name) );
+    MapIterator resource( resourceMap_.find(name) );    // fetch resource
     
     if(resource != resourceMap_.end())
     {
@@ -133,7 +133,7 @@ resT& ResourceManager<resT, ResDescT>::getResource(const std::string& name)
 template<class resT, class ResDescT>
 void ResourceManager<resT, ResDescT>::deleteResource(const std::string& name)
 {
-    MapIterator resource( resourceMap_.find(name) );
+    MapIterator resource( resourceMap_.find(name) );    // fetch resource
     
     // if the resource was found
     if(resource != resourceMap_.end())
@@ -147,7 +147,7 @@ void ResourceManager<resT, ResDescT>::deleteResource(const std::string& name)
 template<class resT, class ResDescT>
 void ResourceManager<resT, ResDescT>::delRef(const std::string& name)
 {
-    MapIterator resource( resourceMap_.find(name) );
+    MapIterator resource( resourceMap_.find(name) );    // fetch resource
     
     // if the resource was found
     if(resource != resourceMap_.end())
@@ -172,8 +172,7 @@ void ResourceManager<resT, ResDescT>::cleanUp()
 template<class resT, class ResDescT>
 void ResourceManager<resT, ResDescT>::printReport(std::ostream& os)
 {
-    MapIterator resource( resourceMap_.begin() );
+    // go through all resources and output debug info (name/path/refCount)
-    
     for(MapIterator i = resourceMap_.begin(); i != resourceMap_.end(); ++i)
     {
         os << i->second.name << "\t" << i->second.path << "\t" 

include/Task.hpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: Task.hpp,v 1.1 2005/03/15 19:22:07 cozman Exp $
+//  $Id: Task.hpp,v 1.2 2005/07/19 01:31:37 cozman Exp $
 
 #ifndef PHOTON_TASK_HPP
 #define PHOTON_TASK_HPP
@@ -141,10 +141,10 @@ public:
 
 // data members
 private:
-    std::string name_;
+    std::string name_;          // all tasks need a unique name
-    PriorityLevel priority_;
+    PriorityLevel priority_;    // priority determines ordering of tasks
-    bool alive_;
+    bool alive_;                // if false, task will be pruned
-    bool paused_;
+    bool paused_;               // if false task won't be executed
 };
 
 }

include/entrypoint.hpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: entrypoint.hpp,v 1.5 2005/05/15 02:51:10 cozman Exp $
+//  $Id: entrypoint.hpp,v 1.6 2005/07/19 01:31:37 cozman Exp $
 
 
 #ifndef PHOTON_ENTRYPOINT_HPP
@@ -13,15 +13,14 @@
 
 #include "Log.hpp"
 
-/* Title: Entrypoint */
+// Title: Entrypoint 
+
+//  Macro: ENTRYPOINT
+//  A macro which is used to specify the class containing the entrypoint.
+//  For example, if the class PongGame is the class derived from <Application>
+//  which implements main, in the file defining PongGame it is important to
+//  include ENTRYPOINT(PongGame) so that the entry point becomes PongGame::main.
 
-/*
-    Macro: ENTRYPOINT
-    A macro which is used to specify the class containing the entrypoint.
-    For example, if the class PongGame is the class derived from <Application>
-    which implements main, in the file defining PongGame it is important to
-    include ENTRYPOINT(PongGame) so that the entry point becomes PongGame::main.
-*/
 #define ENTRYPOINT(className)    int main(int argc, const char** argv)  \
                             { return photon::mainclass<className>(argc,argv); }
 
@@ -32,6 +31,7 @@ namespace photon
 template<class App>
 int mainclass(int argc, const char** argv)
 {
+    // logging of uncaught exceptions to console
     Log log;
     log.addSink(LogSinkPtr(new photon::ConsoleSink("out")));
     
@@ -40,20 +40,23 @@ int mainclass(int argc, const char** argv)
         App::setInitOptions(argv[0]);
         
         App app;
+        
+        // push arguments into StrVec
         StrVec args;
         for(int i=0; i < argc; ++i)
         {
             args.push_back(argv[i]);
         }
 
-        return app.main(args);
+        // hand arguments to Application::main and return what main returns
+        return app.main(args);  
     }
-    catch(Exception &e)
+    catch(Exception &e)     // log exceptions as errors (wow that's confusing)
     {
         log.error() << e;
-        return 0;
+        return 1;   
     }
-    catch(Error &e)
+    catch(Error &e)         // log errors as critical errors 
     {
         log.critical() << e;
         return 1;

include/exceptions.hpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: exceptions.hpp,v 1.5 2005/06/27 04:24:16 cozman Exp $
+//  $Id: exceptions.hpp,v 1.6 2005/07/19 01:31:37 cozman Exp $
 
 #ifndef PHOTON_EXCEPTIONS_HPP
 #define PHOTON_EXCEPTIONS_HPP
@@ -15,8 +15,6 @@
 #include <sstream>
 #include <ostream>
 
-#define __FLOC__ __FILE__,__LINE__
-
 namespace photon 
 { 
 

include/util/ConfigFile.hpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: ConfigFile.hpp,v 1.5 2005/07/18 06:18:51 cozman Exp $
+//  $Id: ConfigFile.hpp,v 1.6 2005/07/19 01:31:37 cozman Exp $
 
 #ifndef PHOTON_UTIL_CONFIGFILE_HPP
 #define PHOTON_UTIL_CONFIGFILE_HPP
@@ -187,8 +187,9 @@ ConfigFile::setVariable(const std::string& sec,
     }
 }
 
-//template specialization for setVariable<std::string>
+//template specialization for setVariable<std::string> (DISABLED)
-/*template<>
+#if 0
+template<>
 void
 ConfigFile::setVariable(std::string sec, std::string var, std::string value)
 {
@@ -196,7 +197,8 @@ ConfigFile::setVariable(std::string sec, std::string var, std::string value)
     value = "\"" + value + "\"";    //add ""s to value
 
     layout_[sec][var] = value;   //actually set it
-}*/
+}
+#endif
 
 template<class varType>
 varType

src/AppCore.cpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: AppCore.cpp,v 1.9 2005/07/17 06:19:18 cozman Exp $
+//  $Id: AppCore.cpp,v 1.10 2005/07/19 01:31:37 cozman Exp $
 
 #include "AppCore.hpp"
 
@@ -25,12 +25,15 @@ AppCore::AppCore() :
 {
     util::VersionInfo glfwReq(2,4,2);   // requires GLFW 2.4.2
     util::ensureVersion("GLFW", initGLFW(), glfwReq);
+    
+    new video::VideoCore;   // create the VideoCore
 
     Kernel::getInstance().addTask(task_);
 }
 
 AppCore::~AppCore()
 {
+    video::VideoCore::destroy();    // destroy videocore
     glfwCloseWindow();  //close GLFW window
     glfwTerminate();    //shutdown GLFW
 }
@@ -51,7 +54,6 @@ void AppCore::createDisplay(uint width, uint height,
 
     dispWidth_ = width;
     dispHeight_ = height;
-    new video::VideoCore;
     video::VideoCore::getInstance().setDisplaySize(width,height);
 
     glfwSetWindowTitle(title.c_str());  // title is set separately

src/Application.cpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: Application.cpp,v 1.11 2005/07/05 06:44:56 cozman Exp $
+//  $Id: Application.cpp,v 1.12 2005/07/19 01:31:38 cozman Exp $
 
 #include "Application.hpp"
 
@@ -34,13 +34,6 @@ Application::Application() :
     new Kernel;
     new AppCore;
 
-    // StrVec args;
-    // 
-    // for(int i=0; i < argc; ++i)
-    // {
-    //     args.push_back(argv[i]);
-    // }
-
     util::ensureVersion("PhysFS", initPhysFS(), physfsReq);
 }
 
@@ -50,7 +43,6 @@ Application::~Application()
 
     // destroy the singletons
     AppCore::destroy();
-    video::VideoCore::destroy();
     //audio::AudioCore::destroy();
     Kernel::destroy();
 }

src/Kernel.cpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: Kernel.cpp,v 1.1 2005/03/15 19:22:07 cozman Exp $
+//  $Id: Kernel.cpp,v 1.2 2005/07/19 01:31:38 cozman Exp $
 
 #include "Kernel.hpp"
 
@@ -39,7 +39,6 @@ void Kernel::run()
             // only update alive, non-paused tasks
             if(task->isAlive() && !task->isPaused())
             {
-                // Log::getInstance().note() << "updating task : " << task->getName();
                 task->update();
             }
         }
@@ -52,7 +51,7 @@ void Kernel::run()
             // remove dead tasks
             if(!task->isAlive())
             {
-                task->onKill();
+                task->onKill();     // symmetry with onStart, clean up act
                 it = tasks_.erase(it);
             }
             else
@@ -66,6 +65,7 @@ void Kernel::run()
 void Kernel::addTask(TaskPtr task)
 {
     std::list<TaskPtr>::iterator it = tasks_.begin();
+    // attempt to find task
     std::list<TaskPtr>::iterator found = std::find_if(tasks_.begin(), 
                                 tasks_.end(),
                                 std::bind2nd(TaskNameEq(), task->getName()) );
@@ -77,7 +77,7 @@ void Kernel::addTask(TaskPtr task)
                                     task->getName() + "\".");
     }
     
-    task->onStart();
+    task->onStart();    // called whenever a task is being started
     
     // find the first task in the list with a lower priority
     while(it != tasks_.end() && task->getPriority() <= (*it)->getPriority())
@@ -89,10 +89,12 @@ void Kernel::addTask(TaskPtr task)
 
 void Kernel::killTask(const std::string& taskName)
 {
+    // attempt to find the task
     std::list<TaskPtr>::iterator task = std::find_if(tasks_.begin(), 
                                 tasks_.end(),
                                 std::bind2nd(TaskNameEq(), taskName) );
-    if(task != tasks_.end())
+    
+    if(task != tasks_.end())    // kill task if found
     {
         (*task)->kill();
     }
@@ -105,10 +107,12 @@ void Kernel::killTask(const std::string& taskName)
 
 void Kernel::pauseTask(const std::string& taskName)
 {
+    // attempt to find the task
     std::list<TaskPtr>::iterator task = std::find_if(tasks_.begin(), 
                                 tasks_.end(),
                                 std::bind2nd(TaskNameEq(), taskName) );
-    if(task != tasks_.end())
+
+    if(task != tasks_.end())    // pause task if found
     {
         (*task)->onPause();
     }
@@ -121,16 +125,18 @@ void Kernel::pauseTask(const std::string& taskName)
 
 void Kernel::unpauseTask(const std::string& taskName)
 {
+    // attempt to find the task
     std::list<TaskPtr>::iterator task = std::find_if(tasks_.begin(), 
                                 tasks_.end(),
                                 std::bind2nd(TaskNameEq(), taskName) );
-    if(task != tasks_.end())
+    
+    if(task != tasks_.end())    // unpause task if found
     {
         (*task)->onUnpause();
     }
     else
     {
-        throw PreconditionException("Attempted to unpause nonexistant task \"" +  
+        throw PreconditionException("Attempted to unpause nonexistant task \"" +
                                     taskName + "\".");
     }
 }

src/Log.cpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: Log.cpp,v 1.8 2005/05/15 02:50:52 cozman Exp $
+//  $Id: Log.cpp,v 1.9 2005/07/19 01:31:38 cozman Exp $
 
 #include "Log.hpp"
 
@@ -21,14 +21,14 @@ Log::Log()
 
 Log::~Log()
 {
-    flush();
+    removeSinks();  // drop all sinks (also flushes output)
-    removeSinks();
 }
 
 void Log::addSink(LogSinkPtr sink)
 {
     flush();
 
+    // search through list of sinks to avoid adding same sink twice
     for(std::list<LogSinkPtr>::iterator it = sinks_.begin();
         it != sinks_.end();
         ++it)
@@ -40,13 +40,14 @@ void Log::addSink(LogSinkPtr sink)
         }
     }
 
-    sinks_.push_back(sink);
+    sinks_.push_back(sink); // add sink if unique
 }
 
 void Log::removeSink(const std::string& sinkName)
 {
     flush();
     
+    // find sink and erase it
     for(std::list<LogSinkPtr>::iterator it = sinks_.begin();
         it != sinks_.end();
         ++it)
@@ -62,9 +63,11 @@ void Log::removeSink(LogSinkPtr sink)
 {
     flush();
     
+    // search for sink 
     std::list<LogSinkPtr>::iterator it =
         std::find(sinks_.begin(),sinks_.end(),sink);
 
+    // remove sink if it exists
     if(it != sinks_.end())
     {
         sinks_.erase(it);
@@ -73,15 +76,15 @@ void Log::removeSink(LogSinkPtr sink)
 
 void Log::removeSinks()
 {
-    flush();
+    flush();    // make sure last message gets flushed to sinks
 
-    sinks_.clear();
+    sinks_.clear();     // empty entire sink list
 }
 
 void Log::flush()
 {
-    std::string str = buffer_.str();
+    std::string str = buffer_.str();    // get string from buffer
-    if(str.length())
+    if(str.length())    // if a message exists, write it to all sinks
     {
         for(std::list<LogSinkPtr>::iterator it = sinks_.begin();
             it != sinks_.end();
@@ -89,10 +92,12 @@ void Log::flush()
         {
             (*it)->writeMessage(lastLevel_,str);
         }
-        buffer_.str("");
+        buffer_.str("");    // clear message
     }
 }
 
+// note, verbose, warning, error, critical all flush the existing buffer
+// set the level and return the stringstream for writing
 std::ostream& Log::note()
 {
     flush();

src/Task.cpp

@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: Task.cpp,v 1.1 2005/03/15 19:22:07 cozman Exp $
+//  $Id: Task.cpp,v 1.2 2005/07/19 01:31:38 cozman Exp $
 
 #include "Task.hpp"
 
@@ -17,10 +17,10 @@ Task::Task(const std::string& name, PriorityLevel priority) :
 { 
 }
 
-// do nothing (how I wish destructors were virtual by default)
+// do nothing.. again (oh how I wish destructors were virtual by default)
 Task::~Task() { }
 
-// do nothings (non-pure since some tasks may not need special behavior)
+// do nothings (not pure-virtual since some tasks may not need special behavior)
 void Task::onStart() { }
 void Task::onKill() { }