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