From 3f9d3190ffd5577482d42bab97b3160d15f46743 Mon Sep 17 00:00:00 2001
From: James Turk <james.p.turk@gmail.com>
Date: Mon, 8 Aug 2005 19:19:21 +0000
Subject: [PATCH] 0.0.1 release preparation

---
 include/Application.hpp     | 49 ++++++++++++------------
 include/InputListener.hpp   | 22 +++++------
 include/ResourceManaged.hpp |  4 +-
 include/State.hpp           | 58 ++++++++++++++++++++++++++++
 include/audio/AudioCore.hpp |  4 +-
 include/entrypoint.hpp      | 76 ++++++++++++++++++++-----------------
 include/photon.hpp          |  2 +-
 include/types.hpp           |  8 ++--
 src/Application.cpp         | 10 ++---
 src/InputListener.cpp       | 10 ++---
 src/entrypoint.cpp          | 48 +++++++++++++++++++++++
 11 files changed, 202 insertions(+), 89 deletions(-)
 create mode 100644 include/State.hpp
 create mode 100644 src/entrypoint.cpp

diff --git a/include/Application.hpp b/include/Application.hpp
index b4632df..96a00e1 100644
--- a/include/Application.hpp
+++ b/include/Application.hpp
@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: Application.hpp,v 1.14 2005/08/08 07:27:50 cozman Exp $
+//  $Id: Application.hpp,v 1.15 2005/08/08 19:19:24 cozman Exp $
 
 #ifndef PHOTON_APPLICATION_HPP
 #define PHOTON_APPLICATION_HPP
@@ -18,10 +18,10 @@
 
 #include "types.hpp"
 #include "util/VersionInfo.hpp"
+#include "State.hpp"
 #include "Task.hpp"
 #include "Kernel.hpp"
 #include "InputListener.hpp"
-#include "video/VideoCore.hpp"
 #include "audio/AudioCore.hpp"
 #include "util/Singleton.hpp"
 
@@ -29,24 +29,14 @@
 
 namespace photon
 {
-    
-class State
-{
-public:
-    State() { };
-    virtual ~State() { };
-
-public:
-    virtual void update() { };
-    virtual void render()=0;
-};
-
-typedef shared_ptr<State> StatePtr;
 
 // Class: Application
-//  Abstract main class, all photon applications should derive from Application.
+//  Photon main class, contains functions that control creation of the display,
+//  setting the OpenGL view, input handling, timing, and <State> management.
 //
-//  Derived classes are made entrypoint via <ENTRYPOINT>.
+//  Class is a <Singleton> and therefore should be accessed through 
+//  Application::getInstance().  (Application Singleton is created/destroyed 
+//  automatically)
 class Application : public util::Singleton<Application>
 {
 
@@ -151,7 +141,7 @@ public:
     void setOrthoView(scalar width, scalar height);
 
     // Function: setOrthoView
-    //  Sets entire screen as current viewport with a given ortho perspective.
+    //  Sets entire screen as current viewport with a 1:1 perspective.
     void setOrthoView();
 
 // Group: Perspective
@@ -173,8 +163,6 @@ public:
     
     // Function: setPerspectiveView
     //  Sets entire screen as current viewport with a given 3D perspective.
-    //
-    //  Same as call to setPerspective
     // 
     // Parameters:
     //  fovy - The y axis field of view angle, in degrees.
@@ -317,12 +305,25 @@ public:
     template<class StateT>
     void setCurrentState();
 
-// Group: Core Access
+// Group: AudioCore
 public:
+    // Function: getAudioCore
+    //  Get the Application's <AudioCore>, should only be called after 
+    //  <initAudioCore>.
+    //
+    // Return:
+    //  Reference to the <AudioCore>.
    audio::AudioCore& getAudioCore();
+   
+   // Function: initAudioCore
+   //  Initialize the <AudioCore>, should be done before attempting to access
+   //  it via <getAudioCore>.
+   //
+   // Arguments:
+   //  deviceName - Name for desired Audio device.
    void initAudioCore(const std::string& deviceName);
 
-// Group: API Initialization
+// API Initialization
 private:
     util::VersionInfo initPhysFS(const std::string& arg0);
     util::VersionInfo initGLFW();
@@ -330,8 +331,8 @@ private:
     
 // Task Classes
 private:
-    // UpdateTask, does the updating work of AppCore, registered as a Task
-    //  so that user need not call something akin to AppCore::update() every 
+    // UpdateTask, does the updating work of Application, registered as a Task
+    //  so that user need not call something akin to Application::update() every 
     //  frame
     class UpdateTask : public Task
     {
diff --git a/include/InputListener.hpp b/include/InputListener.hpp
index f3047a0..a580f0b 100644
--- a/include/InputListener.hpp
+++ b/include/InputListener.hpp
@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: InputListener.hpp,v 1.1 2005/07/19 05:45:23 cozman Exp $
+//  $Id: InputListener.hpp,v 1.2 2005/08/08 19:19:24 cozman Exp $
 
 #ifndef PHOTON_INPUTLISTENER_HPP
 #define PHOTON_INPUTLISTENER_HPP
@@ -24,11 +24,11 @@ class InputListener
 public:
 
     // Function: InputListener
-    //  Registers the InputListener to listen for input with <AppCore>.
+    //  Registers the InputListener to listen for input with <Application>.
     InputListener();
 
     // Function: ~InputListener
-    //  Deregisters the listener with <AppCore>. so that it is no longer
+    //  Deregisters the listener with <Application>. so that it is no longer
     //  notified of events.
     virtual ~InputListener();
 
@@ -54,15 +54,15 @@ public:
     //  Called when a key is pressed.
     // 
     // Parameters:
-    //  key - Key that has been pressed. 
-    virtual void onKeyPress(int key);
+    //  key - <KeyCode> of key that has been pressed. 
+    virtual void onKeyPress(KeyCode key);
     
     // Function: onKeyRelease
     //  Called when a key is released.
     // 
     // Parameters:
-    //  key - Key that has been released.
-    virtual void onKeyRelease(int key);
+    //  key - <KeyCode> of key that has been released.
+    virtual void onKeyRelease(KeyCode key);
 
 // Group: Mouse Actions
 public:
@@ -70,15 +70,15 @@ public:
     //  Called when a mouse button is pressed.
     //
     // Parameters:
-    //  button - Mouse button that was pressed.
-    virtual void onMouseButtonPress(int button);
+    //  button - <MouseButton> that was pressed.
+    virtual void onMouseButtonPress(MouseButton button);
     
     // Function: onMouseButtonRelease
     //  Called when a mouse button is released.
     //
     // Parameters:
-    //  button - Mouse button that was released.
-    virtual void onMouseButtonRelease(int button);
+    //  button - <MouseButton> that was released.
+    virtual void onMouseButtonRelease(MouseButton button);
 
     // Function: onMouseMove
     //  Called when the mouse is moved.
diff --git a/include/ResourceManaged.hpp b/include/ResourceManaged.hpp
index 4ec99e7..f959208 100644
--- a/include/ResourceManaged.hpp
+++ b/include/ResourceManaged.hpp
@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: ResourceManaged.hpp,v 1.7 2005/07/04 03:06:48 cozman Exp $
+//  $Id: ResourceManaged.hpp,v 1.8 2005/08/08 19:19:24 cozman Exp $
 
 #ifndef PHOTON_RESOURCEMANAGED_HPP
 #define PHOTON_RESOURCEMANAGED_HPP
@@ -25,7 +25,7 @@ namespace photon
 // Children:
 //  <Texture>, <Image>
 // 
-//  <Audio>, <Music>, <Sound>
+//  <Sample>
 template<class ResMgrT>
 class ResourceManaged
 {
diff --git a/include/State.hpp b/include/State.hpp
new file mode 100644
index 0000000..2919d48
--- /dev/null
+++ b/include/State.hpp
@@ -0,0 +1,58 @@
+//This file is part of Photon (http://photon.sourceforge.net)
+//Copyright (C) 2004-2005 James Turk
+//
+// Author:
+//  James Turk (jpt2433@rit.edu)
+//
+// Version:
+//  $Id: State.hpp,v 1.1 2005/08/08 19:19:25 cozman Exp $
+
+#ifndef PHOTON_STATE_HPP
+#define PHOTON_STATE_HPP
+
+#include "types.hpp"
+
+// Class: State
+//  Pure virtual State class, used as base class for Photon's state system.
+//
+//  Photon's State system is extremely simple yet also very convenient. Simply 
+//  by creating classes that fulfill the <State> interface you can use Photon
+//  to manage the state that the game is in. 
+
+//  Implement as many or as few of the members of State as needed (the only 
+//  necessary member being <render>) and make the state as current via 
+//  <Application::setCurrentState>.  Once a state is made current it's 
+//  update and render methods will be called every frame until either a new
+//  state is made current or the application ends.
+class State
+{
+// Group: (Con/De)structors
+public:
+    // Function: State
+    //  A State's constructor is called whenever the state is made active via
+    //  <Application::setCurrentState>.
+    State() { };
+    
+    // Function: ~State
+    //  A State's destructor is called whenever the state is no longer the 
+    //  active state (the application ends, or a new state is made active).
+    virtual ~State() { };
+
+// Group: State Functions
+public:
+    // Function: update
+    //  All of a state's logic should go in update, it is called every frame
+    //  before the rendering process begins.  Nothing should be drawn to the 
+    //  screen within update because it will be cleared before it is shown.
+    virtual void update() { };
+    
+    // Function: render
+    //  The only required member of State, anything that should be drawn to the
+    //  screen while the State is active should be drawn in render.  Game logic
+    //  inside of render should be kept to a minimum for optimum performance.
+    virtual void render()=0;
+};
+
+typedef photon::shared_ptr<State> StatePtr;
+
+#endif  //PHOTON_STATE_HPP
diff --git a/include/audio/AudioCore.hpp b/include/audio/AudioCore.hpp
index 7e8acc6..e66181f 100644
--- a/include/audio/AudioCore.hpp
+++ b/include/audio/AudioCore.hpp
@@ -5,14 +5,14 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: AudioCore.hpp,v 1.12 2005/08/08 07:27:50 cozman Exp $
+//  $Id: AudioCore.hpp,v 1.13 2005/08/08 19:19:25 cozman Exp $
 
 #ifdef PHOTON_USE_OPENAL
 
 #ifndef PHOTON_AUDIO_AUDIOCORE_HPP
 #define PHOTON_AUDIO_AUDIOCORE_HPP
 
-#include "AL/al.h"
+#include "AL/al.h"      // This file depends on OpenAL
 #include "AL/alc.h"
 
 #include "util/VersionInfo.hpp"
diff --git a/include/entrypoint.hpp b/include/entrypoint.hpp
index 954e4ba..d85d910 100644
--- a/include/entrypoint.hpp
+++ b/include/entrypoint.hpp
@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: entrypoint.hpp,v 1.7 2005/08/07 07:12:46 cozman Exp $
+//  $Id: entrypoint.hpp,v 1.8 2005/08/08 19:19:25 cozman Exp $
 
 
 #ifndef PHOTON_ENTRYPOINT_HPP
@@ -13,43 +13,49 @@
 
 #include "Log.hpp"
 
-// Title: Entrypoint 
+// Title: PhotonMain
+//  PhotonMain is the entrypoint for all Photon applications, attempting to use
+//  main will result in an error message since main is defined within the 
+//  library.  Using PhotonMain as an entrypoint allows you to bypass any manual
+//  initialization of the core Photon library.
+//
+// Example PhotonMain Usage:
+// (code)
+//
+// class MainMenu : public State
+// {
+//     ...
+// };
+//
+// int PhotonMain(const StrVec& args)
+// {
+//     // create window
+//     Application::getInstance().createDisplay(800,600,32,0,0,false);
+// 
+//     // set current state
+//     Application::getInstance().setCurrentState<MainMenu>();
+//
+//     // can also add any tasks here 
+// 
+//     // run until finished
+//     Kernel::getInstance().run();
+//     
+//     return 0;
+// }
+// (end)
 
+
+// Function: PhotonMain
+//  Entrypoint for Photon applications.
+//
+// Arguments:
+//  args - <StrVec> containing command line arguments.
+//
+// Returns:
+//  zero on success, non-zero on failure, just like standard main. 
 int PhotonMain(const photon::StrVec& args);
 
-int main(int argc, const char** argv)
-{
-    // logging of uncaught exceptions to console
-    photon::Log log;
-    log.addSink(photon::LogSinkPtr(new photon::ConsoleSink("out")));
 
-    try
-    {
-        new photon::Application(argv[0]);
-
-        // push arguments into StrVec
-        photon::StrVec args;
-        for(int i=0; i < argc; ++i)
-        {
-            args.push_back(argv[i]);
-        }
-        
-        int retVal = PhotonMain(args);
-        
-        photon::Application::destroy();
-
-        return retVal;
-    }
-    catch(photon::Exception &e)     // log exceptions as errors (confusing?)
-    {
-        log.error() << e;
-        return 1;
-    }
-    catch(photon::Error &e)         // log errors as critical errors 
-    {
-        log.critical() << e;
-        return 1;
-    }
-}
+int main(int argc, const char** argv);
 
 #endif  //PHOTON_ENTRYPOINT_HPP
diff --git a/include/photon.hpp b/include/photon.hpp
index fe8024c..9b3eeb7 100644
--- a/include/photon.hpp
+++ b/include/photon.hpp
@@ -3,6 +3,7 @@
 
 #include "Kernel.hpp"
 #include "types.hpp"
+#include "State.hpp"
 #include "Application.hpp"
 #include "Task.hpp"
 #include "exceptions.hpp"
@@ -33,7 +34,6 @@
 #include "video/Texture.hpp"
 #include "video/Color.hpp"
 #include "video/TextureResourceManager.hpp"
-#include "video/VideoCore.hpp"
 #include "video/Font.hpp"
 
 #endif // PHOTON_HPP
diff --git a/include/types.hpp b/include/types.hpp
index 1d34e6a..4f774a1 100644
--- a/include/types.hpp
+++ b/include/types.hpp
@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: types.hpp,v 1.6 2005/04/21 19:30:19 cozman Exp $
+//  $Id: types.hpp,v 1.7 2005/08/08 19:19:25 cozman Exp $
 
 #ifndef PHOTON_TYPES_HPP
 #define PHOTON_TYPES_HPP
@@ -33,7 +33,7 @@ typedef unsigned char ubyte;
 typedef unsigned int uint;
 
 // Type: scalar
-//  Scalar value, used throughout photon. (double or float)
+//  Scalar value, used throughout photon in place of double or float
 typedef double scalar;
 
 // Group: STL/Boost Types
@@ -49,7 +49,7 @@ using boost::shared_ptr;
 // Group: Enums
 
 // Enum: KeyCode
-// Enumeration defining keys, used in <AppCore::keyPressed>.
+// Enumeration defining keys, used in <Application::keyPressed>.
 //
 // Enums:
 //  KEY_ESC  - Escape key
@@ -305,7 +305,7 @@ enum KeyCode
 };
 
 // Enum: MouseButton
-// Enumeration defining buttons, used in <AppCore::mouseButtonPressed>.
+// Enumeration defining buttons, used in <Application::mouseButtonPressed>.
 //
 //  MB_LEFT     - Left mouse button.
 //  MB_MIDDLE   - Middle mouse button.
diff --git a/src/Application.cpp b/src/Application.cpp
index 676734e..1ec0ce2 100644
--- a/src/Application.cpp
+++ b/src/Application.cpp
@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: Application.cpp,v 1.18 2005/08/08 07:27:50 cozman Exp $
+//  $Id: Application.cpp,v 1.19 2005/08/08 19:19:21 cozman Exp $
 
 #include "Application.hpp"
 
@@ -305,11 +305,11 @@ void GLFWCALL Application::keyCallback(int key, int action)
         {
             if(action == GLFW_PRESS)
             {
-                (*listener)->onKeyPress(key);
+                (*listener)->onKeyPress(KeyCode(key));
             }
             else
             {
-                (*listener)->onKeyRelease(key);
+                (*listener)->onKeyRelease(KeyCode(key));
             }
         }
     }
@@ -344,11 +344,11 @@ void GLFWCALL Application::mouseButtonCallback(int button, int action)
         {
             if(action == GLFW_PRESS)
             {
-                (*listener)->onMouseButtonPress(button);
+                (*listener)->onMouseButtonPress(MouseButton(button));
             }
             else
             {
-                (*listener)->onMouseButtonRelease(button);
+                (*listener)->onMouseButtonRelease(MouseButton(button));
             }
         }
     }
diff --git a/src/InputListener.cpp b/src/InputListener.cpp
index 954eb97..ed9fe05 100644
--- a/src/InputListener.cpp
+++ b/src/InputListener.cpp
@@ -5,7 +5,7 @@
 //  James Turk (jpt2433@rit.edu)
 //
 // Version:
-//  $Id: InputListener.cpp,v 1.2 2005/08/07 07:12:47 cozman Exp $
+//  $Id: InputListener.cpp,v 1.3 2005/08/08 19:19:22 cozman Exp $
 
 #include "InputListener.hpp"
 
@@ -36,10 +36,10 @@ bool InputListener::isActive() const
 }
 
 // do nothing, overloaded as needed
-void InputListener::onKeyPress(int key) { }
-void InputListener::onKeyRelease(int key) { }
-void InputListener::onMouseButtonPress(int button)  { }
-void InputListener::onMouseButtonRelease(int button) { }
+void InputListener::onKeyPress(KeyCode key) { }
+void InputListener::onKeyRelease(KeyCode key) { }
+void InputListener::onMouseButtonPress(MouseButton button)  { }
+void InputListener::onMouseButtonRelease(MouseButton button) { }
 void InputListener::onMouseMove(const math::Vector2& pos) { }
 
 
diff --git a/src/entrypoint.cpp b/src/entrypoint.cpp
new file mode 100644
index 0000000..774e108
--- /dev/null
+++ b/src/entrypoint.cpp
@@ -0,0 +1,48 @@
+//This file is part of Photon (http://photon.sourceforge.net)
+//Copyright (C) 2004-2005 James Turk
+//
+// Author:
+//  James Turk (jpt2433@rit.edu)
+//
+// Version:
+//  $Id: entrypoint.cpp,v 1.1 2005/08/08 19:19:22 cozman Exp $
+
+#include "entrypoint.hpp"
+#include "Log.hpp"
+#include "types.hpp"
+#include "Application.hpp"
+
+int main(int argc, const char** argv)
+{
+    // logging of uncaught exceptions to console
+    photon::Log log;
+    log.addSink(photon::LogSinkPtr(new photon::ConsoleSink("out")));
+
+    try
+    {
+        new photon::Application(argv[0]);
+
+        // push arguments into StrVec
+        photon::StrVec args;
+        for(int i=0; i < argc; ++i)
+        {
+            args.push_back(argv[i]);
+        }
+        
+        int retVal = PhotonMain(args);
+        
+        photon::Application::destroy();
+
+        return retVal;
+    }
+    catch(photon::Exception &e)     // log exceptions as errors (confusing?)
+    {
+        log.error() << e;
+        return 1;
+    }
+    catch(photon::Error &e)         // log errors as critical errors 
+    {
+        log.critical() << e;
+        return 1;
+    }
+}