Merge branch 'blender-v2.81-release'
[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  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   /**
161    * Destructor.
162    * Protected default constructor to force use of static dispose member.
163    */
164   virtual ~GHOST_ISystem()
165   {
166   }
167
168  public:
169   /***************************************************************************************
170    * Time(r) functionality
171    ***************************************************************************************/
172
173   /**
174    * Returns the system time.
175    * Returns the number of milliseconds since the start of the system process.
176    * Based on ANSI clock() routine.
177    * \return The number of milliseconds.
178    */
179   virtual GHOST_TUns64 getMilliSeconds() const = 0;
180
181   /**
182    * Installs a timer.
183    * Note that, on most operating systems, messages need to be processed in order
184    * for the timer callbacks to be invoked.
185    * \param delay     The time to wait for the first call to the timerProc (in milliseconds)
186    * \param interval  The interval between calls to the timerProc (in milliseconds)
187    * \param timerProc The callback invoked when the interval expires,
188    * \param userData  Placeholder for user data.
189    * \return A timer task (0 if timer task installation failed).
190    */
191   virtual GHOST_ITimerTask *installTimer(GHOST_TUns64 delay,
192                                          GHOST_TUns64 interval,
193                                          GHOST_TimerProcPtr timerProc,
194                                          GHOST_TUserDataPtr userData = NULL) = 0;
195
196   /**
197    * Removes a timer.
198    * \param timerTask Timer task to be removed.
199    * \return Indication of success.
200    */
201   virtual GHOST_TSuccess removeTimer(GHOST_ITimerTask *timerTask) = 0;
202
203   /***************************************************************************************
204    * Display/window management functionality
205    ***************************************************************************************/
206
207   /**
208    * Returns the number of displays on this system.
209    * \return The number of displays.
210    */
211   virtual GHOST_TUns8 getNumDisplays() const = 0;
212
213   /**
214    * Returns the dimensions of the main display on this system.
215    * \return The dimension of the main display.
216    */
217   virtual void getMainDisplayDimensions(GHOST_TUns32 &width, GHOST_TUns32 &height) const = 0;
218
219   /**
220    * Returns the combine dimensions of all monitors.
221    * \return The dimension of the workspace.
222    */
223   virtual void getAllDisplayDimensions(GHOST_TUns32 &width, GHOST_TUns32 &height) const = 0;
224
225   /**
226    * Create a new window.
227    * The new window is added to the list of windows managed.
228    * Never explicitly delete the window, use disposeWindow() instead.
229    * \param title: The name of the window
230    * (displayed in the title bar of the window if the OS supports it).
231    * \param left: The coordinate of the left edge of the window.
232    * \param top: The coordinate of the top edge of the window.
233    * \param width: The width the window.
234    * \param height: The height the window.
235    * \param state: The state of the window when opened.
236    * \param type: The type of drawing context installed in this window.
237    * \param glSettings: Misc OpenGL settings.
238    * \param exclusive: Use to show the window on top and ignore others (used full-screen).
239    * \param is_dialog: Stay on top of parent window, no icon in taskbar, can't be minimized.
240    * \param parentWindow: Parent (embedder) window
241    * \return The new window (or 0 if creation failed).
242    */
243   virtual GHOST_IWindow *createWindow(const STR_String &title,
244                                       GHOST_TInt32 left,
245                                       GHOST_TInt32 top,
246                                       GHOST_TUns32 width,
247                                       GHOST_TUns32 height,
248                                       GHOST_TWindowState state,
249                                       GHOST_TDrawingContextType type,
250                                       GHOST_GLSettings glSettings,
251                                       const bool exclusive = false,
252                                       const bool is_dialog = false,
253                                       const GHOST_IWindow *parentWindow = NULL) = 0;
254
255   /**
256    * Dispose a window.
257    * \param   window Pointer to the window to be disposed.
258    * \return  Indication of success.
259    */
260   virtual GHOST_TSuccess disposeWindow(GHOST_IWindow *window) = 0;
261
262   /**
263    * Create a new offscreen context.
264    * Never explicitly delete the context, use disposeContext() instead.
265    * \return  The new context (or 0 if creation failed).
266    */
267   virtual GHOST_IContext *createOffscreenContext() = 0;
268
269   /**
270    * Dispose of a context.
271    * \param   context Pointer to the context to be disposed.
272    * \return  Indication of success.
273    */
274   virtual GHOST_TSuccess disposeContext(GHOST_IContext *context) = 0;
275
276   /**
277    * Returns whether a window is valid.
278    * \param   window Pointer to the window to be checked.
279    * \return  Indication of validity.
280    */
281   virtual bool validWindow(GHOST_IWindow *window) = 0;
282
283   /**
284    * Begins full screen mode.
285    * \param setting   The new setting of the display.
286    * \param window    Window displayed in full screen.
287    *                  This window is invalid after full screen has been ended.
288    * \return  Indication of success.
289    */
290   virtual GHOST_TSuccess beginFullScreen(const GHOST_DisplaySetting &setting,
291                                          GHOST_IWindow **window,
292                                          const bool stereoVisual,
293                                          const bool alphaBackground = 0) = 0;
294
295   /**
296    * Updates the resolution while in fullscreen mode.
297    * \param setting   The new setting of the display.
298    * \param window    Window displayed in full screen.
299    *
300    * \return  Indication of success.
301    */
302   virtual GHOST_TSuccess updateFullScreen(const GHOST_DisplaySetting &setting,
303                                           GHOST_IWindow **window) = 0;
304
305   /**
306    * Ends full screen mode.
307    * \return  Indication of success.
308    */
309   virtual GHOST_TSuccess endFullScreen(void) = 0;
310
311   /**
312    * Returns current full screen mode status.
313    * \return The current status.
314    */
315   virtual bool getFullScreen(void) = 0;
316
317   /**
318    * Native pixel size support (MacBook 'retina').
319    */
320   virtual bool useNativePixel(void) = 0;
321
322   /**
323    * Focus window after opening, or put them in the background.
324    */
325   virtual void useWindowFocus(const bool use_focus) = 0;
326
327   /***************************************************************************************
328    * Event management functionality
329    ***************************************************************************************/
330
331   /**
332    * Retrieves events from the system and stores them in the queue.
333    * \param waitForEvent Flag to wait for an event (or return immediately).
334    * \return Indication of the presence of events.
335    */
336   virtual bool processEvents(bool waitForEvent) = 0;
337
338   /**
339    * Retrieves events from the queue and send them to the event consumers.
340    */
341   virtual void dispatchEvents() = 0;
342
343   /**
344    * Adds the given event consumer to our list.
345    * \param consumer The event consumer to add.
346    * \return Indication of success.
347    */
348   virtual GHOST_TSuccess addEventConsumer(GHOST_IEventConsumer *consumer) = 0;
349
350   /**
351    * Removes the given event consumer to our list.
352    * \param consumer The event consumer to remove.
353    * \return Indication of success.
354    */
355   virtual GHOST_TSuccess removeEventConsumer(GHOST_IEventConsumer *consumer) = 0;
356
357   /***************************************************************************************
358    * Cursor management functionality
359    ***************************************************************************************/
360
361   /**
362    * Returns the current location of the cursor (location in screen coordinates)
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 getCursorPosition(GHOST_TInt32 &x, GHOST_TInt32 &y) const = 0;
368
369   /**
370    * Updates the location of the cursor (location in screen coordinates).
371    * Not all operating systems allow the cursor to be moved (without the input device being moved).
372    * \param x         The x-coordinate of the cursor.
373    * \param y         The y-coordinate of the cursor.
374    * \return          Indication of success.
375    */
376   virtual GHOST_TSuccess setCursorPosition(GHOST_TInt32 x, GHOST_TInt32 y) = 0;
377
378   /***************************************************************************************
379    * Access to mouse button and keyboard states.
380    ***************************************************************************************/
381
382   /**
383    * Returns the state of a modifier key (ouside the message queue).
384    * \param mask      The modifier key state to retrieve.
385    * \param isDown    The state of a modifier key (true == pressed).
386    * \return          Indication of success.
387    */
388   virtual GHOST_TSuccess getModifierKeyState(GHOST_TModifierKeyMask mask, bool &isDown) const = 0;
389
390   /**
391    * Returns the state of a mouse button (ouside the message queue).
392    * \param mask      The button state to retrieve.
393    * \param isDown    Button state.
394    * \return          Indication of success.
395    */
396   virtual GHOST_TSuccess getButtonState(GHOST_TButtonMask mask, bool &isDown) const = 0;
397
398   /**
399    * Set which tablet API to use. Only affects Windows, other platforms have a single API.
400    * \param api Enum indicating which API to use.
401    */
402   virtual void setTabletAPI(GHOST_TTabletAPI api) = 0;
403
404 #ifdef WITH_INPUT_NDOF
405   /**
406    * Sets 3D mouse deadzone
407    * \param deadzone: Dead-zone of the 3D mouse (both for rotation and pan) relative to full range
408    */
409   virtual void setNDOFDeadZone(float deadzone) = 0;
410 #endif
411
412   /**
413    * Toggles console
414    * \param action
415    * - 0: Hides
416    * - 1: Shows
417    * - 2: Toggles
418    * - 3: Hides if it runs not from  command line
419    * - *: Does nothing
420    * \return current status (1 -visible, 0 - hidden)
421    */
422   virtual int toggleConsole(int action) = 0;
423
424   /***************************************************************************************
425    * Access to clipboard.
426    ***************************************************************************************/
427
428   /**
429    * Returns the selection buffer
430    * \return "unsigned char" from X11 XA_CUT_BUFFER0 buffer
431    *
432    */
433   virtual GHOST_TUns8 *getClipboard(bool selection) const = 0;
434
435   /**
436    * Put data to the Clipboard
437    */
438   virtual void putClipboard(GHOST_TInt8 *buffer, bool selection) const = 0;
439
440   /***************************************************************************************
441    * System Message Box.
442    ***************************************************************************************/
443
444   /**
445    * Show a system message box
446    *
447    * \param title                   The title of the message box
448    * \param message                 The message to display
449    * \param help_label              Help button label
450    * \param continue_label          Continue button label
451    * \param link                    An optional hyperlink
452    * \param dialog_options Options  how to display the message
453    */
454   virtual GHOST_TSuccess showMessageBox(const char * /*title*/,
455                                         const char * /*message*/,
456                                         const char * /*help_label*/,
457                                         const char * /*continue_label*/,
458                                         const char * /*link*/,
459                                         GHOST_DialogOptions /*dialog_options*/) const = 0;
460
461  protected:
462   /**
463    * Initialize the system.
464    * \return Indication of success.
465    */
466   virtual GHOST_TSuccess init() = 0;
467
468   /**
469    * Shut the system down.
470    * \return Indication of success.
471    */
472   virtual GHOST_TSuccess exit() = 0;
473
474   /** The one and only system */
475   static GHOST_ISystem *m_system;
476
477 #ifdef WITH_CXX_GUARDEDALLOC
478   MEM_CXX_CLASS_ALLOC_FUNCS("GHOST:GHOST_ISystem")
479 #endif
480 };
481
482 #endif  // __GHOST_ISYSTEM_H__