dali-toolkit/public-api/controls/gl-view/gl-view.h

   1 #ifndef DALI_TOOLKIT_GL_VIEW_H
   2 #define DALI_TOOLKIT_GL_VIEW_H
   3 /*
   4  * Copyright (c) 2021 Samsung Electronics Co., Ltd.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20 // INTERNAL INCLUDES
  21 #include <dali-toolkit/public-api/controls/control.h>
  22
  23 namespace Dali
  24 {
  25 namespace Toolkit
  26 {
  27 namespace Internal DALI_INTERNAL
  28 {
  29 class GlViewImpl;
  30 }
  31
  32 /**
  33  * @brief GlView is a class for rendering with GL
  34  *
  35  * GlView allows drawing with OpenGL.
  36  * GlView creates a GL context, a GL surface and a render thread.
  37  * The render thread invokes user's callbacks.
  38  *
  39  * @SINCE_2_0.45
  40  */
  41 class DALI_TOOLKIT_API GlView : public Dali::Toolkit::Control
  42 {
  43 public:
  44
  45   /**
  46    * @brief Implementation backend mode
  47    *
  48    * @SINCE_2_1.18
  49    */
  50   enum class BackendMode
  51   {
  52     /**
  53      * DIRECT_RENDERING mode executes GL code within DALi graphics
  54      * pipeline. When Renderer is about to be drawn, the callback
  55      * will be executed and the custom code "injected" into the pipeline.
  56      * This allows rendering directly to the surface rather than offscreen.
  57      */
  58     DIRECT_RENDERING = 0,
  59
  60     /**
  61      * EGL_IMAGE_OFFSCREEN_RENDERING mode executes GL code in own thread
  62      * and renders to the offscreen NativeImage (EGL) buffer. This backend
  63      * will render in parallel but has higher memory footprint and may suffer
  64      * performance issues due to using EGL image.
  65      */
  66     EGL_IMAGE_OFFSCREEN_RENDERING,
  67
  68     /**
  69      * The default mode is set to EGL_IMAGE_OFFSCREEN_RENDERING for backwards
  70      * compatibility.
  71      */
  72     DEFAULT = EGL_IMAGE_OFFSCREEN_RENDERING
  73   };
  74
  75   /**
  76    * @brief Enumeration for rendering mode
  77    *
  78    * This Enumeration is used to choose the rendering mode.
  79    * It has two options.
  80    * One of them is continuous mode. It is rendered continuously.
  81    * The other is on demand mode. It is rendered by application.
  82    *
  83    * @SINCE_2_0.45
  84    */
  85   enum class RenderingMode
  86   {
  87     CONTINUOUS, ///< continuous mode
  88     ON_DEMAND   ///< on demand by application
  89   };
  90
  91   /**
  92    * @brief Enumeration for Graphics API version
  93    *
  94    * This Enumeration is used to set a GLES version for EGL configuration.
  95    *
  96    * @SINCE_2_0.45
  97    */
  98   enum class GraphicsApiVersion
  99   {
 100     GLES_VERSION_2_0 = 0, ///< GLES version 2.0
 101     GLES_VERSION_3_0,     ///< GLES version 3.0
 102   };
 103
 104   /**
 105    * @brief Enumeration for color buffer format
 106    *
 107    * This Enumeration is used to set a color buffer format of GlView
 108    *
 109    * @SINCE_2_0.45
 110    */
 111   enum class ColorFormat
 112   {
 113     RGB888,  ///< 8 red bits, 8 green bits, 8 blue bits
 114     RGBA8888 ///< 8 red bits, 8 green bits, 8 blue bits, alpha 8 bits
 115   };
 116
 117   /**
 118    * @brief Creates a GlView control.
 119    *
 120    * @note This function always creates the GlView with NativeImage backend.
 121    *
 122    * @param[in] colorFormat the format of the color buffer.
 123    * @return A handle to a GlView control
 124    *
 125    * @SINCE_2_0.45
 126    */
 127   static GlView New(ColorFormat colorFormat);
 128
 129   /**
 130    * @brief Creates a GlView control.
 131    *
 132    * The new GlView will be created with specified backend.
 133    * The colorFormat is ignored for DIRECT_RENDERING backend.
 134    *
 135    * @param[in] colorFormat the format of the color buffer.
 136    * @param[in] backendMode the backend used by the GlView
 137    * @return A handle to a GlView control
 138    *
 139    * @SINCE_2_1.18
 140    */
 141   static GlView New(BackendMode backendMode, ColorFormat colorFormat);
 142
 143   /**
 144    * @brief Creates an uninitialized GlView.
 145    *
 146    * @SINCE_2_0.45
 147    */
 148   GlView();
 149
 150   /**
 151    * @brief Destructor.
 152    *
 153    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 154    *
 155    * @SINCE_2_0.45
 156    */
 157   ~GlView();
 158
 159   /**
 160    * @brief Copy constructor.
 161    *
 162    * @param[in] GlView GlView to copy. The copied GlView will point at the same implementation
 163    *
 164    * @SINCE_2_0.45
 165    */
 166   GlView(const GlView& GlView);
 167
 168   /**
 169    * @brief Move constructor
 170    *
 171    * @param[in] rhs A reference to the moved handle
 172    *
 173    * @SINCE_2_0.45
 174    */
 175   GlView(GlView&& rhs);
 176
 177   /**
 178    * @brief Assignment operator.
 179    *
 180    * @param[in] GlView The GlView to assign from
 181    * @return A reference to this
 182    *
 183    * @SINCE_2_0.45
 184    */
 185   GlView& operator=(const GlView& GlView);
 186
 187   /**
 188    * @brief Move assignment
 189    *
 190    * @param[in] rhs A reference to the moved handle
 191    * @return A reference to this
 192    *
 193    * @SINCE_2_0.45
 194    */
 195   GlView& operator=(GlView&& rhs);
 196
 197   /**
 198    * @brief Downcasts a handle to GlView handle.
 199    *
 200    * If handle points to a GlView, the downcast produces valid handle.
 201    * If not, the returned handle is left uninitialized.
 202    *
 203    * @param[in] handle Handle to an object
 204    * @return Handle to a GlView or an uninitialized handle
 205    *
 206    * @SINCE_2_0.45
 207    */
 208   static GlView DownCast(BaseHandle handle);
 209
 210   /**
 211    * @brief Registers GL callback functions for GlView.
 212    *
 213    * @param[in] initCallback  the callback function to create GL resources.
 214    * @param[in] renderFrameCallback the callback function to render for the frame.
 215    * @param[in] terminateCallback the callback function to clean-up GL resources.
 216    *
 217    * A initCallback of the following type have to be used:
 218    * @code
 219    *   void intializeGL();
 220    * @endcode
 221    * This callback will be called before renderFrame callback is called once.
 222    *
 223    * A renderFrameCallback of the following type have to be used:
 224    * @code
 225    *   int renderFrameGL();
 226    * @endcode
 227    * If the return value of this callback is not 0, the eglSwapBuffers() will be called.
 228    *
 229    * A terminateCallback of the following type have to be used:
 230    * @code
 231    *   void terminateGL();
 232    * @endcode
 233    * This callback is called when GlView is deleted.
 234    *
 235    * @note Ownership of the callbacks is passed onto this class.
 236    * <b>You can't call Dali APIs in your callbacks because it is invoked in GlView's own render thread.</b>
 237    * And this must be called before adding GlView to the scene.
 238    *
 239    * @SINCE_2_0.45
 240    */
 241   void RegisterGlCallbacks(CallbackBase* initCallback, CallbackBase* renderFrameCallback, CallbackBase* terminateCallback);
 242
 243   /**
 244    * @brief Sets the ResizeCallback of the GlView.
 245    * When GlView is resized, ResizeCallback would be invoked.
 246    * You can get the resized width and height of the GlView.
 247    *
 248    * @param[in] resizeCallback The ResizeCallback function
 249    *
 250    * A resizeCallback of the following type have to be used:
 251    * @code
 252    *   void resizeCallback(int width, int height);
 253    * @endcode
 254    *
 255    * @note Ownership of the callback is passed onto this class.
 256    * <b>You can't call Dali APIs in your callback because it is invoked in GlView's own render thread.</b>
 257    * And this must be called before adding GlView to the scene.
 258    *
 259    * @SINCE_2_0.45
 260    */
 261   void SetResizeCallback(CallbackBase* resizeCallback);
 262
 263   /**
 264    * @brief Sets the rendering mode.
 265    *
 266    * @param[in] mode the rendering mode for GlView
 267    *
 268    * @note The default Rendering mode is CONTINUOUS.
 269    * If ON_DEMAND mode is set, it is rendered by RenderOnce()
 270    *
 271    * @SINCE_2_0.45
 272    */
 273   void SetRenderingMode(RenderingMode mode);
 274
 275   /**
 276    * @brief Gets the rendering mode.
 277    *
 278    * @SINCE_2_0.45
 279    */
 280   [[nodiscard]] RenderingMode GetRenderingMode() const;
 281
 282   /**
 283    * @brief Gets the backend mode.
 284    *
 285    * @SINCE_2_1.18
 286    */
 287   [[nodiscard]] BackendMode GetBackendMode() const;
 288
 289   /**
 290    * @brief Sets egl configuration for GlView
 291    *
 292    * @param[in] depth the flag of depth buffer. If the value is true, 24bit depth buffer is enabled.
 293    * @param[in] stencil the flag of stencil. If the value is true, 8bit stencil buffer is enabled.
 294    * @param[in] msaa the expected sampling number per pixel.
 295    * @param[in] version the graphics API version
 296    * @return True if the config exists, false otherwise.
 297    *
 298    * @SINCE_2_0.45
 299    */
 300   bool SetGraphicsConfig(bool depth, bool stencil, int msaa, GraphicsApiVersion version);
 301
 302   /**
 303    * @brief Renders once more even if GL render functions are not added to idler.
 304    * @note Will not work if the window is hidden or GL render functions are added to idler
 305    *
 306    * @SINCE_2_0.45
 307    */
 308   void RenderOnce();
 309
 310 public: // Not intended for application developers
 311   /// @cond internal
 312   /**
 313    * @brief Creates a handle using the Toolkit::Internal implementation.
 314    * @param[in] implementation The GlView implementation
 315    *
 316    * @SINCE_2_0.45
 317    */
 318   DALI_INTERNAL GlView(Internal::GlViewImpl& implementation);
 319
 320   /**
 321    * @brief Allows the creation of this GlView from an Internal::CustomActor pointer.
 322    * @param[in] internal A pointer to the internal CustomActor
 323    *
 324    * @SINCE_2_0.45
 325    */
 326   DALI_INTERNAL GlView(Dali::Internal::CustomActor* internal);
 327   /// @endcond
 328 };
 329
 330 } // namespace Toolkit
 331
 332 } // namespace Dali
 333
 334 #endif // DALI_TOOLKIT_GL_VIEW_H