dali/public-api/animation/constraint.h

   1 #ifndef DALI_CONSTRAINT_H
   2 #define DALI_CONSTRAINT_H
   3
   4 /*
   5  * Copyright (c) 2020 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 // EXTERNAL INCLUDES
  22 #include <cstdint> // uint32_t
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/animation/constraint-source.h>
  26 #include <dali/public-api/common/dali-vector.h>
  27 #include <dali/public-api/object/base-handle.h>
  28 #include <dali/public-api/object/property.h>
  29 #include <dali/public-api/object/property-input.h>
  30 #include <dali/public-api/signals/callback.h>
  31
  32 namespace Dali
  33 {
  34 /**
  35  * @addtogroup dali_core_animation
  36  * @{
  37  */
  38
  39 class Handle;
  40
  41 namespace Internal DALI_INTERNAL
  42 {
  43 class ConstraintBase;
  44 }
  45
  46 typedef Vector< PropertyInput* > PropertyInputContainer;
  47
  48 /**
  49  * @brief An abstract base class for Constraints.
  50  *
  51  * This can be used to constrain a property of an object, after animations have been applied.
  52  * Constraints are applied in the following order:
  53  *   - Constraints are applied to on-stage actors in a depth-first traversal.
  54  *   - For each actor, the constraints are applied in the same order as the calls to Apply().
  55  *   - Constraints are not applied to off-stage actors.
  56  *
  57  * Create a constraint using one of the New methods depending on the type of callback function used.
  58  * Try to use a C function unless some data needs to be stored, otherwise functors and class methods
  59  * are also supported.
  60  *
  61  * A constraint can be applied to an object in the following manner:
  62  *
  63  * @code
  64  * Handle handle = CreateMyObject();
  65  * Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, &MyFunction );
  66  * constraint.AddSource( LocalSource( INPUT_PROPERTY_INDEX ) );
  67  * constraint.Apply();
  68  * @endcode
  69  * @SINCE_1_0.0
  70  */
  71 class DALI_CORE_API Constraint : public BaseHandle
  72 {
  73 public:
  74
  75   /**
  76    * @brief Template for the Function that is called by the Constraint system.
  77    *
  78    * Supports:
  79    *  - C style functions
  80    *  - Static member methods of an object
  81    *  - Member functions of a particular class
  82    *  - Functors of a particular class
  83    *  - If a functor or method is provided, then a copy of the object is made.
  84    *
  85    * The expected signature of the callback should be:
  86    * @code
  87    *   void Function( P&, const PropertyInputContainer& );
  88    * @endcode
  89    *
  90    * The P& parameter is an in,out parameter which stores the current value of the property. The callback
  91    * should change this value to the desired one. The PropertyInputContainer is a const reference to the property inputs
  92    * added to the Constraint in the order they were added via AddSource().
  93    *
  94    * @SINCE_1_0.0
  95    * @tparam P The property type to constrain
  96    */
  97   template< typename P >
  98   class DALI_INTERNAL Function : public CallbackBase
  99   {
 100   public:
 101
 102     /**
 103      * @brief Constructor which connects to the provided C function (or a static member function).
 104      *
 105      * The expected signature of the function is:
 106      * @code
 107      *   void MyFunction( P&, const PropertyInputContainer& );
 108      * @endcode
 109      *
 110      * @SINCE_1_0.0
 111      * @param[in] function The function to call
 112      */
 113     Function( void( *function )( P&, const PropertyInputContainer& ) )
 114     : CallbackBase( reinterpret_cast< CallbackBase::Function >( function ) ),
 115       mCopyConstructorDispatcher( NULL )
 116     {
 117     }
 118
 119     /**
 120      * @brief Constructor which copies a function object and connects to the functor of that object.
 121      *
 122      * The function object should have a functor with the following signature:
 123      * @code
 124      *   void operator()( P&, const PropertyInputContainer& );
 125      * @endcode
 126      *
 127      * @SINCE_1_0.0
 128      * @param[in] object The object to copy
 129      * @tparam T The type of the object
 130      */
 131     template< class T >
 132     Function( const T& object )
 133     : CallbackBase( reinterpret_cast< void* >( new T( object ) ), // copy the object
 134                     NULL, // uses operator() instead of member function
 135                     reinterpret_cast< CallbackBase::Dispatcher >( &FunctorDispatcher2< T, P&, const PropertyInputContainer& >::Dispatch ),
 136                     reinterpret_cast< CallbackBase::Destructor >( &Destroyer< T >::Delete ) ),
 137       mCopyConstructorDispatcher( reinterpret_cast< CopyConstructorDispatcher >( &ObjectCopyConstructorDispatcher< T >::Copy ) )
 138     {
 139     }
 140
 141     /**
 142      * @brief Constructor which copies a function object and allows a connection to a member method.
 143      *
 144      * The object should have a method with the signature:
 145      * @code
 146      *   void MyObject::MyMethod( P&, const PropertyInputContainer& );
 147      * @endcode
 148      *
 149      * @SINCE_1_0.0
 150      * @param[in] object The object to copy
 151      * @param[in] memberFunction The member function to call. This has to be a member of the same class
 152      * @tparam T The type of the object
 153      */
 154     template< class T >
 155     Function( const T& object, void ( T::*memberFunction ) ( P&, const PropertyInputContainer& ) )
 156     : CallbackBase( reinterpret_cast< void* >( new T( object ) ), // copy the object
 157                     reinterpret_cast< CallbackBase::MemberFunction >( memberFunction ),
 158                     reinterpret_cast< CallbackBase::Dispatcher >( &Dispatcher2< T, P&, const PropertyInputContainer& >::Dispatch ),
 159                     reinterpret_cast< CallbackBase::Destructor >( &Destroyer< T >::Delete ) ),
 160       mCopyConstructorDispatcher( reinterpret_cast< CopyConstructorDispatcher >( &ObjectCopyConstructorDispatcher< T >::Copy ) )
 161     {
 162     }
 163
 164     /**
 165      * @brief Clones the Function object.
 166      *
 167      * The object, if held by this object, is also copied.
 168      *
 169      * @SINCE_1_0.0
 170      * @return A pointer to a newly-allocated Function
 171      */
 172     CallbackBase* Clone()
 173     {
 174       CallbackBase* callback = NULL;
 175       if ( mImpl && mImpl->mObjectPointer && mCopyConstructorDispatcher )
 176       {
 177         callback = new Function( mCopyConstructorDispatcher( reinterpret_cast< UndefinedClass* >( mImpl->mObjectPointer ) ) /* Copy the object */,
 178                                  mMemberFunction,
 179                                  mImpl->mMemberFunctionDispatcher,
 180                                  mImpl->mDestructorDispatcher,
 181                                  mCopyConstructorDispatcher );
 182       }
 183       else
 184       {
 185         callback = new Function( mFunction );
 186       }
 187       return callback;
 188     }
 189
 190   private:
 191
 192     /**
 193      * @brief Must not be declared.
 194      *
 195      * This is used so that no optimisations are done by the compiler when using void*.
 196      */
 197     class UndefinedClass;
 198
 199     /**
 200      * @brief Used to call the function to copy the stored object.
 201      * @SINCE_1_0.0
 202      */
 203     typedef UndefinedClass* (*CopyConstructorDispatcher) ( UndefinedClass* object );
 204
 205     /**
 206      * @brief Copies the actual object in Constraint::Function.
 207      *
 208      * @SINCE_1_0.0
 209          * @tparam T The type of the object
 210      */
 211     template< class T >
 212     struct ObjectCopyConstructorDispatcher
 213     {
 214       /**
 215        * @brief Copies the object stored in Constraint::Function.
 216        *
 217        * @SINCE_1_0.0
 218        * @param[in] object The object to copy
 219        * @return Newly allocated clone of the object
 220        */
 221       static UndefinedClass* Copy( const UndefinedClass* object )
 222       {
 223         T* copy = new T( *( reinterpret_cast< const T* >( object ) ) );
 224         return reinterpret_cast< UndefinedClass* >( copy );
 225       }
 226     };
 227
 228     Function( const Function& ) = delete; ///< Deleted copy constructor. @SINCE_1_0.0
 229     Function( Function&& ) = delete; ///< Deleted move constructor. @SINCE_1_9.25
 230     Function& operator=( const Function& ) = delete; ///< Deleted copy assignment operator. @SINCE_1_0.0
 231     Function& operator=( Function&& ) = delete; ///< Deleted move assignment operator. @SINCE_1_9.25
 232
 233     /**
 234      * @brief Constructor used when copying the stored object.
 235      *
 236      * @SINCE_1_0.0
 237      * @param[in]  object                     A newly copied object
 238      * @param[in]  memberFunction             The member function of the object
 239      * @param[in]  dispatcher                 Used to call the actual object
 240      * @param[in]  destructor                 Used to delete the owned object
 241      * @param[in]  copyConstructorDispatcher  Used to create a copy of the owned object
 242      */
 243     Function( void* object,
 244               CallbackBase::MemberFunction memberFunction,
 245               CallbackBase::Dispatcher dispatcher,
 246               CallbackBase::Destructor destructor,
 247               CopyConstructorDispatcher copyConstructorDispatcher )
 248     : CallbackBase( object, memberFunction, dispatcher, destructor ),
 249       mCopyConstructorDispatcher( copyConstructorDispatcher )
 250     {
 251     }
 252
 253     /**
 254      * @brief Constructor used when copying a simple stored function.
 255      *
 256      * @SINCE_1_0.0
 257      * @param[in] function The function to call
 258      */
 259     Function( CallbackBase::Function function )
 260     : CallbackBase( function ),
 261       mCopyConstructorDispatcher( NULL )
 262     {
 263     }
 264
 265     // Data
 266
 267     CopyConstructorDispatcher mCopyConstructorDispatcher; ///< Function to call to copy the stored object
 268   };
 269
 270   /**
 271    * @brief Enumeration for the action that will happen when the constraint is removed.
 272    *
 273    * The final value may be "baked" i.e. saved permanently.
 274    * Alternatively the constrained value may be discarded when the constraint is removed.
 275    * @SINCE_1_0.0
 276    */
 277   enum RemoveAction
 278   {
 279     BAKE,   ///< When the constraint is fully-applied, the constrained value is saved. @SINCE_1_9.28
 280     DISCARD ///< When the constraint is removed, the constrained value is discarded. @SINCE_1_9.28
 281   };
 282
 283   static const RemoveAction  DEFAULT_REMOVE_ACTION;  ///< BAKE
 284
 285   /**
 286    * @brief Creates an uninitialized Constraint; this can be initialized with Constraint::New().
 287    *
 288    * Calling member functions with an uninitialized Constraint handle is not allowed.
 289    * @SINCE_1_0.0
 290    */
 291   Constraint();
 292
 293   /**
 294    * @brief Creates a constraint which targets a property using a function or a static class member.
 295    *
 296    * The expected signature, for a Vector3 type for example, of the function is:
 297    * @code
 298    *   void MyFunction( Vector3&, const PropertyInputContainer& );
 299    * @endcode
 300    *
 301    * Create the constraint with this function as follows:
 302    *
 303    * @code
 304    *   Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, &MyFunction );
 305    * @endcode
 306    *
 307    * @SINCE_1_0.0
 308    * @param[in] handle      The handle to the property-owning object
 309    * @param[in] targetIndex The index of the property to constrain
 310    * @param[in] function    The function to call to set the constrained property value
 311    *
 312    * @tparam P The type of the property to constrain
 313    * @return The new constraint
 314    */
 315   template< class P >
 316   static Constraint New( Handle handle, Property::Index targetIndex, void( *function )( P&, const PropertyInputContainer& ) )
 317   {
 318     CallbackBase* callback = new Constraint::Function< P >( function );
 319     return New( handle, targetIndex, PropertyTypes::Get< P >(), callback );
 320   }
 321
 322   /**
 323    * @brief Creates a constraint which targets a property using a functor object.
 324    *
 325    * The expected structure, for a Vector3 type for example, of the functor object is:
 326    * @code
 327    *   struct MyObject
 328    *   {
 329    *     void operator() ( Vector3&, const PropertyInputContainer& );
 330    *   };
 331    * @endcode
 332    *
 333    * Create the constraint with this object as follows:
 334    *
 335    * @code
 336    *   Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, MyObject() );
 337    * @endcode
 338    *
 339    * @SINCE_1_0.0
 340    * @param[in] handle      The handle to the property-owning object
 341    * @param[in] targetIndex The index of the property to constraint
 342    * @param[in] object      The functor object whose functor is called to set the constrained property value
 343    *
 344    * @tparam P The type of the property to constrain
 345    * @tparam T The type of the object
 346    * @return The new constraint
 347    */
 348   template< class P, class T >
 349   static Constraint New( Handle handle, Property::Index targetIndex, const T& object )
 350   {
 351     CallbackBase* function = new Constraint::Function< P >( object );
 352     return New( handle, targetIndex, PropertyTypes::Get< P >(), function );
 353   }
 354
 355   /**
 356    * @brief Creates a constraint which targets a property using an object method.
 357    *
 358    * The expected structure, for a Vector3 type for example, of the object is:
 359    * @code
 360    *   struct MyObject
 361    *   {
 362    *     void MyMethod( Vector3&, const PropertyInputContainer& );
 363    *   };
 364    * @endcode
 365    *
 366    * Create the constraint with this object as follows:
 367    *
 368    * @code
 369    *   Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, MyObject(), &MyObject::MyMethod );
 370    * @endcode
 371    *
 372    * @SINCE_1_0.0
 373    * @param[in] handle         The handle to the property-owning object
 374    * @param[in] targetIndex    The index of the property to constraint
 375    * @param[in] object         The object whose member function is called to set the constrained property value
 376    * @param[in] memberFunction The member function to call to set the constrained property value
 377    * @return The new constraint
 378    *
 379    * @tparam P The type of the property to constrain
 380    * @tparam T The type of the object
 381    */
 382   template< class P, class T >
 383   static Constraint New( Handle handle, Property::Index targetIndex, const T& object, void ( T::*memberFunction ) ( P&, const PropertyInputContainer& ) )
 384   {
 385     CallbackBase* function = new Constraint::Function< P >( object, memberFunction );
 386     return New( handle, targetIndex, PropertyTypes::Get< P >(), function );
 387   }
 388
 389   /**
 390    * @brief Creates a clone of this constraint for another object.
 391    *
 392    * @SINCE_1_0.0
 393    * @param[in] handle The handle to the property-owning object this constraint is to be cloned for
 394    * @return The new constraint
 395    */
 396   Constraint Clone( Handle handle );
 397
 398   /**
 399    * @brief Destructor.
 400    *
 401    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 402    * @SINCE_1_0.0
 403    */
 404   ~Constraint();
 405
 406   /**
 407    * @brief This copy constructor is required for (smart) pointer semantics.
 408    *
 409    * @SINCE_1_0.0
 410    * @param[in] constraint A reference to the copied handle
 411    */
 412   Constraint( const Constraint& constraint );
 413
 414   /**
 415    * @brief This assignment operator is required for (smart) pointer semantics.
 416    *
 417    * @SINCE_1_0.0
 418    * @param[in] rhs A reference to the copied handle
 419    * @return A reference to this
 420    */
 421   Constraint& operator=( const Constraint& rhs );
 422
 423   /**
 424    * @brief Move constructor.
 425    *
 426    * @SINCE_1_9.22
 427    * @param[in] rhs A reference to the moved handle
 428    */
 429   Constraint( Constraint&& rhs );
 430
 431   /**
 432    * @brief Move assignment operator.
 433    *
 434    * @SINCE_1_9.22
 435    * @param[in] rhs A reference to the moved handle
 436    * @return A reference to this handle
 437    */
 438   Constraint& operator=( Constraint&& rhs );
 439
 440   /**
 441    * @brief Downcasts a handle to Constraint handle.
 442    *
 443    * If handle points to a Constraint object, the downcast produces valid handle.
 444    * If not, the returned handle is left uninitialized.
 445    * @SINCE_1_0.0
 446    * @param[in] baseHandle BaseHandle to an object
 447    * @return Handle to a Constraint object or an uninitialized handle
 448    */
 449   static Constraint DownCast( BaseHandle baseHandle );
 450
 451   /**
 452    * @brief Adds a constraint source to the constraint.
 453    *
 454    * @SINCE_1_0.0
 455    * @param[in] source The constraint source input to add
 456    */
 457   void AddSource( ConstraintSource source );
 458
 459   /**
 460    * @brief Applies this constraint.
 461    *
 462    * @SINCE_1_0.0
 463    * @pre The constraint must be initialized.
 464    * @pre The target object must still be alive.
 465    * @pre The source inputs should not have been destroyed.
 466    */
 467   void Apply();
 468
 469   /**
 470    * @brief Removes this constraint.
 471    * @SINCE_1_0.0
 472    */
 473   void Remove();
 474
 475   /**
 476    * @brief Retrieves the object which this constraint is targeting.
 477    *
 478    * @SINCE_1_0.0
 479    * @return The target object
 480    */
 481   Handle GetTargetObject();
 482
 483   /**
 484    * @brief Retrieves the property which this constraint is targeting.
 485    *
 486    * @SINCE_1_0.0
 487    * @return The target property
 488    */
 489   Dali::Property::Index GetTargetProperty();
 490
 491   /**
 492    * @brief Sets the remove action. Constraint::BAKE will "bake" a value when fully-applied.
 493    *
 494    * In case of Constraint::DISCARD, the constrained value will be discarded, when the constraint is removed.
 495    * The default value is Constraint::BAKE.
 496    * @SINCE_1_0.0
 497    * @param[in] action The remove-action
 498    */
 499   void SetRemoveAction( RemoveAction action );
 500
 501   /**
 502    * @brief Retrieves the remove action that will happen when the constraint is removed.
 503    *
 504    * @SINCE_1_0.0
 505    * @return The remove-action
 506    */
 507   RemoveAction GetRemoveAction() const;
 508
 509   /**
 510    * @brief Sets a tag for the constraint so it can be identified later.
 511    *
 512    * @SINCE_1_0.0
 513    * @param[in] tag An integer to identify the constraint
 514    */
 515   void SetTag( const uint32_t tag );
 516
 517   /**
 518    * @brief Gets the tag.
 519    *
 520    * @SINCE_1_0.0
 521    * @return The tag
 522    */
 523   uint32_t GetTag() const;
 524
 525 public: // Not intended for use by Application developers
 526
 527   /// @cond internal
 528   /**
 529    * @brief This constructor is used by Constraint::New() methods.
 530    * @SINCE_1_0.0
 531    * @param[in] constraint A pointer to a newly allocated Dali resource
 532    */
 533   explicit DALI_INTERNAL Constraint( Internal::ConstraintBase* constraint );
 534   /// @endcond
 535
 536 private: // Not intended for use by Application developers
 537
 538   /// @cond internal
 539   /**
 540    * @brief Constructs a new constraint which targets a property.
 541    *
 542    * @SINCE_1_0.0
 543    * @param[in]  handle       The handle to the property-owning object
 544    * @param[in]  targetIndex  The index of the property to constrain
 545    * @param[in]  targetType   Type The type of the constrained property
 546    * @param[in]  function     The constraint function
 547    * @return The new constraint
 548    */
 549   static Constraint New( Handle handle, Property::Index targetIndex, Property::Type targetType, CallbackBase* function );
 550   /// @endcond
 551 };
 552
 553 /**
 554  * @}
 555  */
 556 } // namespace Dali
 557
 558 #endif // DALI_CONSTRAINT_H