dali/public-api/animation/constraint.h

   1 #ifndef __DALI_CONSTRAINT_H__
   2 #define __DALI_CONSTRAINT_H__
   3
   4 /*
   5  * Copyright (c) 2014 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 <boost/function.hpp>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/animation/alpha-functions.h>
  26 #include <dali/public-api/animation/constraint-source.h>
  27 #include <dali/public-api/object/any.h>
  28 #include <dali/public-api/object/handle.h>
  29 #include <dali/public-api/object/property.h>
  30 #include <dali/public-api/object/property-input.h>
  31
  32 namespace Dali
  33 {
  34 struct TimePeriod;
  35
  36 namespace Internal DALI_INTERNAL
  37 {
  38 class Constraint;
  39 }
  40
  41 /**
  42  * @brief An abstract base class for Constraints.
  43  * This can be used to constrain a property of an actor, after animations have been applied.
  44  * Constraints are applied in the following order:
  45  *   - Constraints are applied to on-stage actors in a depth-first traversal.
  46  *   - For each actor, the constraints are applied in the same order as the calls to Actor::ApplyConstraint().
  47  *   - Constraints are not applied to off-stage actors.
  48  */
  49 class DALI_IMPORT_API Constraint : public BaseHandle
  50 {
  51 public:
  52
  53   typedef Any AnyFunction; ///< Generic function pointer for constraint
  54
  55   /**
  56    * @brief The action that will happen when the constraint is removed.
  57    *
  58    * Constraints can be applied gradually; see SetApplyTime() for more details.
  59    * When a constraint is fully-applied the final value may be "baked" i.e. saved permanently.
  60    * Alternatively the constrained value may be discarded when the constraint is removed.
  61    */
  62   enum RemoveAction
  63   {
  64     Bake,   ///< When the constraint is fully-applied, the constrained value is saved.
  65     Discard ///< When the constraint is removed, the constrained value is discarded.
  66   };
  67
  68   static const AlphaFunction DEFAULT_ALPHA_FUNCTION; ///< AlphaFunctions::Linear
  69   static const RemoveAction  DEFAULT_REMOVE_ACTION;  ///< Bake
  70
  71   /**
  72    * @brief Create an uninitialized Constraint; this can be initialized with Constraint::New().
  73    *
  74    * Calling member functions with an uninitialized Dali::Object is not allowed.
  75    */
  76   Constraint();
  77
  78   /**
  79    * @brief Create a constraint which targets a property.
  80    *
  81    * The templated parameter P, is the type of the property to constrain.
  82    * @param [in] target The index of the property to constrain.
  83    * @param [in] func A function which returns the constrained property value.
  84    * @return The new constraint.
  85    */
  86   template <class P>
  87   static Constraint New( Property::Index target,
  88                          boost::function<P (const P& current)> func )
  89   {
  90     return New( target,
  91                 PropertyTypes::Get<P>(),
  92                 func );
  93   }
  94
  95   /**
  96    * @brief Create a constraint which targets a property.
  97    *
  98    * The templated parameter P, is the type of the property to constrain.
  99    * @param [in] target The index of the property to constrain.
 100    * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
 101    * @param [in] func A function which returns the constrained property value.
 102    * @return The new constraint.
 103    */
 104   template <class P>
 105   static Constraint New( Property::Index target,
 106                          ConstraintSource source1,
 107                          boost::function<P (const P& current, const PropertyInput& input1)> func )
 108   {
 109     return New( target,
 110                 PropertyTypes::Get<P>(),
 111                 source1,
 112                 func );
 113   }
 114
 115   /**
 116    * @brief Create a constraint which targets a property.
 117    *
 118    * The templated parameter P, is the type of the property to constrain.
 119    * @param [in] target The index of the property to constrain.
 120    * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
 121    * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
 122    * @param [in] func A function which returns the constrained property value.
 123    * @return The new constraint.
 124    */
 125   template <class P>
 126   static Constraint New( Property::Index target,
 127                          ConstraintSource source1,
 128                          ConstraintSource source2,
 129                          boost::function<P (const P& current, const PropertyInput& input1, const PropertyInput& input2)> func )
 130   {
 131     return New( target,
 132                 PropertyTypes::Get<P>(),
 133                 source1,
 134                 source2,
 135                 func );
 136   }
 137
 138   /**
 139    * @brief Create a constraint which targets a property.
 140    *
 141    * The templated parameter P, is the type of the property to constrain.
 142    * @param [in] target The index of the property to constrain.
 143    * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
 144    * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
 145    * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
 146    * @param [in] func A function which returns the constrained property value.
 147    * @return The new constraint.
 148    */
 149   template <class P>
 150   static Constraint New( Property::Index target,
 151                          ConstraintSource source1,
 152                          ConstraintSource source2,
 153                          ConstraintSource source3,
 154                          boost::function<P (const P& current, const PropertyInput& input1, const PropertyInput& input2, const PropertyInput& input3)> func )
 155   {
 156     return New( target,
 157                 PropertyTypes::Get<P>(),
 158                 source1,
 159                 source2,
 160                 source3,
 161                 func );
 162   }
 163
 164   /**
 165    * @brief Create a constraint which targets a property.
 166    *
 167    * The templated parameter P, is the type of the property to constrain.
 168    * @param [in] target The index of the property to constrain.
 169    * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
 170    * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
 171    * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
 172    * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
 173    * @param [in] func A function which returns the constrained property value.
 174    * @return The new constraint.
 175    */
 176   template <class P>
 177   static Constraint New( Property::Index target,
 178                          ConstraintSource source1,
 179                          ConstraintSource source2,
 180                          ConstraintSource source3,
 181                          ConstraintSource source4,
 182                          boost::function<P (const P& current,
 183                                             const PropertyInput& input1,
 184                                             const PropertyInput& input2,
 185                                             const PropertyInput& input3,
 186                                             const PropertyInput& input4)> func )
 187   {
 188     return New( target,
 189                 PropertyTypes::Get<P>(),
 190                 source1,
 191                 source2,
 192                 source3,
 193                 source4,
 194                 func );
 195   }
 196
 197   /**
 198    * @brief Create a constraint which targets a property.
 199    *
 200    * The templated parameter P, is the type of the property to constrain.
 201    * @param [in] target The index of the property to constrain.
 202    * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
 203    * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
 204    * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
 205    * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
 206    * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
 207    * @param [in] func A function which returns the constrained property value.
 208    * @return The new constraint.
 209    */
 210   template <class P>
 211   static Constraint New( Property::Index target,
 212                          ConstraintSource source1,
 213                          ConstraintSource source2,
 214                          ConstraintSource source3,
 215                          ConstraintSource source4,
 216                          ConstraintSource source5,
 217                          boost::function<P (const P& current,
 218                                             const PropertyInput& input1,
 219                                             const PropertyInput& input2,
 220                                             const PropertyInput& input3,
 221                                             const PropertyInput& input4,
 222                                             const PropertyInput& input5)> func )
 223   {
 224     return New( target,
 225                 PropertyTypes::Get<P>(),
 226                 source1,
 227                 source2,
 228                 source3,
 229                 source4,
 230                 source5,
 231                 func );
 232   }
 233
 234   /**
 235    * @brief Create a constraint which targets a property.
 236    *
 237    * The templated parameter P, is the type of the property to constrain.
 238    * @param [in] target The index of the property to constrain.
 239    * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
 240    * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
 241    * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
 242    * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
 243    * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
 244    * @param [in] source6 The source of a property; the current value will be passed as the 7th parameter of func.
 245    * @param [in] func A function which returns the constrained property value.
 246    * @return The new constraint.
 247    */
 248   template <class P>
 249   static Constraint New( Property::Index target,
 250                          ConstraintSource source1,
 251                          ConstraintSource source2,
 252                          ConstraintSource source3,
 253                          ConstraintSource source4,
 254                          ConstraintSource source5,
 255                          ConstraintSource source6,
 256                          boost::function<P (const P& current,
 257                                             const PropertyInput& input1,
 258                                             const PropertyInput& input2,
 259                                             const PropertyInput& input3,
 260                                             const PropertyInput& input4,
 261                                             const PropertyInput& input5,
 262                                             const PropertyInput& input6)> func )
 263   {
 264     return New( target,
 265                 PropertyTypes::Get<P>(),
 266                 source1,
 267                 source2,
 268                 source3,
 269                 source4,
 270                 source5,
 271                 source6,
 272                 func );
 273   }
 274
 275   /**
 276    * @brief Downcast an Object handle to Constraint handle.
 277    *
 278    * If handle points to a Constraint object the
 279    * downcast produces valid handle. If not the returned handle is left uninitialized.
 280    * @param[in] handle to An object
 281    * @return handle to a Constraint object or an uninitialized handle
 282    */
 283   static Constraint DownCast( BaseHandle handle );
 284
 285   /**
 286    * @brief Destructor
 287    *
 288    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 289    */
 290   ~Constraint();
 291
 292   /**
 293    * @brief This copy constructor is required for (smart) pointer semantics.
 294    *
 295    * @param [in] handle A reference to the copied handle
 296    */
 297   Constraint(const Constraint& handle);
 298
 299   /**
 300    * @brief This assignment operator is required for (smart) pointer semantics.
 301    *
 302    * @param [in] rhs  A reference to the copied handle
 303    * @return A reference to this
 304    */
 305   Constraint& operator=(const Constraint& rhs);
 306
 307   /**
 308    * @brief Set the time taken for the constraint to be fully applied.
 309    *
 310    * The default is zero, meaning that the constraint is applied immediately.
 311    * @param [in] timePeriod The constraint will be applied during this time period.
 312    */
 313   void SetApplyTime( TimePeriod timePeriod );
 314
 315   /**
 316    * @brief Retrieve the time taken for the constraint to be fully applied.
 317    *
 318    * @return The apply time.
 319    */
 320   TimePeriod GetApplyTime() const;
 321
 322   /**
 323    * @brief Set the alpha function for a constraint; the default is AlphaFunctions::Linear.
 324    *
 325    * @param [in] func The alpha function to use when applying/removing the constraint.
 326    */
 327   void SetAlphaFunction( AlphaFunction func );
 328
 329   /**
 330    * @brief Retrieve the alpha function of a constraint.
 331    *
 332    * @return The function.
 333    */
 334   AlphaFunction GetAlphaFunction();
 335
 336   /**
 337    * @brief Set whether the constraint will "bake" a value when fully-applied.
 338    *
 339    * Otherwise the constrained value will be discarded, when the constraint is removed.
 340    * The default value is Constraint::Bake.
 341    * @param[in] action The remove-action.
 342    */
 343   void SetRemoveAction( RemoveAction action );
 344
 345   /**
 346    * @brief Query whether the constraint will "bake" a value when fully-applied.
 347    *
 348    * Otherwise the constrained value will be discarded, when the constraint is removed.
 349    * @return The apply-action.
 350    */
 351   RemoveAction GetRemoveAction() const;
 352
 353   /**
 354    * @brief Set a tag for the constraint so it can be identified later
 355    *
 356    * @param[in] tag An integer to identify the constraint
 357    */
 358   void SetTag( const unsigned int tag );
 359
 360   /**
 361    * @brief Get the tag
 362    *
 363    * @return The tag
 364    */
 365   unsigned int GetTag() const;
 366
 367 public: // Not intended for use by Application developers
 368
 369   /**
 370    * @brief This constructor is used by Dali New() methods
 371    * @param [in] constraint A pointer to a newly allocated Dali resource
 372    */
 373   explicit DALI_INTERNAL Constraint( Internal::Constraint* constraint );
 374
 375 private: // Not intended for use by Application developers
 376
 377   /**
 378    * @brief Construct a new constraint which targets a property.
 379    *
 380    * @param [in] target The index of the property to constrain.
 381    * @param [in] targetType The type of the constrained property.
 382    * @param [in] func The constraint function.
 383    * @return The new constraint.
 384    */
 385   static Constraint New( Property::Index target,
 386                          Property::Type targetType,
 387                          AnyFunction func );
 388
 389   /**
 390    * @brief Construct a new constraint which targets a property.
 391    *
 392    * @param [in] target The index of the property to constrain.
 393    * @param [in] targetType The type of the constrained property.
 394    * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
 395    * @param [in] func The constraint function.
 396    * @return The new constraint.
 397    */
 398   static Constraint New( Property::Index target,
 399                          Property::Type targetType,
 400                          ConstraintSource source1,
 401                          AnyFunction func );
 402
 403   /**
 404    * @brief Construct a new constraint which targets a property.
 405    *
 406    * @param [in] target The index of the property to constrain.
 407    * @param [in] targetType The type of the constrained property.
 408    * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
 409    * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
 410    * @param [in] func The constraint function.
 411    * @return The new constraint.
 412    */
 413   static Constraint New( Property::Index target,
 414                          Property::Type targetType,
 415                          ConstraintSource source1,
 416                          ConstraintSource source2,
 417                          AnyFunction func );
 418
 419   /**
 420    * @brief Construct a new constraint which targets a property.
 421    *
 422    * @param [in] target The index of the property to constrain.
 423    * @param [in] targetType The type of the constrained property.
 424    * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
 425    * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
 426    * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
 427    * @param [in] func The constraint function.
 428    * @return The new constraint.
 429    */
 430   static Constraint New( Property::Index target,
 431                          Property::Type targetType,
 432                          ConstraintSource source1,
 433                          ConstraintSource source2,
 434                          ConstraintSource source3,
 435                          AnyFunction func );
 436
 437   /**
 438    * @brief Construct a new constraint which targets a property.
 439    *
 440    * @param [in] target The index of the property to constrain.
 441    * @param [in] targetType The type of the constrained property.
 442    * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
 443    * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
 444    * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
 445    * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
 446    * @param [in] func The constraint function.
 447    * @return The new constraint.
 448    */
 449   static Constraint New( Property::Index target,
 450                          Property::Type targetType,
 451                          ConstraintSource source1,
 452                          ConstraintSource source2,
 453                          ConstraintSource source3,
 454                          ConstraintSource source4,
 455                          AnyFunction func );
 456
 457   /**
 458    * @brief Construct a new constraint which targets a property.
 459    *
 460    * @param [in] target The index of the property to constrain.
 461    * @param [in] targetType The type of the constrained property.
 462    * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
 463    * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
 464    * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
 465    * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
 466    * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
 467    * @param [in] func The constraint function.
 468    * @return The new constraint.
 469    */
 470   static Constraint New( Property::Index target,
 471                          Property::Type targetType,
 472                          ConstraintSource source1,
 473                          ConstraintSource source2,
 474                          ConstraintSource source3,
 475                          ConstraintSource source4,
 476                          ConstraintSource source5,
 477                          AnyFunction func );
 478
 479   /**
 480    * @brief Construct a new constraint which targets a property.
 481    *
 482    * @param [in] target The index of the property to constrain.
 483    * @param [in] targetType The type of the constrained property.
 484    * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
 485    * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
 486    * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
 487    * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
 488    * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
 489    * @param [in] source6 The source of a property; the current value will be passed as the 7th parameter of func.
 490    * @param [in] func The constraint function.
 491    * @return The new constraint.
 492    */
 493   static Constraint New( Property::Index target,
 494                          Property::Type targetType,
 495                          ConstraintSource source1,
 496                          ConstraintSource source2,
 497                          ConstraintSource source3,
 498                          ConstraintSource source4,
 499                          ConstraintSource source5,
 500                          ConstraintSource source6,
 501                          AnyFunction func );
 502 };
 503
 504 } // namespace Dali
 505
 506 #endif // __DALI_CONSTRAINT_H__