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