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