From ede708d4e15a34a4443727fc64fd28946fcbeb41 Mon Sep 17 00:00:00 2001 From: Daniel Karbach Date: Tue, 16 Oct 2012 22:33:33 +0200 Subject: [PATCH] commented headers in app/ directory --- src/app/Application.cpp | 33 ++++++++++++++++----------------- src/app/Application.h | 17 +++++++++++++++-- src/app/Arguments.h | 2 ++ src/app/Input.h | 13 +++++++++++++ src/app/State.h | 28 +++++++++++++++++++++------- src/app/Timer.h | 25 +++++++++++++++++++++++++ src/main.cpp | 2 +- 7 files changed, 93 insertions(+), 27 deletions(-) diff --git a/src/app/Application.cpp b/src/app/Application.cpp index 4de48d4..f773cfc 100644 --- a/src/app/Application.cpp +++ b/src/app/Application.cpp @@ -13,12 +13,11 @@ namespace app { -Application::Application(sdl::InitScreen *screen, State *initialState) +Application::Application(sdl::InitScreen &screen, State *initialState) : screen(screen) , states() , last(SDL_GetTicks()) , inStateChage(false) { - assert(screen && "cannot create application without screen"); assert(initialState && "cannot create application without initial state"); RealPushState(initialState); } @@ -86,32 +85,32 @@ void Application::PopState() { void Application::RealChangeState(State *s) { if (!states.empty()) { - states.top()->PauseState(*this, screen->Screen()); - states.top()->ExitState(*this, screen->Screen()); + states.top()->PauseState(*this, screen.Screen()); + states.top()->ExitState(*this, screen.Screen()); states.pop(); } states.push(s); - s->EnterState(*this, screen->Screen()); - s->ResumeState(*this, screen->Screen()); + s->EnterState(*this, screen.Screen()); + s->ResumeState(*this, screen.Screen()); } void Application::RealPushState(State *s) { if (!states.empty()) { - states.top()->PauseState(*this, screen->Screen()); + states.top()->PauseState(*this, screen.Screen()); } states.push(s); - s->EnterState(*this, screen->Screen()); - s->ResumeState(*this, screen->Screen()); + s->EnterState(*this, screen.Screen()); + s->ResumeState(*this, screen.Screen()); } void Application::RealPopState() { if (states.empty()) return; - states.top()->PauseState(*this, screen->Screen()); - states.top()->ExitState(*this, screen->Screen()); + states.top()->PauseState(*this, screen.Screen()); + states.top()->ExitState(*this, screen.Screen()); delete states.top(); states.pop(); if (!states.empty()) { - states.top()->ResumeState(*this, screen->Screen()); + states.top()->ResumeState(*this, screen.Screen()); } } @@ -121,8 +120,8 @@ void Application::Quit() { void Application::PopAllStates() { while (!states.empty()) { - states.top()->PauseState(*this, screen->Screen()); - states.top()->ExitState(*this, screen->Screen()); + states.top()->PauseState(*this, screen.Screen()); + states.top()->ExitState(*this, screen.Screen()); delete states.top(); states.pop(); } @@ -165,7 +164,7 @@ void Application::HandleEvents() { PopAllStates(); break; case SDL_VIDEORESIZE: - screen->Resize(event.resize.w, event.resize.h); + screen.Resize(event.resize.w, event.resize.h); CurrentState()->Resize(event.resize.w, event.resize.h); break; case SDL_KEYDOWN: @@ -190,8 +189,8 @@ void Application::UpdateWorld(Uint32 deltaT) { void Application::Render(void) { if (!CurrentState()) return; - CurrentState()->Render(screen->Screen()); - screen->Flip(); + CurrentState()->Render(screen.Screen()); + screen.Flip(); } } diff --git a/src/app/Application.h b/src/app/Application.h index 41198bc..df5de25 100644 --- a/src/app/Application.h +++ b/src/app/Application.h @@ -20,10 +20,23 @@ namespace app { +/// Application controller class. +/// Operates on a state stack that can be modified via ChangeState, PushState, +/// and PopState. +/// All state changes are delayed until the looping mechanism gets control again +/// (i.e. after a top level state function returns, not during). +/// SDL key events are preprocessed, see app::Input. +/// The quit event (typically window closed or signal received) is caught and +/// results in immediate (that is, after the next input loop) termination. +/// Popped states will be deleted via the plain delete operator on an app::State +/// pointer. +/// Timers created by GlobalTimers() operate on actual application time and are +/// not paused when the current state is paused (as are the timers started by +/// the app::State members). class Application { public: - Application(sdl::InitScreen *screen, State *initialState); + Application(sdl::InitScreen &screen, State *initialState); ~Application(); private: Application(const Application &); @@ -65,7 +78,7 @@ private: void Render(); private: - sdl::InitScreen *screen; + sdl::InitScreen &screen; std::stack states; std::queue stateChanges; Timers globalTimers; diff --git a/src/app/Arguments.h b/src/app/Arguments.h index 7c51b7f..ace8cda 100644 --- a/src/app/Arguments.h +++ b/src/app/Arguments.h @@ -12,6 +12,8 @@ namespace app { +/// Specialized argument interpreter. +/// Reads command line arguments via Read(int, char**) function. class Arguments { public: diff --git a/src/app/Input.h b/src/app/Input.h index 415d11f..4df4685 100644 --- a/src/app/Input.h +++ b/src/app/Input.h @@ -13,6 +13,19 @@ namespace app { +/// Maps SDL key events to virtual buttons. +/// Records the state and whether it was pressed/released in the current +/// iteration. +/// Multiple buttons can be passed by ORing them bitwise. +/// The MapKey(SDLKey, Button) function introduces a mapping for the given key +/// to the given virtual button. Each key can be assigned to one button only, +/// but there is no limit (well, except for memory, I guess) on how many keys +/// may map to the same button. +/// Each iteration should first call ResetInteractiveState() to drop the just +/// pressed/released information and then pass each SDL_KeyboardEvent to +/// HandleKeyboardEvent(const SDL_KeyboardEvent &). +/// The four DEBUG_? buttons do not map to any real SNES/Lufia 2 button and may +/// be used for debugging or non-gameplay-related input. class Input { public: diff --git a/src/app/State.h b/src/app/State.h index 958e423..41af536 100644 --- a/src/app/State.h +++ b/src/app/State.h @@ -15,33 +15,47 @@ namespace app { +/// Application state base class for use with app::Application. class State { public: virtual ~State() { }; public: - /// do some setup - /// called when the state first enters the stack + /// Do some setup that needs an application and/or screen handle and thus + /// can not be done by the constructor. + /// Called when the state first enters the stack. /// @param ctrl the Application running the state virtual void EnterState(Application &ctrl, SDL_Surface *screen) = 0; - /// do some cleanup - /// called when the state is popped from the stack + /// Do some cleanup. + /// Called when the state is popped from the stack. virtual void ExitState(Application &ctrl, SDL_Surface *screen) = 0; - /// called when the state becomes the active one + /// Called when the state becomes the active one. virtual void ResumeState(Application &ctrl, SDL_Surface *screen) = 0; - /// called when the state becomes inactive + /// Called when the state becomes inactive. virtual void PauseState(Application &ctrl, SDL_Surface *screen) = 0; - /// adapt the state's graphics to given dimensions + /// Adapt the state's graphics to given dimensions. + /// NOTE: currently, this is only called for the stack top and not + /// propagated on stack changes. + /// Will be fixed soom ;). virtual void Resize(int width, int height) = 0; + /// Handle interactive events such as input and timers. virtual void HandleEvents(const Input &) = 0; + /// Update the time-dependant world representation. virtual void UpdateWorld(float deltaT) = 0; + /// Draw a picture of the world. virtual void Render(SDL_Surface *) = 0; public: + /// Timers handle intended for graphics, sync'ed with render time. + /// These timers are only updated for the stack top and thus appear paused + /// when the state is visible (roughly). Timers &GraphicsTimers() { return graphicsTimers; } + /// Timers handle intended for graphics, sync'ed with world time. + /// These timers are only updated for the stack top and thus appear paused + /// when the state is visible (roughly). Timers &PhysicsTimers() { return physicsTimers; } private: diff --git a/src/app/Timer.h b/src/app/Timer.h index 13f48f3..05d295e 100644 --- a/src/app/Timer.h +++ b/src/app/Timer.h @@ -14,6 +14,8 @@ namespace app { +/// Stores timing information. +/// For use by app::Timer. template struct TimerData { @@ -29,6 +31,9 @@ struct TimerData { }; +/// Timer handle. +/// How the various information returned by the const member functions is to be +/// interpreted highly depends on how the timer was created (by app::Timers). template class Timer { @@ -48,37 +53,50 @@ public: } public: + /// Check if the timer was started (and not cleared) yet. bool Started() const { return data; } + /// Check if the timer has reached its target time (only sensible for + /// countdown timers). bool Finished() const { return data && data->target != Time() && !data->repeat && data->time >= data->target; } + /// Check if the timer was started and has not finished yet (in case it's a + /// countdown). bool Running() const { return data && !Finished(); } + /// Get the elapsed time since the timer started. Time Elapsed() const { return data ? data->time : Time(); } + /// Get the time remaining for countdowns. Time Remaining() const { return data ? (data->target - data->time) : Time(); } + /// Get the iteration index for interval timers. int Iteration() const { return (data && data->target > Time()) ? std::floor(data->time / data->target) : Time(); } + /// Check if the timer reached its interval or countdown goal this iteration. bool JustHit() const { return data && data->justHit; } + /// Unset the timer (does not stop other handles for a shared timer). void Clear() { if (data) { --data->refCount; data = 0; } } + /// Reset the timer, do not stop it if it's running. void Reset() { if (data) data->time = Time(); } + /// Restart the timer. + /// Only works if the timer was started at least once. void Restart() { if (data) { if (data->target > Time() && data->justHit) { @@ -95,6 +113,7 @@ private: }; +/// Tracker for timers, responsible for creating and updating them. template class Timers { @@ -102,6 +121,7 @@ public: Timers() { } public: + /// Move all timers forward by delta. void Update(Time delta) { for (typename std::list >::iterator i(data.begin()), end(data.end()); i != end;) { if (i->target > 0) { @@ -117,14 +137,19 @@ public: } } } + /// Start a timer that counts elapsed time until stopped manually. Timer