Add API to notify adaptor that scene has been created
[platform/core/uifw/dali-adaptor.git] / adaptors / integration-api / adaptor.h
1 #ifndef __DALI_INTEGRATION_ADAPTOR_H__
2 #define __DALI_INTEGRATION_ADAPTOR_H__
3
4 /*
5  * Copyright (c) 2014 Samsung Electronics Co., Ltd.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  *
19  */
20
21 // EXTERNAL INCLUDES
22 #include <dali/public-api/signals/callback.h>
23 #include <dali/public-api/signals/dali-signal.h>
24 #include <dali/public-api/math/rect.h>
25 #include <dali/public-api/events/touch-event.h>
26
27 // INTERNAL INCLUDES
28 #include "window.h"
29 #include "application-configuration.h"
30
31 namespace Dali
32 {
33
34 class RenderSurface;
35
36 namespace Internal
37 {
38 namespace Adaptor
39 {
40 class Adaptor;
41 }
42 }
43
44 /**
45  * @brief An Adaptor object is used to initialize and control how Dali runs.
46  *
47  * It provides a lifecycle interface that allows the application
48  * writer to provide their own main loop and other platform related
49  * features.
50  *
51  * The Adaptor class provides a means for initialising the resources required by the Dali::Core.
52  *
53  * When dealing with platform events, the application writer MUST ensure that Dali is called in a
54  * thread-safe manner.
55  *
56  * As soon as the Adaptor class is created and started, the application writer can initialise their
57  * Dali::Actor objects straight away or as required by the main loop they intend to use (there is no
58  * need to wait for an initialise signal as per the Dali::Application class).
59  *
60  * The Adaptor does emit a Resize signal which informs the user when the surface is resized.
61  * Tizen and Linux Adaptors should follow the example below:
62  *
63  * @code
64  * void CreateProgram(DaliAdaptor& adaptor)
65  * {
66  *   // Create Dali components...
67  *   // Can instantiate adaptor here instead, if required
68  * }
69  *
70  * int main ()
71  * {
72  *   // Initialise platform
73  *   MyPlatform.Init();
74  *
75  *   // Create an 800 by 1280 window positioned at (0,0).
76  *   Dali::PositionSize positionSize(0, 0, 800, 1280);
77  *   Dali::Window window = Dali::Window::New( positionSize, "My Application" );
78  *
79  *   // Create an adaptor which uses that window for rendering
80  *   Dali::Adaptor adaptor = Dali::Adaptor::New( window );
81  *   adaptor.Start();
82  *
83  *   CreateProgram(adaptor);
84  *   // Or use this as a callback function depending on the platform initialisation sequence.
85  *
86  *   // Start Main Loop of your platform
87  *   MyPlatform.StartMainLoop();
88  *
89  *   return 0;
90  * }
91  * @endcode
92  *
93  * If required, you can also connect class member functions to a signal:
94  *
95  * @code
96  * MyApplication application;
97  * adaptor.ResizedSignal().Connect(&application, &MyApplication::Resize);
98  * @endcode
99  *
100  * @see RenderSurface
101  */
102 class DALI_IMPORT_API Adaptor
103 {
104 public:
105
106   typedef Signal< void (Adaptor&) > AdaptorSignalType; ///< Generic Type for adaptor signals
107
108 public:
109   /**
110    * @brief Create a new adaptor using the window.
111    *
112    * @param[in] window The window to draw onto
113    * @return a reference to the adaptor handle
114    */
115   static Adaptor& New( Window window );
116
117   /**
118    * @brief Create a new adaptor using the window.
119    *
120    * @param[in] window The window to draw onto
121    * @param[in] configuration The context loss configuration.
122    * @return a reference to the adaptor handle
123    */
124   static Adaptor& New( Window window, Configuration::ContextLoss configuration );
125
126   /**
127    * @brief Create a new adaptor using render surface.
128    *
129    * @param[in] nativeWindow native window handle
130    * @param[in] surface The surface to draw onto
131    * @return a reference to the adaptor handle
132    */
133   static Adaptor& New( Any nativeWindow, const Dali::RenderSurface& surface );
134
135   /**
136    * @brief Create a new adaptor using render surface.
137    *
138    * @param[in] nativeWindow native window handle
139    * @param[in] surface The surface to draw onto
140    * @param[in] configuration The context loss configuration.
141    * @return a reference to the adaptor handle
142    */
143   static Adaptor& New( Any nativeWindow, const Dali::RenderSurface& surface, Configuration::ContextLoss configuration = Configuration::APPLICATION_DOES_NOT_HANDLE_CONTEXT_LOSS);
144
145   /**
146    * @brief Virtual Destructor.
147    */
148   virtual ~Adaptor();
149
150 public:
151
152   /**
153    * @brief Starts the Adaptor.
154    */
155   void Start();
156
157   /**
158    * @brief Pauses the Adaptor.
159    */
160   void Pause();
161
162   /**
163    * @brief Resumes the Adaptor, if previously paused.
164    *
165    * @note If the adaptor is not paused, this does not do anything.
166    */
167   void Resume();
168
169   /**
170    * @brief Stops the Adaptor.
171    */
172   void Stop();
173
174   /**
175    * @brief Ensures that the function passed in is called from the main loop when it is idle.
176    *
177    * A callback of the following type may be used:
178    * @code
179    *   void MyFunction();
180    * @endcode
181    *
182    * @param[in] callback The function to call.
183    * @return true if added successfully, false otherwise
184    *
185    * @note Ownership of the callback is passed onto this class.
186    */
187   bool AddIdle( CallbackBase* callback );
188
189   /**
190    * @brief Replaces the rendering surface
191    *
192    * @param[in] nativeWindow native window handle
193    * @param[in] surface to use
194    */
195   void ReplaceSurface( Any nativeWindow, Dali::RenderSurface& surface );
196
197   /**
198    * @brief Get the render surface the adaptor is using to render to.
199    *
200    * @return reference to current render surface
201    */
202   RenderSurface& GetSurface();
203
204   /**
205    * @brief Release any locks the surface may hold.
206    *
207    * For example, after compositing an offscreen surface, use this method to allow
208    * rendering to continue.
209    */
210   void ReleaseSurfaceLock();
211
212   /**
213    * @brief Set the number of frames per render.
214    *
215    * This enables an application to deliberately render with a reduced FPS.
216    * @param[in] numberOfVSyncsPerRender The number of vsyncs between successive renders.
217    * Suggest this is a power of two:
218    * 1 - render each vsync frame
219    * 2 - render every other vsync frame
220    * 4 - render every fourth vsync frame
221    * 8 - render every eighth vsync frame
222    */
223   void SetRenderRefreshRate( unsigned int numberOfVSyncsPerRender );
224
225   /**
226    * @brief Set whether the frame count per render is managed using the hardware VSync or
227    * manually timed.
228    *
229    * @param[in] useHardware True if the hardware VSync should be used
230    */
231   void SetUseHardwareVSync(bool useHardware);
232
233   /**
234    * @brief Returns a reference to the instance of the adaptor used by the current thread.
235    *
236    * @return A reference to the adaptor.
237    * @pre The adaptor has been initialised.
238    * @note This is only valid in the main thread.
239    */
240   static Adaptor& Get();
241
242   /**
243    * @brief Checks whether the adaptor is available.
244    *
245    * @return true, if it is available, false otherwise.
246    */
247   static bool IsAvailable();
248
249   /**
250    * @brief Call this method to notify Dali when scene is created and initialized.
251    *
252    * Notify Adaptor that the scene has been created.
253    */
254   void NotifySceneCreated();
255
256   /**
257    * @brief Call this method to notify Dali when the system language changes.
258    *
259    * Use this only when NOT using Dali::Application, As Application created using
260    * Dali::Application will automatically receive notification of language change.
261    * When Dali::Application is not used, the application developer should
262    * use app-core to receive language change notifications and should update Dali
263    * by calling this method.
264    */
265   void NotifyLanguageChanged();
266
267   /**
268    * @brief Sets minimum distance in pixels that the fingers must move towards/away from each other in order to
269    * trigger a pinch gesture
270    *
271    * @param[in] distance The minimum pinch distance in pixels
272    */
273   void SetMinimumPinchDistance(float distance);
274
275   /**
276    * @brief Feed a touch point to the adaptor.
277    *
278    * @param[in] point touch point
279    * @param[in] timeStamp time value of event
280    */
281   void FeedTouchPoint( TouchPoint& point, int timeStamp );
282
283   /**
284    * @brief Feed a wheel event to the adaptor.
285    *
286    * @param[in]  wheelEvent wheel event
287    */
288   void FeedWheelEvent( WheelEvent& wheelEvent );
289
290   /**
291    * @brief Feed a key event to the adaptor.
292    *
293    * @param[in] keyEvent The key event holding the key information.
294    */
295   void FeedKeyEvent( KeyEvent& keyEvent );
296
297 public:  // Signals
298
299   /**
300    * @brief The user should connect to this signal if they need to perform any
301    * special activities when the surface Dali is being rendered on is resized.
302    *
303    * @return The signal to connect to
304    */
305   AdaptorSignalType& ResizedSignal();
306
307   /**
308    * @brief This signal is emitted when the language is changed on the device.
309    *
310    * @return The signal to connect to
311    */
312   AdaptorSignalType& LanguageChangedSignal();
313
314 private:
315
316   // Undefined
317   Adaptor(const Adaptor&);
318   Adaptor& operator=(Adaptor&);
319
320 private:
321
322   /**
323    * @brief Create an uninitialized Adaptor.
324    */
325   Adaptor();
326
327   Internal::Adaptor::Adaptor* mImpl; ///< Implementation object
328   friend class Internal::Adaptor::Adaptor;
329 };
330
331 } // namespace Dali
332
333 #endif // __DALI_INTEGRATION_ADAPTOR_H__