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