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