dali/internal/update/common/property-owner.h

   1 #ifndef DALI_INTERNAL_SCENE_GRAPH_PROPERTY_OWNER_H
   2 #define DALI_INTERNAL_SCENE_GRAPH_PROPERTY_OWNER_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/devel-api/common/owner-container.h>
  23 #include <dali/integration-api/ordered-set.h>
  24 #include <dali/internal/common/const-string.h>
  25 #include <dali/internal/common/message.h>
  26 #include <dali/internal/update/animation/scene-graph-constraint-declarations.h>
  27 #include <dali/internal/update/common/property-base.h>
  28 #include <dali/internal/update/common/scene-graph-buffers.h>
  29 #include <dali/internal/update/common/uniform-map.h>
  30 #include <dali/public-api/common/dali-vector.h>
  31
  32 namespace Dali
  33 {
  34 namespace Internal
  35 {
  36 namespace SceneGraph
  37 {
  38 class PropertyOwner;
  39 class ResetterManager;
  40
  41 using OwnedPropertyContainer = OwnerContainer<PropertyBase*>;
  42 using OwnedPropertyIter      = OwnedPropertyContainer::Iterator;
  43
  44 /**
  45  * An update-thread object which own properties.
  46  * This allows observers to track the lifetime of the object & its properties.
  47  */
  48 class PropertyOwner
  49 {
  50 public:
  51   class Observer
  52   {
  53   public:
  54     enum NotifyReturnType
  55     {
  56       STOP_OBSERVING,
  57       KEEP_OBSERVING,
  58     };
  59
  60   public:
  61     /**
  62      * Called when the observable object is connected to the scene graph.
  63      * @param[in] owner A reference to the connected PropertyOwner
  64      */
  65     virtual void PropertyOwnerConnected(PropertyOwner& owner) = 0;
  66
  67     /**
  68      * Called when the observable object is disconnected from the scene graph.
  69      * @param[in] currentBufferIndex The buffer to reset.
  70      * @param[in] owner A reference to the disconnected PropertyOwner
  71      * @return NotifyReturnType::STOP_OBSERVING if we will not observe this object after this called
  72      *         NotifyReturnType::KEEP_OBSERVING if we will observe this object after this called.
  73      */
  74     virtual NotifyReturnType PropertyOwnerDisconnected(BufferIndex updateBufferIndex, PropertyOwner& owner) = 0;
  75
  76     /**
  77      * Called shortly before the observable object is destroyed.
  78      *
  79      * @note Cleanup should be done in both this and PropertyOwnerDisconnected as PropertyOwnerDisconnected
  80      * may not be called (i.e. when shutting down).
  81      */
  82     virtual void PropertyOwnerDestroyed(PropertyOwner& owner) = 0;
  83
  84   protected:
  85     /**
  86      * Virtual destructor, no deletion through this interface
  87      */
  88     virtual ~Observer() = default;
  89   };
  90
  91   /**
  92    * Create a property owner.
  93    * @return A newly allocated object.
  94    */
  95   static PropertyOwner* New();
  96
  97   /**
  98    * Virtual destructor; this is intended as a base class.
  99    */
 100   virtual ~PropertyOwner();
 101
 102   /**
 103    * Add an observer.
 104    * The observer is responsible for calling RemoveObserver(*this) during its own destruction.
 105    * Connecting an actor-side object as an observer is not allowed, due to thread-safety issues.
 106    * @param[in] observer The observer.
 107    */
 108   void AddObserver(Observer& observer);
 109
 110   /**
 111    * Remove an observer.
 112    * @param[in] observer The observer.
 113    */
 114   void RemoveObserver(Observer& observer);
 115
 116   /**
 117    * This method can be used to determine if there is an animation or
 118    * constraint that is using this property owner.
 119    * @return true if there are observers.
 120    */
 121   bool IsObserved();
 122
 123   /**
 124    * Called just before destruction to disconnect all observers and remove constraints.
 125    * This occurs when the object is in the process of being destroyed.
 126    */
 127   void Destroy();
 128
 129   /**
 130    * Notify all observers that the object has been connected
 131    * This occurs when the object is connected to the scene-graph during UpdateManager::Update().
 132    */
 133   void ConnectToSceneGraph();
 134
 135   /**
 136    * Notify all observers that the object has been disconnected and remove constraints.
 137    * This occurs when the object is disconnected from the scene-graph during UpdateManager::Update().
 138    * @param[in] currentBufferIndex The current update buffer.
 139    */
 140   void DisconnectFromSceneGraph(BufferIndex updateBufferIndex);
 141
 142   /**
 143    * Reserve the given number of properties
 144    */
 145   void ReserveProperties(int propertyCount);
 146
 147   /**
 148    * Install a custom property.
 149    * @post The PropertyOwner takes ownership of the property.
 150    * @param[in] property A pointer to a newly allocated property.
 151    */
 152   void InstallCustomProperty(OwnerPointer<PropertyBase>& property);
 153
 154   /**
 155    * Retrieve the custom properties owned by the object.
 156    * @return A container of properties.
 157    */
 158   OwnedPropertyContainer& GetCustomProperties()
 159   {
 160     return mCustomProperties;
 161   }
 162
 163   /**
 164    * Retrieve the custom properties owned by the object.
 165    * @return A container of properties.
 166    */
 167   const OwnedPropertyContainer& GetCustomProperties() const
 168   {
 169     return mCustomProperties;
 170   }
 171
 172   /**
 173    * Mark an property owner with the updated flag.
 174    * @param[in] updated The updated flag
 175    */
 176   void SetUpdated(bool updated)
 177   {
 178     mUpdated = updated;
 179   }
 180
 181   /**
 182    * Retrieve if the property owner is updated due to the property is being animating.
 183    * @return An updated flag
 184    */
 185   bool Updated() const
 186   {
 187     return mUpdated;
 188   }
 189
 190   // Constraints
 191
 192   /**
 193    * Apply a constraint.
 194    * @param[in] constraint The constraint to apply.
 195    */
 196   void ApplyConstraint(OwnerPointer<ConstraintBase>& constraint);
 197
 198   /**
 199    * Begin removal of constraints.
 200    * @param[in] constraint The constraint to remove.
 201    */
 202   void RemoveConstraint(ConstraintBase* constraint);
 203
 204   /**
 205    * Apply a post constraint.
 206    * @param[in] constraint The constraint to apply.
 207    */
 208   void ApplyPostConstraint(OwnerPointer<ConstraintBase>& constraint);
 209
 210   /**
 211    * Begin removal of post constraints.
 212    * @param[in] constraint The constraint to remove.
 213    */
 214   void RemovePostConstraint(ConstraintBase* constraint);
 215
 216   /**
 217    * Retrieve the constraints that are currently applied.
 218    * @return A container of constraints.
 219    */
 220   ConstraintOwnerContainer& GetConstraints();
 221
 222   /**
 223    * Retrieve the post constraints that are currently applied.
 224    * @return A container of post constraints.
 225    */
 226   ConstraintOwnerContainer& GetPostConstraints();
 227
 228   /**
 229    * @copydoc UniformMap::Add
 230    */
 231   virtual void AddUniformMapping(const UniformPropertyMapping& map);
 232
 233   /**
 234    * @copydoc UniformMap::Remove
 235    */
 236   virtual void RemoveUniformMapping(const ConstString& uniformName);
 237
 238   /**
 239    * Get the mappings table
 240    */
 241   const UniformMap& GetUniformMap() const;
 242
 243   /**
 244    * Query whether playing an animation is possible or not.
 245    * @return true if playing an animation is possible.
 246    */
 247   virtual bool IsAnimationPossible() const
 248   {
 249     return true;
 250   }
 251
 252   /**
 253    * @brief Install custom resetter messages to resetter manager.
 254    * @pre ConnectToSceneGraph() Should be called before this API.
 255    *
 256    * @param[in] manager ResetterManager to add resetter.
 257    */
 258   virtual void AddInitializeResetter(ResetterManager& manager) const
 259   {
 260     // Do nothing
 261   }
 262
 263 protected:
 264   /**
 265    * Protected constructor.
 266    */
 267   PropertyOwner();
 268
 269   /**
 270    * Method to inform derived classes when property maps have been modified.
 271    */
 272   virtual void OnMappingChanged()
 273   {
 274     // Default behaviour is to do nothing
 275   }
 276
 277 private:
 278   // Undefined
 279   PropertyOwner(const PropertyOwner&);
 280
 281   // Undefined
 282   PropertyOwner& operator=(const PropertyOwner& rhs);
 283
 284 protected:
 285   OwnedPropertyContainer mCustomProperties; ///< Properties provided with InstallCustomProperty()
 286   UniformMap             mUniformMaps;      ///< Container of owned uniform maps
 287   bool                   mUpdated;
 288   bool                   mIsConnectedToSceneGraph;
 289
 290 private:
 291   using ObserverContainer = Integration::OrderedSet<PropertyOwner::Observer, false>;
 292   using ObserverIter      = ObserverContainer::Iterator;
 293   using ConstObserverIter = ObserverContainer::ConstIterator;
 294
 295   ObserverContainer mObservers; ///< Container of observer raw-pointers (not owned)
 296
 297   ConstraintOwnerContainer mConstraints;     ///< Container of owned constraints
 298   ConstraintOwnerContainer mPostConstraints; ///< Container of owned constraints
 299
 300   bool mObserverNotifying : 1; ///< Whether we are currently notifying observers.
 301 };
 302
 303 } // namespace SceneGraph
 304
 305 } // namespace Internal
 306
 307 } // namespace Dali
 308
 309 #endif // DALI_INTERNAL_SCENE_GRAPH_PROPERTY_OWNER_H