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 GlView;
  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  */
  40 class DALI_TOOLKIT_API GlView : public Dali::Toolkit::Control
  41 {
  42 public:
  43   /**
  44    * @brief Enumeration for rendering mode
  45    *
  46    * This Enumeration is used to choose the rendering mode.
  47    * It has two options.
  48    * One of them is continuous mode. It is rendered continuously.
  49    * The other is on demand mode. It is rendered by application.
  50    */
  51   enum class RenderingMode
  52   {
  53     CONTINUOUS, ///< continuous mode
  54     ON_DEMAND   ///< on demand by application
  55   };
  56
  57   /**
  58    * @brief Enumeration for Graphics API version
  59    *
  60    * This Enumeration is used to set a GLES version for EGL configuration.
  61    */
  62   enum class GraphicsApiVersion
  63   {
  64     GLES_VERSION_2_0 = 0, ///< GLES version 2.0
  65     GLES_VERSION_3_0,     ///< GLES version 3.0
  66   };
  67
  68   /**
  69    * @brief Enumeration for color buffer format
  70    *
  71    * This Enumeration is used to set a color buffer format of GlView
  72    */
  73   enum class ColorFormat
  74   {
  75     RGB888,  ///< 8 red bits, 8 green bits, 8 blue bits
  76     RGBA8888 ///< 8 red bits, 8 green bits, 8 blue bits, alpha 8 bits
  77   };
  78
  79   /**
  80    * @brief Creates a GlView control.
  81    * @param[in] colorFormat the format of the color buffer.
  82    * @return A handle to a GlView control
  83    */
  84   static GlView New(ColorFormat colorFormat);
  85
  86   /**
  87    * @brief Creates an uninitialized GlView.
  88    */
  89   GlView();
  90
  91   /**
  92    * @brief Destructor.
  93    *
  94    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  95    */
  96   ~GlView();
  97
  98   /**
  99    * @brief Copy constructor.
 100    *
 101    * @param[in] GlView GlView to copy. The copied GlView will point at the same implementation
 102    */
 103   GlView(const GlView& GlView);
 104
 105   /**
 106    * @brief Move constructor
 107    *
 108    * @param[in] rhs A reference to the moved handle
 109    */
 110   GlView(GlView&& rhs);
 111
 112   /**
 113    * @brief Assignment operator.
 114    *
 115    * @param[in] GlView The GlView to assign from
 116    * @return A reference to this
 117    */
 118   GlView& operator=(const GlView& GlView);
 119
 120   /**
 121    * @brief Move assignment
 122    *
 123    * @param[in] rhs A reference to the moved handle
 124    * @return A reference to this
 125    */
 126   GlView& operator=(GlView&& rhs);
 127
 128   /**
 129    * @brief Downcasts a handle to GlView handle.
 130    *
 131    * If handle points to a GlView, the downcast produces valid handle.
 132    * If not, the returned handle is left uninitialized.
 133    *
 134    * @param[in] handle Handle to an object
 135    * @return Handle to a GlView or an uninitialized handle
 136    */
 137   static GlView DownCast(BaseHandle handle);
 138
 139   /**
 140    * @brief Registers GL callback functions for GlView.
 141    *
 142    * @param[in] initCallback  the callback function to create GL resources.
 143    * @param[in] renderFrameCallback the callback function to render for the frame.
 144    * @param[in] terminateCallback the callback function to clean-up GL resources.
 145    *
 146    * A initCallback of the following type have to be used:
 147    * @code
 148    *   void intializeGL();
 149    * @endcode
 150    * This callback will be called before renderFrame callback is called once.
 151    *
 152    * A renderFrameCallback of the following type have to be used:
 153    * @code
 154    *   int renderFrameGL();
 155    * @endcode
 156    * If the return value of this callback is not 0, the eglSwapBuffers() will be called.
 157    *
 158    * A terminateCallback of the following type have to be used:
 159    * @code
 160    *   void terminateGL();
 161    * @endcode
 162    * This callback is called when GlView is deleted.
 163    *
 164    * @note Ownership of the callbacks is passed onto this class.
 165    * <b>You can't call Dali APIs in your callbacks because it is invoked in GlView's own render thread.</b>
 166    * And this must be called before adding GlView to the scene.
 167    */
 168   void RegisterGlCallbacks(CallbackBase* initCallback, CallbackBase* renderFrameCallback, CallbackBase* terminateCallback);
 169
 170   /**
 171    * @brief Sets the ResizeCallback of the GlView.
 172    * When GlView is resized, ResizeCallback would be invoked.
 173    * You can get the resized width and height of the GlView.
 174    *
 175    * @param[in] resizeCallback The ResizeCallback function
 176    *
 177    * A resizeCallback of the following type have to be used:
 178    * @code
 179    *   void resizeCallback(int width, int height);
 180    * @endcode
 181    *
 182    * @note Ownership of the callback is passed onto this class.
 183    * <b>You can't call Dali APIs in your callback because it is invoked in GlView's own render thread.</b>
 184    * And this must be called before adding GlView to the scene.
 185    */
 186   void SetResizeCallback(CallbackBase* resizeCallback);
 187
 188   /**
 189    * @brief Sets the rendering mode.
 190    *
 191    * @param[in] mode the rendering mode for GlView
 192    *
 193    * @note The default Rendering mode is CONTINUOUS.
 194    * If ON_DEMAND mode is set, it is rendered by RenderOnce()
 195    */
 196   void SetRenderingMode(RenderingMode mode);
 197
 198   /**
 199    * @brief Gets the rendering mode.
 200    */
 201   RenderingMode GetRenderingMode() const;
 202
 203   /**
 204    * @brief Sets egl configuration for GlView
 205    *
 206    * @param[in] depth the flag of depth buffer. If the value is true, 24bit depth buffer is enabled.
 207    * @param[in] stencil the flag of stencil. If the value is true, 8bit stencil buffer is enabled.
 208    * @param[in] msaa the expected sampling number per pixel.
 209    * @param[in] version the graphics API version
 210    * @return True if the config exists, false otherwise.
 211    */
 212   bool SetGraphicsConfig(bool depth, bool stencil, int msaa, GraphicsApiVersion version);
 213
 214   /**
 215    * @brief Renders once more even if GL render functions are not added to idler.
 216    * @note Will not work if the window is hidden or GL render functions are added to idler
 217    */
 218   void RenderOnce();
 219
 220 public: // Not intended for application developers
 221   /// @cond internal
 222   /**
 223    * @brief Creates a handle using the Toolkit::Internal implementation.
 224    * @param[in] implementation The GlView implementation
 225    */
 226   DALI_INTERNAL GlView(Internal::GlView& implementation);
 227
 228   /**
 229    * @brief Allows the creation of this GlView from an Internal::CustomActor pointer.
 230    * @param[in] internal A pointer to the internal CustomActor
 231    */
 232   DALI_INTERNAL GlView(Dali::Internal::CustomActor* internal);
 233   /// @endcond
 234 };
 235
 236 } // namespace Toolkit
 237
 238 } // namespace Dali
 239
 240 #endif // DALI_TOOLKIT_GL_VIEW_H