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      * * @SINCE_2_1.18
  59      */
  60     DIRECT_RENDERING = 0,
  61
  62     /**
  63      * DIRECT_RENDERING_THREADED mode executes GL code on separate thread
  64      * and then blits the result within DALi graphics commands stream.
  65      * The mode is logically compatible with the EGL_IMAGE_OFFSCREEN_RENDERING.
  66      *
  67      * @SINCE_2_1.30
  68      */
  69     DIRECT_RENDERING_THREADED,
  70
  71     /**
  72      * EGL_IMAGE_OFFSCREEN_RENDERING mode executes GL code in own thread
  73      * and renders to the offscreen NativeImage (EGL) buffer. This backend
  74      * will render in parallel but has higher memory footprint and may suffer
  75      * performance issues due to using EGL image.
  76      *
  77      * @SINCE_2_1.18
  78      */
  79     EGL_IMAGE_OFFSCREEN_RENDERING,
  80
  81     /**
  82      * The default mode is set to EGL_IMAGE_OFFSCREEN_RENDERING for backwards
  83      * compatibility.
  84      *
  85      * @SINCE_2_1.18
  86      */
  87     DEFAULT = EGL_IMAGE_OFFSCREEN_RENDERING
  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    * @SINCE_2_0.45
  99    */
 100   enum class RenderingMode
 101   {
 102     CONTINUOUS, ///< continuous mode
 103     ON_DEMAND   ///< on demand by application
 104   };
 105
 106   /**
 107    * @brief Enumeration for Graphics API version
 108    *
 109    * This Enumeration is used to set a GLES version for EGL configuration.
 110    *
 111    * @SINCE_2_0.45
 112    */
 113   enum class GraphicsApiVersion
 114   {
 115     GLES_VERSION_2_0 = 0, ///< GLES version 2.0
 116     GLES_VERSION_3_0,     ///< GLES version 3.0
 117   };
 118
 119   /**
 120    * @brief Enumeration for color buffer format
 121    *
 122    * This Enumeration is used to set a color buffer format of GlView
 123    *
 124    * @SINCE_2_0.45
 125    */
 126   enum class ColorFormat
 127   {
 128     RGB888,  ///< 8 red bits, 8 green bits, 8 blue bits
 129     RGBA8888 ///< 8 red bits, 8 green bits, 8 blue bits, alpha 8 bits
 130   };
 131
 132   /**
 133    * @brief Creates a GlView control.
 134    *
 135    * @note This function always creates the GlView with NativeImage backend.
 136    *
 137    * @param[in] colorFormat the format of the color buffer.
 138    * @return A handle to a GlView control
 139    *
 140    * @SINCE_2_0.45
 141    */
 142   static GlView New(ColorFormat colorFormat);
 143
 144   /**
 145    * @brief Creates a GlView control.
 146    *
 147    * The new GlView will be created with specified backend.
 148    * The colorFormat is ignored for DIRECT_RENDERING backend.
 149    *
 150    * @param[in] colorFormat the format of the color buffer.
 151    * @param[in] backendMode the backend used by the GlView
 152    * @return A handle to a GlView control
 153    *
 154    * @SINCE_2_1.18
 155    */
 156   static GlView New(BackendMode backendMode, ColorFormat colorFormat);
 157
 158   /**
 159    * @brief Creates an uninitialized GlView.
 160    *
 161    * @SINCE_2_0.45
 162    */
 163   GlView();
 164
 165   /**
 166    * @brief Destructor.
 167    *
 168    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 169    *
 170    * @SINCE_2_0.45
 171    */
 172   ~GlView();
 173
 174   /**
 175    * @brief Copy constructor.
 176    *
 177    * @param[in] GlView GlView to copy. The copied GlView will point at the same implementation
 178    *
 179    * @SINCE_2_0.45
 180    */
 181   GlView(const GlView& GlView);
 182
 183   /**
 184    * @brief Move constructor
 185    *
 186    * @param[in] rhs A reference to the moved handle
 187    *
 188    * @SINCE_2_0.45
 189    */
 190   GlView(GlView&& rhs);
 191
 192   /**
 193    * @brief Assignment operator.
 194    *
 195    * @param[in] GlView The GlView to assign from
 196    * @return A reference to this
 197    *
 198    * @SINCE_2_0.45
 199    */
 200   GlView& operator=(const GlView& GlView);
 201
 202   /**
 203    * @brief Move assignment
 204    *
 205    * @param[in] rhs A reference to the moved handle
 206    * @return A reference to this
 207    *
 208    * @SINCE_2_0.45
 209    */
 210   GlView& operator=(GlView&& rhs);
 211
 212   /**
 213    * @brief Downcasts a handle to GlView handle.
 214    *
 215    * If handle points to a GlView, the downcast produces valid handle.
 216    * If not, the returned handle is left uninitialized.
 217    *
 218    * @param[in] handle Handle to an object
 219    * @return Handle to a GlView or an uninitialized handle
 220    *
 221    * @SINCE_2_0.45
 222    */
 223   static GlView DownCast(BaseHandle handle);
 224
 225   /**
 226    * @brief Registers GL callback functions for GlView.
 227    *
 228    * @param[in] initCallback  the callback function to create GL resources.
 229    * @param[in] renderFrameCallback the callback function to render for the frame.
 230    * @param[in] terminateCallback the callback function to clean-up GL resources.
 231    *
 232    * A initCallback of the following type have to be used:
 233    * @code
 234    *   void intializeGL();
 235    * @endcode
 236    * This callback will be called before renderFrame callback is called once.
 237    *
 238    * A renderFrameCallback of the following type have to be used:
 239    * @code
 240    *   int renderFrameGL();
 241    * @endcode
 242    * If the return value of this callback is not 0, the eglSwapBuffers() will be called.
 243    *
 244    * A terminateCallback of the following type have to be used:
 245    * @code
 246    *   void terminateGL();
 247    * @endcode
 248    * This callback is called when GlView is deleted.
 249    *
 250    * @note Ownership of the callbacks is passed onto this class.
 251    * <b>You can't call Dali APIs in your callbacks because it is invoked in GlView's own render thread.</b>
 252    * And this must be called before adding GlView to the scene.
 253    *
 254    * @SINCE_2_0.45
 255    */
 256   void RegisterGlCallbacks(CallbackBase* initCallback, CallbackBase* renderFrameCallback, CallbackBase* terminateCallback);
 257
 258   /**
 259    * @brief Sets the ResizeCallback of the GlView.
 260    * When GlView is resized, ResizeCallback would be invoked.
 261    * You can get the resized width and height of the GlView.
 262    *
 263    * @param[in] resizeCallback The ResizeCallback function
 264    *
 265    * A resizeCallback of the following type have to be used:
 266    * @code
 267    *   void resizeCallback(int width, int height);
 268    * @endcode
 269    *
 270    * @note Ownership of the callback is passed onto this class.
 271    * <b>You can't call Dali APIs in your callback because it is invoked in GlView's own render thread.</b>
 272    * And this must be called before adding GlView to the scene.
 273    *
 274    * @SINCE_2_0.45
 275    */
 276   void SetResizeCallback(CallbackBase* resizeCallback);
 277
 278   /**
 279    * @brief Sets the rendering mode.
 280    *
 281    * @param[in] mode the rendering mode for GlView
 282    *
 283    * @note The default Rendering mode is CONTINUOUS.
 284    * If ON_DEMAND mode is set, it is rendered by RenderOnce()
 285    *
 286    * @SINCE_2_0.45
 287    */
 288   void SetRenderingMode(RenderingMode mode);
 289
 290   /**
 291    * @brief Gets the rendering mode.
 292    *
 293    * @SINCE_2_0.45
 294    */
 295   [[nodiscard]] RenderingMode GetRenderingMode() const;
 296
 297   /**
 298    * @brief Gets the backend mode.
 299    *
 300    * @SINCE_2_1.18
 301    */
 302   [[nodiscard]] BackendMode GetBackendMode() const;
 303
 304   /**
 305    * @brief Sets egl configuration for GlView
 306    *
 307    * @param[in] depth the flag of depth buffer. If the value is true, 24bit depth buffer is enabled.
 308    * @param[in] stencil the flag of stencil. If the value is true, 8bit stencil buffer is enabled.
 309    * @param[in] msaa the expected sampling number per pixel.
 310    * @param[in] version the graphics API version
 311    * @return True if the config exists, false otherwise.
 312    *
 313    * @SINCE_2_0.45
 314    */
 315   bool SetGraphicsConfig(bool depth, bool stencil, int msaa, GraphicsApiVersion version);
 316
 317   /**
 318    * @brief Renders once more even if GL render functions are not added to idler.
 319    * @note Will not work if the window is hidden or GL render functions are added to idler
 320    *
 321    * @SINCE_2_0.45
 322    */
 323   void RenderOnce();
 324
 325 public: // Not intended for application developers
 326   /// @cond internal
 327   /**
 328    * @brief Creates a handle using the Toolkit::Internal implementation.
 329    * @param[in] implementation The GlView implementation
 330    *
 331    * @SINCE_2_0.45
 332    */
 333   DALI_INTERNAL GlView(Internal::GlViewImpl& implementation);
 334
 335   /**
 336    * @brief Allows the creation of this GlView from an Internal::CustomActor pointer.
 337    * @param[in] internal A pointer to the internal CustomActor
 338    *
 339    * @SINCE_2_0.45
 340    */
 341   DALI_INTERNAL GlView(Dali::Internal::CustomActor* internal);
 342   /// @endcond
 343 };
 344
 345 } // namespace Toolkit
 346
 347 } // namespace Dali
 348
 349 #endif // DALI_TOOLKIT_GL_VIEW_H