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