dali/devel-api/adaptor-framework/gl-window.h

   1 #ifndef DALI_GL_WINDOW_H
   2 #define DALI_GL_WINDOW_H
   3
   4 /*
   5  * Copyright (c) 2021 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/adaptor-framework/window-enumerations.h>
  23 #include <dali/public-api/math/rect.h>
  24 #include <dali/public-api/math/uint-16-pair.h>
  25 #include <dali/public-api/math/vector2.h>
  26 #include <dali/public-api/math/vector4.h>
  27 #include <dali/public-api/object/any.h>
  28 #include <dali/public-api/object/base-handle.h>
  29 #include <dali/public-api/signals/dali-signal.h>
  30 #include <string>
  31
  32 // INTERNAL INCLUDES
  33 #include <dali/public-api/dali-adaptor-common.h>
  34
  35 namespace Dali
  36 {
  37 /**
  38  * @addtogroup dali_adaptor_framework
  39  * @{
  40  */
  41
  42 typedef Dali::Rect<int> PositionSize;
  43
  44 namespace Internal DALI_INTERNAL
  45 {
  46 namespace Adaptor
  47 {
  48 class GlWindow;
  49 }
  50 } // namespace DALI_INTERNAL
  51
  52 class TouchEvent;
  53 class KeyEvent;
  54
  55 /**
  56  * @brief The GlWindow class is to draw with native GLES.
  57  *
  58  * This class is the special window. It is for native GLES application.
  59  * So, some special funtions and type are supported.
  60  * In addition, basic window's functions are supported, too.
  61  *
  62  */
  63 class DALI_ADAPTOR_API GlWindow : public BaseHandle
  64 {
  65 public:
  66   using WindowSize = Uint16Pair;
  67
  68   typedef Signal<void(const KeyEvent&)>   KeyEventSignalType;          ///< GlWindow Key Event signal type
  69   typedef Signal<void(const TouchEvent&)> TouchEventSignalType;        ///< GlWindow Touch Event signal type
  70   typedef Signal<void(GlWindow, bool)>    FocusChangeSignalType;       ///< GlWindow Focus signal type
  71   typedef Signal<void(WindowSize)>        ResizeSignalType;            ///< GlWindow resize signal type
  72   typedef Signal<void(GlWindow, bool)>    VisibilityChangedSignalType; ///< GlWindow visibility change signal type
  73
  74 public:
  75   // Enumerations
  76
  77   /**
  78    * @brief Enumeration for GLES verion
  79    *
  80    * This Enumeration is used the GLES version for EGL configuration.
  81    * If the device can not support GLES version 3.0 over, the version will be chosen with GLES version 2.0
  82    *
  83    */
  84   enum class GlesVersion
  85   {
  86     VERSION_2_0 = 0, ///< GLES version 2.0
  87     VERSION_3_0,     ///< GLES version 3.0
  88   };
  89
  90   /**
  91    * @brief Enumeration for rendering mode
  92    *
  93    * This Enumeration is used to choose the rendering mode.
  94    * It has two options.
  95    * One of them is continuous mode. It is rendered continuously.
  96    * The other is on demand mode. It is rendered by application.
  97    */
  98   enum class RenderingMode
  99   {
 100     CONTINUOUS, ///< continuous mode
 101     ON_DEMAND   ///< on demand by application
 102   };
 103
 104   /**
 105    * @brief Creates an initialized handle to a new GlWindow.
 106    *
 107    * @return A new GlWindow
 108    * @note This creates an extra GlWindow in addition to the default main GlWindow
 109    */
 110   static GlWindow New();
 111
 112   /**
 113    * @brief Creates an initialized handle to a new GlWindow.
 114    *
 115    * @param[in] positionSize The position and size of the GlWindow
 116    * @param[in] name The GlWindow title
 117    * @param[in] className The GlWindow class name
 118    * @param[in] isTransparent Whether GlWindow is transparent
 119    * @note This creates an extra GlWindow in addition to the default main GlWindow
 120    * @return A new GlWindow
 121    */
 122   static GlWindow New(PositionSize positionSize, const std::string& name, const std::string& className, bool isTransparent = false);
 123
 124   /**
 125    * @brief Creates an uninitialized handle.
 126    *
 127    * This can be initialized using Dali::Application::GetGlWindow() or
 128    * Dali::GlWindow::New().
 129    *
 130    */
 131   GlWindow();
 132
 133   /**
 134    * @brief Destructor.
 135    *
 136    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 137    *
 138    */
 139   ~GlWindow();
 140
 141   /**
 142    * @brief This copy constructor is required for (smart) pointer semantics.
 143    *
 144    * @param[in] handle A reference to the copied handle
 145    */
 146   GlWindow(const GlWindow& handle);
 147
 148   /**
 149    * @brief This assignment operator is required for (smart) pointer semantics.
 150    *
 151    * @param[in] rhs A reference to the copied handle
 152    * @return A reference to this
 153    */
 154   GlWindow& operator=(const GlWindow& rhs);
 155
 156   /**
 157    * @brief Move constructor.
 158    *
 159    * @param[in] rhs A reference to the moved handle
 160    */
 161   GlWindow(GlWindow&& rhs);
 162
 163   /**
 164    * @brief Move assignment operator.
 165    *
 166    * @param[in] rhs A reference to the moved handle
 167    * @return A reference to this handle
 168    */
 169   GlWindow& operator=(GlWindow&& rhs);
 170
 171   /**
 172    * @brief Sets graphics configuration for GlWindow
 173    *
 174    * @param[in] depth the flag of depth buffer. If true is set, 24bit depth buffer is enabled.
 175    * @param[in] stencil the flag of stencil. it true is set, 8bit stencil buffer is enabled.
 176    * @param[in] msaa the bit of msaa.
 177    * @param[in] version the GLES version
 178    *
 179    */
 180   void SetGraphicsConfig(bool depth, bool stencil, int msaa, GlesVersion version);
 181
 182   /**
 183    * @brief Raises GlWindow to the top of GlWindow stack.
 184    *
 185    */
 186   void Raise();
 187
 188   /**
 189    * @brief Lowers GlWindow to the bottom of GlWindow stack.
 190    *
 191    */
 192   void Lower();
 193
 194   /**
 195    * @brief Activates GlWindow to the top of GlWindow stack even it is iconified.
 196    *
 197    */
 198   void Activate();
 199
 200   /**
 201    * @brief Shows the GlWindow if it is hidden.
 202    *
 203    */
 204   void Show();
 205
 206   /**
 207    * @brief Hides the GlWindow if it is showing.
 208    *
 209    */
 210   void Hide();
 211
 212   /**
 213    * @brief Sets a position of the GlWindow.
 214    *
 215    * @param[in] positionSize The new GlWindow position
 216    */
 217   void SetPositionSize(PositionSize positionSize);
 218
 219   /**
 220    * @brief Gets a position of the GlWindow.
 221    *
 222    * @return The position of the GlWindow
 223    */
 224   PositionSize GetPositionSize() const;
 225
 226   /**
 227    * @brief Gets the count of supported auxiliary hints of the window.
 228    *
 229    * @return The number of supported auxiliary hints.
 230    *
 231    * @note The window auxiliary hint is the value which is used to decide which actions should be made available to the user by the window manager.
 232    * If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
 233    */
 234   unsigned int GetSupportedAuxiliaryHintCount() const;
 235
 236   /**
 237    * @brief Gets the supported auxiliary hint string of the window.
 238    *
 239    * @param[in] index The index of the supported auxiliary hint lists
 240    * @return The auxiliary hint string of the index.
 241    *
 242    * @note The window auxiliary hint is the value which is used to decide which actions should be made available to the user by the window manager.
 243    * If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
 244    */
 245   std::string GetSupportedAuxiliaryHint(unsigned int index) const;
 246
 247   /**
 248    * @brief Creates an auxiliary hint of the window.
 249    *
 250    * @param[in] hint The auxiliary hint string.
 251    * @param[in] value The value string.
 252    * @return The ID of created auxiliary hint, or @c 0 on failure.
 253    */
 254   unsigned int AddAuxiliaryHint(const std::string& hint, const std::string& value);
 255
 256   /**
 257    * @brief Removes an auxiliary hint of the window.
 258    *
 259    * @param[in] id The ID of the auxiliary hint.
 260    * @return True if no error occurred, false otherwise.
 261    */
 262   bool RemoveAuxiliaryHint(unsigned int id);
 263
 264   /**
 265    * @brief Changes a value of the auxiliary hint.
 266    *
 267    * @param[in] id The auxiliary hint ID.
 268    * @param[in] value The value string to be set.
 269    * @return True if no error occurred, false otherwise.
 270    */
 271   bool SetAuxiliaryHintValue(unsigned int id, const std::string& value);
 272
 273   /**
 274    * @brief Gets a value of the auxiliary hint.
 275    *
 276    * @param[in] id The auxiliary hint ID.
 277    * @return The string value of the auxiliary hint ID, or an empty string if none exists.
 278    */
 279   std::string GetAuxiliaryHintValue(unsigned int id) const;
 280
 281   /**
 282    * @brief Gets a ID of the auxiliary hint string.
 283    *
 284    * @param[in] hint The auxiliary hint string.
 285    * @return The ID of the auxiliary hint string, or @c 0 if none exists.
 286    */
 287   unsigned int GetAuxiliaryHintId(const std::string& hint) const;
 288
 289   /**
 290    * @brief Sets a region to accept input events.
 291    *
 292    * @param[in] inputRegion The region to accept input events.
 293    */
 294   void SetInputRegion(const Rect<int>& inputRegion);
 295
 296   /**
 297    * @brief Sets a transparent window's visual state to opaque.
 298    * @details If a visual state of a transparent window is opaque,
 299    * then the window manager could handle it as an opaque window when calculating visibility.
 300    *
 301    * @param[in] opaque Whether the window's visual state is opaque.
 302    * @remarks This will have no effect on an opaque window.
 303    * It doesn't change transparent window to opaque window but lets the window manager know the visual state of the window.
 304    */
 305   void SetOpaqueState(bool opaque);
 306
 307   /**
 308    * @brief Returns whether a transparent window's visual state is opaque or not.
 309    *
 310    * @return True if the window's visual state is opaque, false otherwise.
 311    * @remarks The return value has no meaning on an opaque window.
 312    */
 313   bool IsOpaqueState() const;
 314
 315   /**
 316    * @brief Gets current rotation angle of the window.
 317    *
 318    * @return The current GlWindow rotation angle if previously set, or none
 319    */
 320   WindowOrientation GetCurrentOrientation() const;
 321
 322   /**
 323     * @brief Sets available orientations of the window.
 324     *
 325     * This API is for setting several orientations one time.
 326     *
 327     * @param[in] orientations The available orientations list to add
 328     */
 329   void SetAvailableOrientations(const Dali::Vector<WindowOrientation>& orientations);
 330
 331   /**
 332    * @brief Sets a preferred orientation.
 333    *
 334    * @param[in] orientation The preferred orientation
 335    * @pre angle is in the list of available orientation.
 336    *
 337    * @note To unset the preferred orientation, angle should be set NO_ORIENTATION_PREFERENCE.
 338    */
 339   void SetPreferredOrientation(WindowOrientation orientation);
 340
 341   /**
 342    * @brief Registers a GL callback function for application.
 343    *
 344    * @param[in] initCallback  the callback function for application initialize
 345    * @param[in] renderFrameCallback the callback function to render for the frame.
 346    * @param[in] terminateCallback the callback function to clean-up application GL resource.
 347    *
 348    * @note Function must be called on idle time
 349    *
 350    * A initCallback of the following type should be used:
 351    * @code
 352    *   void intializeGL();
 353    * @endcode
 354    * This callback will be called before renderFrame callback is called at once.
 355    *
 356    * A renderFrameCallback of the following type should be used:
 357    * @code
 358    *   int renderFrameGL();
 359    * @endcode
 360    * This callback's return value is not 0, the eglSwapBuffers() will be called.
 361    *
 362    * A terminateCallback of the following type should be used:
 363    * @code
 364    *   void terminateGL();
 365    * @endcode
 366    * This callback is called when GlWindow is deleted.
 367    */
 368   void RegisterGlCallbacks(CallbackBase* initCallback, CallbackBase* renderFrameCallback, CallbackBase* terminateCallback);
 369
 370   /**
 371    * @brief Renders once more even if GL render functions are not added to idler.
 372    * @note Will not work if the window is hidden or GL render functions are added to idler
 373    *
 374    */
 375   void RenderOnce();
 376
 377   /**
 378    * @brief Sets rendering mode.
 379    *
 380    * @param[in] mode the rendering mode for GlWindow
 381    *
 382    * @note The default Rendering mode is continuous.
 383    * If OnDemand mode is set, it is rendered by RenderOnce()
 384    */
 385   void SetRenderingMode(RenderingMode mode);
 386
 387   /**
 388    * @brief Gets rendering mode.
 389    *
 390    * @return current rendering mode in this GlWindow
 391    *
 392    * @note The default Rendering mode is continuous.
 393    * If OnDemand mode is set, it is rendered by RenderOnce()
 394    */
 395   RenderingMode GetRenderingMode() const;
 396
 397 public: // Signals
 398   /**
 399    * @brief The user should connect to this signal to get a timing when GlWindow gains focus or loses focus.
 400    *
 401    * A callback of the following type may be connected:
 402    * @code
 403    *   void YourCallbackName( GlWindow GlWindow, bool focusIn );
 404    * @endcode
 405    * The parameter is true if GlWindow gains focus, otherwise false.
 406    * and GlWindow means this signal was called from what GlWindow
 407    *
 408    * @return The signal to connect to
 409    */
 410   FocusChangeSignalType& FocusChangeSignal();
 411
 412   /**
 413    * @brief This signal is emitted when the GlWindow is resized.
 414    *
 415    * A callback of the following type may be connected:
 416    * @code
 417    *   void YourCallbackName( GlWindow GlWindow, int width, int height );
 418    * @endcode
 419    * The parameters are the resized width and height.
 420    * and GlWindow means this signal was called from what GlWindow
 421    *
 422    * @return The signal to connect to
 423    */
 424   ResizeSignalType& ResizeSignal();
 425
 426   /**
 427    * @brief This signal is emitted when key event is received.
 428    *
 429    * A callback of the following type may be connected:
 430    * @code
 431    *   void YourCallbackName(const KeyEvent& event);
 432    * @endcode
 433    *
 434    * @return The signal to connect to
 435    */
 436   KeyEventSignalType& KeyEventSignal();
 437
 438   /**
 439    * @brief This signal is emitted when the screen is touched and when the touch ends
 440    * (i.e. the down & up touch events only).
 441    *
 442    * If there are multiple touch points, then this will be emitted when the first touch occurs and
 443    * then when the last finger is lifted.
 444    * An interrupted event will also be emitted (if it occurs).
 445    * A callback of the following type may be connected:
 446    * @code
 447    *   void YourCallbackName(const TouchEvent& event);
 448    * @endcode
 449    *
 450    * @return The touch signal to connect to
 451    *
 452    * @note Motion events are not emitted.
 453    */
 454   TouchEventSignalType& TouchedSignal();
 455
 456   /**
 457    * @brief This signal is emitted when the window is shown or hidden.
 458    *
 459    * A callback of the following type may be connected:
 460    * @code
 461    *   void YourCallbackName( Window window, bool visible );
 462    * @endcode
 463    *
 464    * @return The signal to connect to
 465    */
 466   VisibilityChangedSignalType& VisibilityChangedSignal();
 467
 468 public: // Not intended for application developers
 469   /// @cond internal
 470   /**
 471    * @brief This constructor is used by Dali::Application::GetGlWindow().
 472    * @param[in] GlWindow A pointer to the GlWindow
 473    */
 474   explicit DALI_INTERNAL GlWindow(Internal::Adaptor::GlWindow* GlWindow);
 475   /// @endcond
 476 };
 477
 478 /**
 479  * @}
 480  */
 481 } // namespace Dali
 482
 483 #endif // DALI_GL_WINDOW_H