dali/public-api/animation/constraint.h

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