1 //
2 // Copyright (c) 2008-2017 the Urho3D project.
3 //
4 // Permission is hereby granted, free of charge, to any person obtaining a copy
5 // of this software and associated documentation files (the "Software"), to deal
6 // in the Software without restriction, including without limitation the rights
7 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 // copies of the Software, and to permit persons to whom the Software is
9 // furnished to do so, subject to the following conditions:
10 //
11 // The above copyright notice and this permission notice shall be included in
12 // all copies or substantial portions of the Software.
13 //
14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20 // THE SOFTWARE.
21 //
22 
23 #pragma once
24 
25 #include "../Core/Object.h"
26 #include "../Core/Timer.h"
27 
28 namespace Urho3D
29 {
30 
31 class Console;
32 class DebugHud;
33 
34 /// Urho3D engine. Creates the other subsystems.
35 class URHO3D_API Engine : public Object
36 {
37     URHO3D_OBJECT(Engine, Object);
38 
39 public:
40     /// Construct.
41     Engine(Context* context);
42     /// Destruct. Free all subsystems.
43     virtual ~Engine();
44 
45     /// Initialize engine using parameters given and show the application window. Return true if successful.
46     bool Initialize(const VariantMap& parameters);
47     /// Reinitialize resource cache subsystem using parameters given. Implicitly called by Initialize. Return true if successful.
48     bool InitializeResourceCache(const VariantMap& parameters, bool removeOld = true);
49     /// Run one frame.
50     void RunFrame();
51     /// Create the console and return it. May return null if engine configuration does not allow creation (headless mode.)
52     Console* CreateConsole();
53     /// Create the debug hud.
54     DebugHud* CreateDebugHud();
55     /// Set minimum frames per second. If FPS goes lower than this, time will appear to slow down.
56     void SetMinFps(int fps);
57     /// Set maximum frames per second. The engine will sleep if FPS is higher than this.
58     void SetMaxFps(int fps);
59     /// Set maximum frames per second when the application does not have input focus.
60     void SetMaxInactiveFps(int fps);
61     /// Set how many frames to average for timestep smoothing. Default is 2. 1 disables smoothing.
62     void SetTimeStepSmoothing(int frames);
63     /// Set whether to pause update events and audio when minimized.
64     void SetPauseMinimized(bool enable);
65     /// Set whether to exit automatically on exit request (window close button.)
66     void SetAutoExit(bool enable);
67     /// Override timestep of the next frame. Should be called in between RunFrame() calls.
68     void SetNextTimeStep(float seconds);
69     /// Close the graphics window and set the exit flag. No-op on iOS/tvOS, as an iOS/tvOS application can not legally exit.
70     void Exit();
71     /// Dump profiling information to the log.
72     void DumpProfiler();
73     /// Dump information of all resources to the log.
74     void DumpResources(bool dumpFileName = false);
75     /// Dump information of all memory allocations to the log. Supported in MSVC debug mode only.
76     void DumpMemory();
77 
78     /// Get timestep of the next frame. Updated by ApplyFrameLimit().
GetNextTimeStep()79     float GetNextTimeStep() const { return timeStep_; }
80 
81     /// Return the minimum frames per second.
GetMinFps()82     int GetMinFps() const { return minFps_; }
83 
84     /// Return the maximum frames per second.
GetMaxFps()85     int GetMaxFps() const { return maxFps_; }
86 
87     /// Return the maximum frames per second when the application does not have input focus.
GetMaxInactiveFps()88     int GetMaxInactiveFps() const { return maxInactiveFps_; }
89 
90     /// Return how many frames to average for timestep smoothing.
GetTimeStepSmoothing()91     int GetTimeStepSmoothing() const { return timeStepSmoothing_; }
92 
93     /// Return whether to pause update events and audio when minimized.
GetPauseMinimized()94     bool GetPauseMinimized() const { return pauseMinimized_; }
95 
96     /// Return whether to exit automatically on exit request.
GetAutoExit()97     bool GetAutoExit() const { return autoExit_; }
98 
99     /// Return whether engine has been initialized.
IsInitialized()100     bool IsInitialized() const { return initialized_; }
101 
102     /// Return whether exit has been requested.
IsExiting()103     bool IsExiting() const { return exiting_; }
104 
105     /// Return whether the engine has been created in headless mode.
IsHeadless()106     bool IsHeadless() const { return headless_; }
107 
108     /// Send frame update events.
109     void Update();
110     /// Render after frame update.
111     void Render();
112     /// Get the timestep for the next frame and sleep for frame limiting if necessary.
113     void ApplyFrameLimit();
114 
115     /// Parse the engine startup parameters map from command line arguments.
116     static VariantMap ParseParameters(const Vector<String>& arguments);
117     /// Return whether startup parameters contains a specific parameter.
118     static bool HasParameter(const VariantMap& parameters, const String& parameter);
119     /// Get an engine startup parameter, with default value if missing.
120     static const Variant
121         & GetParameter(const VariantMap& parameters, const String& parameter, const Variant& defaultValue = Variant::EMPTY);
122 
123 private:
124     /// Handle exit requested event. Auto-exit if enabled.
125     void HandleExitRequested(StringHash eventType, VariantMap& eventData);
126     /// Actually perform the exit actions.
127     void DoExit();
128 
129     /// Frame update timer.
130     HiresTimer frameTimer_;
131     /// Previous timesteps for smoothing.
132     PODVector<float> lastTimeSteps_;
133     /// Next frame timestep in seconds.
134     float timeStep_;
135     /// How many frames to average for the smoothed timestep.
136     unsigned timeStepSmoothing_;
137     /// Minimum frames per second.
138     unsigned minFps_;
139     /// Maximum frames per second.
140     unsigned maxFps_;
141     /// Maximum frames per second when the application does not have input focus.
142     unsigned maxInactiveFps_;
143     /// Pause when minimized flag.
144     bool pauseMinimized_;
145 #ifdef URHO3D_TESTING
146     /// Time out counter for testing.
147     long long timeOut_;
148 #endif
149     /// Auto-exit flag.
150     bool autoExit_;
151     /// Initialized flag.
152     bool initialized_;
153     /// Exiting flag.
154     bool exiting_;
155     /// Headless mode flag.
156     bool headless_;
157     /// Audio paused flag.
158     bool audioPaused_;
159 };
160 
161 }
162