include/IrrlichtDevice.h

   1 // Copyright (C) 2002-2012 Nikolaus Gebhardt\r
   2 // This file is part of the "Irrlicht Engine".\r
   3 // For conditions of distribution and use, see copyright notice in irrlicht.h\r
   4 \r
   5 #ifndef __I_IRRLICHT_DEVICE_H_INCLUDED__\r
   6 #define __I_IRRLICHT_DEVICE_H_INCLUDED__\r
   7 \r
   8 #include "IReferenceCounted.h"\r
   9 #include "dimension2d.h"\r
  10 #include "IVideoDriver.h"\r
  11 #include "EDriverTypes.h"\r
  12 #include "EDeviceTypes.h"\r
  13 #include "IEventReceiver.h"\r
  14 #include "ICursorControl.h"\r
  15 #include "ITimer.h"\r
  16 #include "IOSOperator.h"\r
  17 #include "IrrCompileConfig.h"\r
  18 \r
  19 namespace irr\r
  20 {\r
  21         class ILogger;\r
  22         class IEventReceiver;\r
  23 \r
  24         namespace io {\r
  25                 class IFileSystem;\r
  26         } // end namespace io\r
  27 \r
  28         namespace gui {\r
  29                 class IGUIEnvironment;\r
  30         } // end namespace gui\r
  31 \r
  32         namespace scene {\r
  33                 class ISceneManager;\r
  34         } // end namespace scene\r
  35 \r
  36         namespace video {\r
  37                 class IContextManager;\r
  38                 extern "C" IRRLICHT_API bool IRRCALLCONV isDriverSupported(E_DRIVER_TYPE driver);\r
  39         } // end namespace video\r
  40 \r
  41         //! The Irrlicht device. You can create it with createDevice() or createDeviceEx().\r
  42         /** This is the most important class of the Irrlicht Engine. You can\r
  43         access everything in the engine if you have a pointer to an instance of\r
  44         this class.  There should be only one instance of this class at any\r
  45         time.\r
  46         */\r
  47         class IrrlichtDevice : public virtual IReferenceCounted\r
  48         {\r
  49         public:\r
  50 \r
  51                 //! Runs the device.\r
  52                 /** Also increments the virtual timer by calling\r
  53                 ITimer::tick();. You can prevent this\r
  54                 by calling ITimer::stop(); before and ITimer::start() after\r
  55                 calling IrrlichtDevice::run(). Returns false if device wants\r
  56                 to be deleted. Use it in this way:\r
  57                 \code\r
  58                 while(device->run())\r
  59                 {\r
  60                         // draw everything here\r
  61                 }\r
  62                 \endcode\r
  63                 If you want the device to do nothing if the window is inactive\r
  64                 (recommended), use the slightly enhanced code shown at isWindowActive().\r
  65 \r
  66                 Note if you are running Irrlicht inside an external, custom\r
  67                 created window: Calling Device->run() will cause Irrlicht to\r
  68                 dispatch windows messages internally.\r
  69                 If you are running Irrlicht in your own custom window, you can\r
  70                 also simply use your own message loop using GetMessage,\r
  71                 DispatchMessage and whatever and simply don't use this method.\r
  72                 But note that Irrlicht will not be able to fetch user input\r
  73                 then. See irr::SIrrlichtCreationParameters::WindowId for more\r
  74                 information and example code.\r
  75                 */\r
  76                 virtual bool run() = 0;\r
  77 \r
  78                 //! Cause the device to temporarily pause execution and let other processes run.\r
  79                 /** This should bring down processor usage without major\r
  80                 performance loss for Irrlicht */\r
  81                 virtual void yield() = 0;\r
  82 \r
  83                 //! Pause execution and let other processes to run for a specified amount of time.\r
  84                 /** It may not wait the full given time, as sleep may be interrupted\r
  85                 \param timeMs: Time to sleep for in milliseconds.\r
  86                 \param pauseTimer: If true, pauses the device timer while sleeping\r
  87                 */\r
  88                 virtual void sleep(u32 timeMs, bool pauseTimer=false) = 0;\r
  89 \r
  90                 //! Provides access to the video driver for drawing 3d and 2d geometry.\r
  91                 /** \return Pointer the video driver. */\r
  92                 virtual video::IVideoDriver* getVideoDriver() = 0;\r
  93 \r
  94                 //! Provides access to the virtual file system.\r
  95                 /** \return Pointer to the file system. */\r
  96                 virtual io::IFileSystem* getFileSystem() = 0;\r
  97 \r
  98                 //! Provides access to the 2d user interface environment.\r
  99                 /** \return Pointer to the gui environment. */\r
 100                 virtual gui::IGUIEnvironment* getGUIEnvironment() = 0;\r
 101 \r
 102                 //! Provides access to the scene manager.\r
 103                 /** \return Pointer to the scene manager. */\r
 104                 virtual scene::ISceneManager* getSceneManager() = 0;\r
 105 \r
 106                 //! Provides access to the cursor control.\r
 107                 /** \return Pointer to the mouse cursor control interface. */\r
 108                 virtual gui::ICursorControl* getCursorControl() = 0;\r
 109 \r
 110                 //! Provides access to the message logger.\r
 111                 /** \return Pointer to the logger. */\r
 112                 virtual ILogger* getLogger() = 0;\r
 113 \r
 114                 //! Get context manager\r
 115                 virtual video::IContextManager* getContextManager() = 0;\r
 116 \r
 117                 //! Provides access to the operation system operator object.\r
 118                 /** The OS operator provides methods for\r
 119                 getting system specific information and doing system\r
 120                 specific operations, such as exchanging data with the clipboard\r
 121                 or reading the operation system version.\r
 122                 \return Pointer to the OS operator. */\r
 123                 virtual IOSOperator* getOSOperator() = 0;\r
 124 \r
 125                 //! Provides access to the engine's timer.\r
 126                 /** The system time can be retrieved by it as\r
 127                 well as the virtual time, which also can be manipulated.\r
 128                 \return Pointer to the ITimer object. */\r
 129                 virtual ITimer* getTimer() = 0;\r
 130 \r
 131                 //! Sets the caption of the window.\r
 132                 /** \param text: New text of the window caption. */\r
 133                 virtual void setWindowCaption(const wchar_t* text) = 0;\r
 134 \r
 135                 //! Returns if the window is active.\r
 136                 /** If the window is inactive,\r
 137                 nothing needs to be drawn. So if you don't want to draw anything\r
 138                 when the window is inactive, create your drawing loop this way:\r
 139                 \code\r
 140                 while(device->run())\r
 141                 {\r
 142                         if (device->isWindowActive())\r
 143                         {\r
 144                                 // draw everything here\r
 145                         }\r
 146                         else\r
 147                                 device->yield();\r
 148                 }\r
 149                 \endcode\r
 150                 \return True if window is active. */\r
 151                 virtual bool isWindowActive() const = 0;\r
 152 \r
 153                 //! Checks if the Irrlicht window has the input focus\r
 154                 /** \return True if window has focus. */\r
 155                 virtual bool isWindowFocused() const = 0;\r
 156 \r
 157                 //! Checks if the Irrlicht window is minimized\r
 158                 /** \return True if window is minimized. */\r
 159                 virtual bool isWindowMinimized() const = 0;\r
 160 \r
 161                 //! Checks if the Irrlicht window is maximized\r
 162                 //! Only fully works on SDL. Returns false, or the last value set via\r
 163                 //! maximizeWindow() and restoreWindow(), on other backends.\r
 164                 /** \return True if window is maximized. */\r
 165                 virtual bool isWindowMaximized() const = 0;\r
 166 \r
 167                 //! Checks if the Irrlicht window is running in fullscreen mode\r
 168                 /** \return True if window is fullscreen. */\r
 169                 virtual bool isFullscreen() const = 0;\r
 170 \r
 171                 //! Get the current color format of the window\r
 172                 /** \return Color format of the window. */\r
 173                 virtual video::ECOLOR_FORMAT getColorFormat() const = 0;\r
 174 \r
 175                 //! Notifies the device that it should close itself.\r
 176                 /** IrrlichtDevice::run() will always return false after closeDevice() was called. */\r
 177                 virtual void closeDevice() = 0;\r
 178 \r
 179                 //! Get the version of the engine.\r
 180                 /** The returned string\r
 181                 will look like this: "1.2.3" or this: "1.2".\r
 182                 \return String which contains the version. */\r
 183                 virtual const c8* getVersion() const = 0;\r
 184 \r
 185                 //! Sets a new user event receiver which will receive events from the engine.\r
 186                 /** Return true in IEventReceiver::OnEvent to prevent the event from continuing along\r
 187                 the chain of event receivers. The path that an event takes through the system depends\r
 188                 on its type. See irr::EEVENT_TYPE for details.\r
 189                 \param receiver New receiver to be used. */\r
 190                 virtual void setEventReceiver(IEventReceiver* receiver) = 0;\r
 191 \r
 192                 //! Provides access to the current event receiver.\r
 193                 /** \return Pointer to the current event receiver. Returns 0 if there is none. */\r
 194                 virtual IEventReceiver* getEventReceiver() = 0;\r
 195 \r
 196                 //! Sends a user created event to the engine.\r
 197                 /** Is is usually not necessary to use this. However, if you\r
 198                 are using an own input library for example for doing joystick\r
 199                 input, you can use this to post key or mouse input events to\r
 200                 the engine. Internally, this method only delegates the events\r
 201                 further to the scene manager and the GUI environment. */\r
 202                 virtual bool postEventFromUser(const SEvent& event) = 0;\r
 203 \r
 204                 //! Sets the input receiving scene manager.\r
 205                 /** If set to null, the main scene manager (returned by\r
 206                 GetSceneManager()) will receive the input\r
 207                 \param sceneManager New scene manager to be used. */\r
 208                 virtual void setInputReceivingSceneManager(scene::ISceneManager* sceneManager) = 0;\r
 209 \r
 210                 //! Sets if the window should be resizable in windowed mode.\r
 211                 /** The default is false. This method only works in windowed\r
 212                 mode.\r
 213                 \param resize Flag whether the window should be resizable. */\r
 214                 virtual void setResizable(bool resize=false) = 0;\r
 215 \r
 216                 //! Resize the render window.\r
 217                 /**     This will only work in windowed mode and is not yet supported on all systems.\r
 218                 It does set the drawing/clientDC size of the window, the window decorations are added to that.\r
 219                 You get the current window size with IVideoDriver::getScreenSize() (might be unified in future)\r
 220                 */\r
 221                 virtual void setWindowSize(const irr::core::dimension2d<u32>& size) = 0;\r
 222 \r
 223                 //! Minimizes the window if possible.\r
 224                 virtual void minimizeWindow() =0;\r
 225 \r
 226                 //! Maximizes the window if possible.\r
 227                 virtual void maximizeWindow() =0;\r
 228 \r
 229                 //! Restore the window to normal size if possible.\r
 230                 virtual void restoreWindow() =0;\r
 231 \r
 232                 //! Get the position of the frame on-screen\r
 233                 virtual core::position2di getWindowPosition() = 0;\r
 234 \r
 235                 //! Activate any joysticks, and generate events for them.\r
 236                 /** Irrlicht contains support for joysticks, but does not generate joystick events by default,\r
 237                 as this would consume joystick info that 3rd party libraries might rely on. Call this method to\r
 238                 activate joystick support in Irrlicht and to receive irr::SJoystickEvent events.\r
 239                 \param joystickInfo On return, this will contain an array of each joystick that was found and activated.\r
 240                 \return true if joysticks are supported on this device, false if joysticks are not\r
 241                              supported or support is compiled out.\r
 242                 */\r
 243                 virtual bool activateJoysticks(core::array<SJoystickInfo>& joystickInfo) =0;\r
 244 \r
 245         //! Activate accelerometer.\r
 246         virtual bool activateAccelerometer(float updateInterval = 0.016666f) = 0;\r
 247 \r
 248         //! Deactivate accelerometer.\r
 249         virtual bool deactivateAccelerometer() = 0;\r
 250 \r
 251         //! Is accelerometer active.\r
 252         virtual bool isAccelerometerActive() = 0;\r
 253 \r
 254         //! Is accelerometer available.\r
 255         virtual bool isAccelerometerAvailable() = 0;\r
 256 \r
 257         //! Activate gyroscope.\r
 258         virtual bool activateGyroscope(float updateInterval = 0.016666f) = 0;\r
 259 \r
 260         //! Deactivate gyroscope.\r
 261         virtual bool deactivateGyroscope() = 0;\r
 262 \r
 263         //! Is gyroscope active.\r
 264         virtual bool isGyroscopeActive() = 0;\r
 265 \r
 266         //! Is gyroscope available.\r
 267         virtual bool isGyroscopeAvailable() = 0;\r
 268 \r
 269         //! Activate device motion.\r
 270         virtual bool activateDeviceMotion(float updateInterval = 0.016666f) = 0;\r
 271 \r
 272         //! Deactivate device motion.\r
 273         virtual bool deactivateDeviceMotion() = 0;\r
 274 \r
 275         //! Is device motion active.\r
 276         virtual bool isDeviceMotionActive() = 0;\r
 277 \r
 278         //! Is device motion available.\r
 279         virtual bool isDeviceMotionAvailable() = 0;\r
 280 \r
 281                 //! Set the maximal elapsed time between 2 clicks to generate doubleclicks for the mouse. It also affects tripleclick behavior.\r
 282                 /** When set to 0 no double- and tripleclicks will be generated.\r
 283                 \param timeMs maximal time in milliseconds for two consecutive clicks to be recognized as double click\r
 284                 */\r
 285                 virtual void setDoubleClickTime(u32 timeMs) =0;\r
 286 \r
 287                 //! Get the maximal elapsed time between 2 clicks to generate double- and tripleclicks for the mouse.\r
 288                 /** When return value is 0 no double- and tripleclicks will be generated.\r
 289                 \return maximal time in milliseconds for two consecutive clicks to be recognized as double click\r
 290                 */\r
 291                 virtual u32 getDoubleClickTime() const =0;\r
 292 \r
 293                 //! Remove messages pending in the system message loop\r
 294                 /** This function is usually used after messages have been buffered for a longer time, for example\r
 295                 when loading a large scene. Clearing the message loop prevents that mouse- or buttonclicks which users\r
 296                 have pressed in the meantime will now trigger unexpected actions in the gui. <br>\r
 297                 So far the following messages are cleared:<br>\r
 298                 Win32: All keyboard and mouse messages<br>\r
 299                 Linux: All keyboard and mouse messages<br>\r
 300                 All other devices are not yet supported here.<br>\r
 301                 The function is still somewhat experimental, as the kind of messages we clear is based on just a few use-cases.\r
 302                 If you think further messages should be cleared, or some messages should not be cleared here, then please tell us. */\r
 303                 virtual void clearSystemMessages() = 0;\r
 304 \r
 305                 //! Get the type of the device.\r
 306                 /** This allows the user to check which windowing system is currently being\r
 307                 used. */\r
 308                 virtual E_DEVICE_TYPE getType() const = 0;\r
 309 \r
 310                 //! Check if a driver type is supported by the engine.\r
 311                 /** Even if true is returned the driver may not be available\r
 312                 for a configuration requested when creating the device. */\r
 313                 static bool isDriverSupported(video::E_DRIVER_TYPE driver)\r
 314                 {\r
 315                         return video::isDriverSupported(driver);\r
 316                 }\r
 317         };\r
 318 \r
 319 } // end namespace irr\r
 320 \r
 321 #endif\r
 322 \r