dali/public-api/signals/render-callback.h

   1 #ifndef DALI_RENDER_CALLBACK_H
   2 #define DALI_RENDER_CALLBACK_H
   3
   4 /*
   5  * Copyright (c) 2024 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // INTERNAL INCLUDES
  22 #include <dali/public-api/math/matrix.h>
  23 #include <dali/public-api/math/rect.h>
  24 #include <dali/public-api/math/vector2.h>
  25 #include <dali/public-api/rendering/texture.h>
  26 #include <dali/public-api/signals/callback.h>
  27
  28 // EXTERNAL INCLUDES
  29 #include <any>
  30 #include <memory>
  31 #include <utility>
  32 #include <vector>
  33
  34 namespace Dali
  35 {
  36 /**
  37  * @class RenderCallbackInput
  38  *
  39  * This structure contains data to be passed into the RenderCallback
  40  * functor.
  41  *
  42  * @SINCE_2_1.30
  43  */
  44 struct DALI_CORE_API RenderCallbackInput
  45 {
  46   Matrix                mvp;
  47   Matrix                projection;
  48   Size                  size;
  49   Rect<int32_t>         clippingBox;
  50   std::vector<uint32_t> textureBindings;
  51
  52   std::any eglContext;       ///< Storage for EGL Context
  53   bool     usingOwnEglContext; ///< Uses own EGL context (owns GL state), custom code should be aware of it
  54
  55   Matrix view; // Added at end to avoid abi break.
  56 };
  57
  58 /**
  59  * @class RenderCallback
  60  *
  61  * RenderCallback is used by the direct rendering feature and allows injecting
  62  * custom render code (using native API such as GL directly) into the DALi
  63  * rendering stream. The RenderCallback will be executed within own context (unless
  64  * native API is context-less) to maintain state separation from DALi render state.
  65  *
  66  * The class wraps CallbackBase object ensuring its type-safe assignment
  67  *
  68  * @SINCE_2_1.14
  69  */
  70 class DALI_CORE_API RenderCallback
  71 {
  72 public:
  73
  74   /**
  75    * @brief Mode of execution of custom rendering code into the pipeline
  76    *
  77    * ISOLATED mode will try to isolate custom rendering so it will start with
  78    * clean state of graphics API and won't affect DALi rendering pipeline. This
  79    * mode is considered as safe.
  80    *
  81    * UNSAFE mode will inject custom rendering code into DALi rendering
  82    * pipeline as is and won't isolate graphics native API state. This mode
  83    * should be used with caution and is considered unsafe.
  84    *
  85    * The default mode is ISOLATED.
  86    *
  87    * @SINCE_2_3.12
  88    */
  89   enum class ExecutionMode
  90   {
  91     /**
  92      * @brief Native rendering commands will be isolated from DALi graphics pipline state
  93      * @details This mode is default and provides safest way of executing custom graphics API commands.
  94      * @SINCE_2_3.12
  95      */
  96     ISOLATED,
  97
  98     /**
  99      * @brief Native rendering will be injected directly into DALi graphics pipeline
 100      * @details This mode is considered unsafe as it's directly injected into DALi rendering pipeline.
 101      * It inherits current graphics API state and may alter it.
 102      * @SINCE_2_3.12
 103      */
 104     UNSAFE,
 105
 106     /**
 107      * @brief Default mode is ISOLATED
 108      * @SINCE_2_3.12
 109      */
 110     DEFAULT = ISOLATED
 111   };
 112
 113   /**
 114    * Templated member function type
 115    */
 116   template<class T>
 117   using FuncType = bool (T::*)(const RenderCallbackInput&);
 118
 119   /**
 120    * @brief Constructor of RenderCallback
 121    *
 122    * @param[in] object Object to invoke
 123    * @param[in] func Member function to invoke
 124    * @param[in] executionMode execution mode of custom code
 125    *
 126    * @SINCE_2_3.12
 127    */
 128   template<class T>
 129   RenderCallback(T* object, FuncType<T> func, ExecutionMode executionMode)
 130   : mCallback(MakeCallback(object, func)),
 131     mExecutionMode(executionMode)
 132   {
 133   }
 134
 135   /**
 136    * @brief Creates new instance of RenderCallback
 137    *
 138    * @SINCE_2_1.14
 139    * @param[in] object Object to invoke
 140    * @param[in] func Member function to invoke
 141    * @return Unique pointer to the RenderCallback instance
 142    */
 143   template<class T>
 144   static std::unique_ptr<RenderCallback> New(T* object, FuncType<T> func)
 145   {
 146     return std::make_unique<RenderCallback>(object, func, ExecutionMode::DEFAULT);
 147   }
 148
 149   /**
 150    * @brief Creates new instance of RenderCallback
 151    *
 152    * @SINCE_2_3.12
 153    * @param[in] object Object to invoke
 154    * @param[in] func Member function to invoke
 155    * @param[in] executionMode Execution mode of custom code
 156    * @return Unique pointer to the RenderCallback instance
 157    */
 158   template<class T>
 159   static std::unique_ptr<RenderCallback> New(T* object, FuncType<T> func, ExecutionMode executionMode)
 160   {
 161     return std::make_unique<RenderCallback>(object, func, executionMode);
 162   }
 163
 164   /**
 165    * @brief Explicit cast operator
 166    *
 167    * @SINCE_2_1.14
 168    * @return casts RenderCallback to CallbackBase object
 169    */
 170   explicit operator CallbackBase*()
 171   {
 172     return mCallback.get();
 173   }
 174
 175   /**
 176    * @brief Binds DALi textures to the callback
 177    *
 178    * The textures that are bound to the callback will be passed upon
 179    * callback execution providing native handles (like GL name) so they
 180    * can be used alongside with custom GL code.
 181    *
 182    * Binding texture does not affect lifecycle and it's up to the client-side
 183    * to make sure the resource is alive when used inside the callback.
 184    *
 185    * @param[in] textures List of DALi textures to be bound to the callback
 186    * @SINCE_2_1.30
 187    */
 188   void BindTextureResources(std::vector<Dali::Texture> textures)
 189   {
 190     mTextureResources = std::move(textures);
 191   }
 192
 193   /**
 194    * @brief Returns list of DALi textures bound to the callback
 195    *
 196    * @return list of textures
 197    */
 198   [[nodiscard]] const std::vector<Dali::Texture>& GetTextureResources() const
 199   {
 200     return mTextureResources;
 201   }
 202   /**
 203    * @brief Explicit cast operator
 204    *
 205    * @SINCE_2_1.14
 206    * @return casts RenderCallback to CallbackBase object
 207    */
 208   explicit operator CallbackBase&()
 209   {
 210     return *mCallback;
 211   }
 212
 213   /**
 214    * @brief Returns input data passed to the callback upon execution
 215    *
 216    * The input data will be filled by the DALi and Graphics backend
 217    * providing DALi rendering related data (such as clipping box) as well as
 218    * Graphics native API related data (like EGLContext for GL).
 219    *
 220    * @SINCE_2_1.30
 221    * @return Valid RenderCallbackInput structure
 222    */
 223   RenderCallbackInput& GetRenderCallbackInput()
 224   {
 225     return mRenderCallbackInput;
 226   }
 227
 228   /**
 229    * @brief Returns execution mode of the callback
 230    *
 231    * @SINCE_2_3.12
 232    * @return Valid execution mode
 233    */
 234    [[nodiscard]] ExecutionMode GetExecutionMode() const
 235    {
 236      return mExecutionMode;
 237    }
 238
 239 private:
 240   std::unique_ptr<CallbackBase> mCallback; //< Callback base object
 241   RenderCallbackInput           mRenderCallbackInput;
 242   ExecutionMode                 mExecutionMode{ExecutionMode::DEFAULT};
 243   std::vector<Dali::Texture> mTextureResources{};
 244 };
 245 } // namespace Dali
 246
 247 #endif // DALI_RENDER_CALLBACK_H