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 class 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& ) >      TouchEventSignalType;         ///< GlWindow Touch Event signal type
  77   typedef Signal< void ( GlWindow, bool ) >         FocusChangeSignalType;        ///< GlWindow Focus signal type
  78   typedef Signal< void ( WindowSize ) >             ResizeSignalType;             ///< GlWindow resize 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 Move constructor.
 167    *
 168    * @param[in] rhs A reference to the moved handle
 169    */
 170   GlWindow(GlWindow&& rhs);
 171
 172   /**
 173    * @brief Move assignment operator.
 174    *
 175    * @param[in] rhs A reference to the moved handle
 176    * @return A reference to this handle
 177    */
 178   GlWindow& operator=(GlWindow&& rhs);
 179
 180   /**
 181    * @brief Sets egl configuration for GlWindow
 182    *
 183    * @param[in] depth the flag of depth buffer. If true is set, 24bit depth buffer is enabled.
 184    * @param[in] stencil the flag of stencil. it true is set, 8bit stencil buffer is enabled.
 185    * @param[in] msaa the bit of msaa.
 186    * @param[in] version the GLES version
 187    *
 188    */
 189   void SetEglConfig( bool depth, bool stencil, int msaa, GlesVersion version );
 190
 191   /**
 192    * @brief Raises GlWindow to the top of GlWindow stack.
 193    *
 194    */
 195   void Raise();
 196
 197   /**
 198    * @brief Lowers GlWindow to the bottom of GlWindow stack.
 199    *
 200    */
 201   void Lower();
 202
 203   /**
 204    * @brief Activates GlWindow to the top of GlWindow stack even it is iconified.
 205    *
 206    */
 207   void Activate();
 208
 209   /**
 210    * @brief Shows the GlWindow if it is hidden.
 211    *
 212    */
 213   void Show();
 214
 215   /**
 216    * @brief Hides the GlWindow if it is showing.
 217    *
 218    */
 219   void Hide();
 220
 221   /**
 222    * @brief Sets a position of the GlWindow.
 223    *
 224    * @param[in] positionSize The new GlWindow position
 225    */
 226   void SetPositionSize( PositionSize positionSize );
 227
 228   /**
 229    * @brief Gets a position of the GlWindow.
 230    *
 231    * @return The position of the GlWindow
 232    */
 233   PositionSize GetPositionSize() const;
 234
 235   /**
 236    * @brief Gets the count of supported auxiliary hints of the window.
 237    *
 238    * @return The number of supported auxiliary hints.
 239    *
 240    * @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.
 241    * If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
 242    */
 243   unsigned int GetSupportedAuxiliaryHintCount() const;
 244
 245   /**
 246    * @brief Gets the supported auxiliary hint string of the window.
 247    *
 248    * @param[in] index The index of the supported auxiliary hint lists
 249    * @return The auxiliary hint string of the index.
 250    *
 251    * @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.
 252    * If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
 253    */
 254   std::string GetSupportedAuxiliaryHint( unsigned int index ) const;
 255
 256   /**
 257    * @brief Creates an auxiliary hint of the window.
 258    *
 259    * @param[in] hint The auxiliary hint string.
 260    * @param[in] value The value string.
 261    * @return The ID of created auxiliary hint, or @c 0 on failure.
 262    */
 263   unsigned int AddAuxiliaryHint( const std::string& hint, const std::string& value );
 264
 265   /**
 266    * @brief Removes an auxiliary hint of the window.
 267    *
 268    * @param[in] id The ID of the auxiliary hint.
 269    * @return True if no error occurred, false otherwise.
 270    */
 271   bool RemoveAuxiliaryHint( unsigned int id );
 272
 273   /**
 274    * @brief Changes a value of the auxiliary hint.
 275    *
 276    * @param[in] id The auxiliary hint ID.
 277    * @param[in] value The value string to be set.
 278    * @return True if no error occurred, false otherwise.
 279    */
 280   bool SetAuxiliaryHintValue( unsigned int id, const std::string& value );
 281
 282   /**
 283    * @brief Gets a value of the auxiliary hint.
 284    *
 285    * @param[in] id The auxiliary hint ID.
 286    * @return The string value of the auxiliary hint ID, or an empty string if none exists.
 287    */
 288   std::string GetAuxiliaryHintValue( unsigned int id ) const;
 289
 290   /**
 291    * @brief Gets a ID of the auxiliary hint string.
 292    *
 293    * @param[in] hint The auxiliary hint string.
 294    * @return The ID of the auxiliary hint string, or @c 0 if none exists.
 295    */
 296   unsigned int GetAuxiliaryHintId( const std::string& hint ) const;
 297
 298   /**
 299    * @brief Sets a region to accept input events.
 300    *
 301    * @param[in] inputRegion The region to accept input events.
 302    */
 303   void SetInputRegion( const Rect< int >& inputRegion );
 304
 305   /**
 306    * @brief Sets a transparent window's visual state to opaque.
 307    * @details If a visual state of a transparent window is opaque,
 308    * then the window manager could handle it as an opaque window when calculating visibility.
 309    *
 310    * @param[in] opaque Whether the window's visual state is opaque.
 311    * @remarks This will have no effect on an opaque window.
 312    * It doesn't change transparent window to opaque window but lets the window manager know the visual state of the window.
 313    */
 314   void SetOpaqueState( bool opaque );
 315
 316   /**
 317    * @brief Returns whether a transparent window's visual state is opaque or not.
 318    *
 319    * @return True if the window's visual state is opaque, false otherwise.
 320    * @remarks The return value has no meaning on an opaque window.
 321    */
 322   bool IsOpaqueState() const;
 323
 324   /**
 325    * @brief Gets current rotation angle of the window.
 326    *
 327    * @return The current GlWindow rotation angle if previously set, or none
 328    */
 329    Dali::GlWindow::GlWindowOrientation GetCurrentOrientation() const;
 330
 331    /**
 332     * @brief Sets available orientations of the window.
 333     *
 334     * This API is for setting several orientations one time.
 335     *
 336     * @param[in] orientations The available orientations list to add
 337     */
 338    void SetAvailableOrientations( const Dali::Vector<Dali::GlWindow::GlWindowOrientation>& orientations );
 339
 340   /**
 341    * @brief Sets a preferred orientation.
 342    *
 343    * @param[in] orientation The preferred orientation
 344    * @pre angle is in the list of available orientation.
 345    *
 346    * @note To unset the preferred orientation, angle should be set NO_ORIENTATION_PREFERENCE.
 347    */
 348   void SetPreferredOrientation( Dali::GlWindow::GlWindowOrientation orientation );
 349
 350   /**
 351    * @brief Registers a GL callback function for application.
 352    *
 353    * @param[in] glInit  the callback function for application initialize
 354    * @param[in] glRenderFrame the callback function to render to the frame.
 355    * @param[in] glTerminate the callback function to clean-up application GL resource.
 356    *
 357    */
 358   void RegisterGlCallback( GlInitialize glInit, GlRenderFrame glRenderFrame, GlTerminate glTerminate );
 359
 360   /**
 361    * @brief Renders once more even if GL render functions are not added to idler.
 362    * @note Will not work if the window is hidden or GL render functions are added to idler
 363    *
 364    */
 365   void RenderOnce();
 366
 367 public: // Signals
 368
 369   /**
 370    * @brief The user should connect to this signal to get a timing when GlWindow gains focus or loses focus.
 371    *
 372    * A callback of the following type may be connected:
 373    * @code
 374    *   void YourCallbackName( GlWindow GlWindow, bool focusIn );
 375    * @endcode
 376    * The parameter is true if GlWindow gains focus, otherwise false.
 377    * and GlWindow means this signal was called from what GlWindow
 378    *
 379    * @return The signal to connect to
 380    */
 381   FocusChangeSignalType& FocusChangeSignal();
 382
 383   /**
 384    * @brief This signal is emitted when the GlWindow is resized.
 385    *
 386    * A callback of the following type may be connected:
 387    * @code
 388    *   void YourCallbackName( GlWindow GlWindow, int width, int height );
 389    * @endcode
 390    * The parameters are the resized width and height.
 391    * and GlWindow means this signal was called from what GlWindow
 392    *
 393    * @return The signal to connect to
 394    */
 395   ResizeSignalType& ResizeSignal();
 396
 397   /**
 398    * @brief This signal is emitted when key event is received.
 399    *
 400    * A callback of the following type may be connected:
 401    * @code
 402    *   void YourCallbackName(const KeyEvent& event);
 403    * @endcode
 404    *
 405    * @return The signal to connect to
 406    */
 407   KeyEventSignalType& KeyEventSignal();
 408
 409   /**
 410    * @brief This signal is emitted when the screen is touched and when the touch ends
 411    * (i.e. the down & up touch events only).
 412    *
 413    * If there are multiple touch points, then this will be emitted when the first touch occurs and
 414    * then when the last finger is lifted.
 415    * An interrupted event will also be emitted (if it occurs).
 416    * A callback of the following type may be connected:
 417    * @code
 418    *   void YourCallbackName(const TouchEvent& event);
 419    * @endcode
 420    *
 421    * @return The touch signal to connect to
 422    *
 423    * @note Motion events are not emitted.
 424    */
 425   TouchEventSignalType& TouchedSignal();
 426
 427   /**
 428    * @brief This signal is emitted when the window is shown or hidden.
 429    *
 430    * A callback of the following type may be connected:
 431    * @code
 432    *   void YourCallbackName( Window window, bool visible );
 433    * @endcode
 434    *
 435    * @return The signal to connect to
 436    */
 437   VisibilityChangedSignalType& VisibilityChangedSignal();
 438
 439 public: // Not intended for application developers
 440   /// @cond internal
 441   /**
 442    * @brief This constructor is used by Dali::Application::GetGlWindow().
 443    * @param[in] GlWindow A pointer to the GlWindow
 444    */
 445   explicit DALI_INTERNAL GlWindow( Internal::Adaptor::GlWindow* GlWindow );
 446   /// @endcond
 447 };
 448
 449 /**
 450  * @}
 451  */
 452 } // namespace Dali
 453
 454 #endif // DALI_GL_WINDOW_H