Merge branch 'blender2.7'
[blender.git] / intern / ghost / GHOST_ISystem.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  *
16  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
17  * All rights reserved.
18  */
19
20 /** \file
21  * \ingroup GHOST
22  * %Main interface file for C++ Api with declaration of GHOST_ISystem interface
23  * class.
24  * Contains the doxygen documentation main page.
25  */
26
27 #ifndef __GHOST_ISYSTEM_H__
28 #define __GHOST_ISYSTEM_H__
29
30 #include "GHOST_Types.h"
31 #include "GHOST_IContext.h"
32 #include "GHOST_ITimerTask.h"
33 #include "GHOST_IWindow.h"
34
35 class GHOST_IEventConsumer;
36
37 /**
38  * \page GHOSTPage GHOST
39  *
40  * \section intro Introduction
41  *
42  * GHOST is yet another acronym. It stands for "Generic Handy Operating System
43  * Toolkit". It has been created to replace the OpenGL utility tool kit
44  * <a href="http://www.opengl.org/resources/libraries/glut/">GLUT</a>.
45  * GLUT was used in <a href="http://www.blender3d.com">Blender</a> until the
46  * point that Blender needed to be ported to Apple's Mac OSX. Blender needed a
47  * number of modifications in GLUT to work but the GLUT sources for OSX were
48  * unavailable at the time. The decision was made to build our own replacement
49  * for GLUT. In those days, NaN Technologies BV was the company that developed
50  * Blender.
51  * <br><br>
52  * Enough history. What does GHOST have to offer?<br>
53  * In short: everything that Blender needed from GLUT to run on all it's supported
54  * operating systems and some extra's.
55  * This includes :
56  *
57  * - Time(r) management.
58  * - Display/window management (windows are only created on the main display).
59  * - Event management.
60  * - Cursor shape management (no custom cursors for now).
61  * - Access to the state of the mouse buttons and the keyboard.
62  * - Menus for windows with events generated when they are accessed (this is
63  *   work in progress).
64  * - Video mode switching.
65  * - Copy/Paste buffers.
66  * - System paths.
67  *
68  * Font management has been moved to a separate library.
69  *
70  * \section platforms Platforms
71  *
72  * GHOST supports the following platforms:
73  *
74  * - OSX Cocoa.
75  * - Windows.
76  * - X11.
77  * - SDL2 (experimental).
78  * - NULL (headless mode).
79  *
80  * \section Building GHOST
81  *
82  * GHOST is not build standalone however there are tests in intern/ghost/test
83  *
84  * \section interface Interface
85  * GHOST has two programming interfaces:
86  *
87  * - The C-API. For programs written in C.
88  * - The C++-API. For programs written in C++.
89  *
90  * GHOST itself is written in C++ and the C-API is a wrapper around the C++
91  * API.
92  *
93  * \subsection cplusplus_api The C++ API consists of the following files:
94  *
95  * - GHOST_IEvent.h
96  * - GHOST_IEventConsumer.h
97  * - GHOST_ISystem.h
98  * - GHOST_ITimerTask.h
99  * - GHOST_IWindow.h
100  * - GHOST_Rect.h
101  * - GHOST_Types.h
102  *
103  * For an example of using the C++-API, have a look at the GHOST_C-Test.cpp
104  * program in the ?/ghost/test/gears/ directory.
105  *
106  * \subsection c_api The C-API
107  * To use GHOST in programs written in C, include the file GHOST_C-API.h in
108  * your program. This file includes the GHOST_Types.h file for all GHOST types
109  * and defines functions that give you access to the same functionality present
110  * in the C++ API.<br>
111  * For an example of using the C-API, have a look at the GHOST_C-Test.c program
112  * in the ?/ghost/test/gears/ directory.
113  *
114  * \section work Work in progress
115  * \todo write WIP section
116  */
117
118 /** \interface GHOST_ISystem
119  * Interface for classes that provide access to the operating system.
120  * There should be only one system class in an application.
121  * Therefore, the routines to create and dispose the system are static.
122  * Provides:
123  *  -# Time(r) management.
124  *  -# Display/window management (windows are only created on the main display).
125  *  -# Event management.
126  *  -# Cursor shape management (no custom cursors for now).
127  *  -# Access to the state of the mouse buttons and the keyboard.
128  *  -# Menus for windows with events generated when they are accessed (this is
129  *     work in progress).
130  */
131 class GHOST_ISystem
132 {
133 public:
134         /**
135          * Creates the one and only system.
136          * \return An indication of success.
137          */
138         static GHOST_TSuccess createSystem();
139
140         /**
141          * Disposes the one and only system.
142          * \return An indication of success.
143          */
144         static GHOST_TSuccess disposeSystem();
145
146         /**
147          * Returns a pointer to the one and only system (nil if it hasn't been created).
148          * \return A pointer to the system.
149          */
150         static GHOST_ISystem *getSystem();
151
152 protected:
153         /**
154          * Constructor.
155          * Protected default constructor to force use of static createSystem member.
156          */
157         GHOST_ISystem() {
158         }
159
160         /**
161          * Destructor.
162          * Protected default constructor to force use of static dispose member.
163          */
164         virtual ~GHOST_ISystem() {
165         }
166
167 public:
168         /***************************************************************************************
169          * Time(r) functionality
170          ***************************************************************************************/
171
172         /**
173          * Returns the system time.
174          * Returns the number of milliseconds since the start of the system process.
175          * Based on ANSI clock() routine.
176          * \return The number of milliseconds.
177          */
178         virtual GHOST_TUns64 getMilliSeconds() const = 0;
179
180         /**
181          * Installs a timer.
182          * Note that, on most operating systems, messages need to be processed in order
183          * for the timer callbacks to be invoked.
184          * \param delay     The time to wait for the first call to the timerProc (in milliseconds)
185          * \param interval  The interval between calls to the timerProc (in milliseconds)
186          * \param timerProc The callback invoked when the interval expires,
187          * \param userData  Placeholder for user data.
188          * \return A timer task (0 if timer task installation failed).
189          */
190         virtual GHOST_ITimerTask *installTimer(GHOST_TUns64 delay,
191                                                GHOST_TUns64 interval,
192                                                GHOST_TimerProcPtr timerProc,
193                                                GHOST_TUserDataPtr userData = NULL) = 0;
194
195         /**
196          * Removes a timer.
197          * \param timerTask Timer task to be removed.
198          * \return Indication of success.
199          */
200         virtual GHOST_TSuccess removeTimer(GHOST_ITimerTask *timerTask) = 0;
201
202         /***************************************************************************************
203          * Display/window management functionality
204          ***************************************************************************************/
205
206         /**
207          * Returns the number of displays on this system.
208          * \return The number of displays.
209          */
210         virtual GHOST_TUns8 getNumDisplays() const = 0;
211
212         /**
213          * Returns the dimensions of the main display on this system.
214          * \return The dimension of the main display.
215          */
216         virtual void getMainDisplayDimensions(GHOST_TUns32& width, GHOST_TUns32& height) const = 0;
217
218         /**
219          * Returns the combine dimensions of all monitors.
220          * \return The dimension of the workspace.
221          */
222         virtual void getAllDisplayDimensions(GHOST_TUns32& width, GHOST_TUns32& height) const = 0;
223
224         /**
225          * Create a new window.
226          * The new window is added to the list of windows managed.
227          * Never explicitly delete the window, use disposeWindow() instead.
228          * \param   title           The name of the window (displayed in the title bar of the window if the OS supports it).
229          * \param   left            The coordinate of the left edge of the window.
230          * \param   top             The coordinate of the top edge of the window.
231          * \param   width           The width the window.
232          * \param   height          The height the window.
233          * \param   state           The state of the window when opened.
234          * \param   type            The type of drawing context installed in this window.
235          * \param glSettings: Misc OpenGL settings.
236          * \param exclusive: Use to show the window ontop and ignore others (used fullscreen).
237          * \param   parentWindow    Parent (embedder) window
238          * \return  The new window (or 0 if creation failed).
239          */
240         virtual GHOST_IWindow *createWindow(
241                 const STR_String& title,
242                 GHOST_TInt32 left, GHOST_TInt32 top, GHOST_TUns32 width, GHOST_TUns32 height,
243                 GHOST_TWindowState state, GHOST_TDrawingContextType type,
244                 GHOST_GLSettings glSettings,
245                 const bool exclusive = false,
246                 const GHOST_TEmbedderWindowID parentWindow = 0) = 0;
247
248         /**
249          * Dispose a window.
250          * \param   window Pointer to the window to be disposed.
251          * \return  Indication of success.
252          */
253         virtual GHOST_TSuccess disposeWindow(GHOST_IWindow *window) = 0;
254
255         /**
256          * Create a new offscreen context.
257          * Never explicitly delete the context, use disposeContext() instead.
258          * \return  The new context (or 0 if creation failed).
259          */
260         virtual GHOST_IContext *createOffscreenContext() = 0;
261
262         /**
263          * Dispose of a context.
264          * \param   context Pointer to the context to be disposed.
265          * \return  Indication of success.
266          */
267         virtual GHOST_TSuccess disposeContext(GHOST_IContext *context) = 0;
268
269         /**
270          * Returns whether a window is valid.
271          * \param   window Pointer to the window to be checked.
272          * \return  Indication of validity.
273          */
274         virtual bool validWindow(GHOST_IWindow *window) = 0;
275
276         /**
277          * Begins full screen mode.
278          * \param setting   The new setting of the display.
279          * \param window    Window displayed in full screen.
280          *                  This window is invalid after full screen has been ended.
281          * \return  Indication of success.
282          */
283         virtual GHOST_TSuccess beginFullScreen(
284                 const GHOST_DisplaySetting& setting, GHOST_IWindow **window,
285                 const bool stereoVisual, const bool alphaBackground = 0, const GHOST_TUns16 numOfAASamples = 0) = 0;
286
287         /**
288          * Updates the resolution while in fullscreen mode.
289          * \param setting   The new setting of the display.
290          * \param window    Window displayed in full screen.
291          *
292          * \return  Indication of success.
293          */
294         virtual GHOST_TSuccess updateFullScreen(
295                 const GHOST_DisplaySetting& setting, GHOST_IWindow **window) = 0;
296
297         /**
298          * Ends full screen mode.
299          * \return  Indication of success.
300          */
301         virtual GHOST_TSuccess endFullScreen(void) = 0;
302
303         /**
304          * Returns current full screen mode status.
305          * \return The current status.
306          */
307         virtual bool getFullScreen(void) = 0;
308
309         /**
310          * Native pixel size support (MacBook 'retina').
311          */
312         virtual bool useNativePixel(void) = 0;
313
314         /**
315          * Focus window after opening, or put them in the background.
316          */
317         virtual void useWindowFocus(const bool use_focus) = 0;
318
319         /***************************************************************************************
320          * Event management functionality
321          ***************************************************************************************/
322
323         /**
324          * Retrieves events from the system and stores them in the queue.
325          * \param waitForEvent Flag to wait for an event (or return immediately).
326          * \return Indication of the presence of events.
327          */
328         virtual bool processEvents(bool waitForEvent) = 0;
329
330         /**
331          * Retrieves events from the queue and send them to the event consumers.
332          */
333         virtual void dispatchEvents() = 0;
334
335         /**
336          * Adds the given event consumer to our list.
337          * \param consumer The event consumer to add.
338          * \return Indication of success.
339          */
340         virtual GHOST_TSuccess addEventConsumer(GHOST_IEventConsumer *consumer) = 0;
341
342         /**
343          * Removes the given event consumer to our list.
344          * \param consumer The event consumer to remove.
345          * \return Indication of success.
346          */
347         virtual GHOST_TSuccess removeEventConsumer(GHOST_IEventConsumer *consumer) = 0;
348
349         /***************************************************************************************
350          * Cursor management functionality
351          ***************************************************************************************/
352
353         /**
354          * Returns the current location of the cursor (location in screen coordinates)
355          * \param x         The x-coordinate of the cursor.
356          * \param y         The y-coordinate of the cursor.
357          * \return          Indication of success.
358          */
359         virtual GHOST_TSuccess getCursorPosition(GHOST_TInt32& x, GHOST_TInt32& y) const = 0;
360
361         /**
362          * Updates the location of the cursor (location in screen coordinates).
363          * Not all operating systems allow the cursor to be moved (without the input device being moved).
364          * \param x         The x-coordinate of the cursor.
365          * \param y         The y-coordinate of the cursor.
366          * \return          Indication of success.
367          */
368         virtual GHOST_TSuccess setCursorPosition(GHOST_TInt32 x, GHOST_TInt32 y) = 0;
369
370         /***************************************************************************************
371          * Access to mouse button and keyboard states.
372          ***************************************************************************************/
373
374         /**
375          * Returns the state of a modifier key (ouside the message queue).
376          * \param mask      The modifier key state to retrieve.
377          * \param isDown    The state of a modifier key (true == pressed).
378          * \return          Indication of success.
379          */
380         virtual GHOST_TSuccess getModifierKeyState(GHOST_TModifierKeyMask mask, bool& isDown) const = 0;
381
382         /**
383          * Returns the state of a mouse button (ouside the message queue).
384          * \param mask      The button state to retrieve.
385          * \param isDown    Button state.
386          * \return          Indication of success.
387          */
388         virtual GHOST_TSuccess getButtonState(GHOST_TButtonMask mask, bool& isDown) const = 0;
389
390         /**
391          * Set which tablet API to use. Only affects Windows, other platforms have a single API.
392          * \param api Enum indicating which API to use.
393          */
394         virtual void setTabletAPI(GHOST_TTabletAPI api) = 0;
395
396 #ifdef WITH_INPUT_NDOF
397         /**
398          * Sets 3D mouse deadzone
399          * \param deadzone: Deadzone of the 3D mouse (both for rotation and pan) relative to full range
400          */
401         virtual void setNDOFDeadZone(float deadzone) = 0;
402 #endif
403
404         /**
405          * Toggles console
406          * \param action
407          * - 0: Hides
408          * - 1: Shows
409          * - 2: Toggles
410          * - 3: Hides if it runs not from  command line
411          * - *: Does nothing
412          * \return current status (1 -visible, 0 - hidden)
413          */
414         virtual int toggleConsole(int action) = 0;
415
416         /***************************************************************************************
417          * Access to clipboard.
418          ***************************************************************************************/
419
420         /**
421          * Returns the selection buffer
422          * \return "unsigned char" from X11 XA_CUT_BUFFER0 buffer
423          *
424          */
425         virtual GHOST_TUns8 *getClipboard(bool selection) const = 0;
426
427         /**
428          * Put data to the Clipboard
429          */
430         virtual void putClipboard(GHOST_TInt8 *buffer, bool selection) const = 0;
431
432         /**
433          * Confirms quitting he program when there is just one window left open
434          * in the application
435          */
436         virtual int confirmQuit(GHOST_IWindow *window) const = 0;
437
438         /**
439          * Informs if the system provides native dialogs (eg. confirm quit)
440          */
441         virtual bool supportsNativeDialogs(void) = 0;
442
443 protected:
444         /**
445          * Initialize the system.
446          * \return Indication of success.
447          */
448         virtual GHOST_TSuccess init() = 0;
449
450         /**
451          * Shut the system down.
452          * \return Indication of success.
453          */
454         virtual GHOST_TSuccess exit() = 0;
455
456         /** The one and only system */
457         static GHOST_ISystem *m_system;
458
459
460 #ifdef WITH_CXX_GUARDEDALLOC
461         MEM_CXX_CLASS_ALLOC_FUNCS("GHOST:GHOST_ISystem")
462 #endif
463 };
464
465 #endif // __GHOST_ISYSTEM_H__