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