dali/public-api/animation/path.h

   1 #ifndef DALI_PATH_H
   2 #define DALI_PATH_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 // INTERNAL INCLUDES
  22 #include <dali/public-api/object/handle.h>
  23 #include <dali/public-api/object/property-index-ranges.h>
  24
  25 namespace Dali
  26 {
  27 /**
  28  * @addtogroup dali_core_animation
  29  * @{
  30  */
  31
  32 namespace Internal DALI_INTERNAL
  33 {
  34 class Path;
  35 }
  36
  37 /**
  38  * @brief A 3D parametric curve.
  39  *
  40  * Paths can be used to animate position and orientation of actors using Dali::Animate().
  41  *
  42  * @SINCE_1_0.0
  43  */
  44 class DALI_CORE_API Path : public Handle
  45 {
  46 public:
  47   /**
  48    * @brief Enumeration for the instance of properties belonging to the Path class.
  49    * @SINCE_1_0.0
  50    */
  51   struct Property
  52   {
  53     /**
  54      * @brief Enumeration for the instance of properties belonging to the Path class.
  55      * @SINCE_1_0.0
  56      */
  57     enum
  58     {
  59       POINTS = DEFAULT_OBJECT_PROPERTY_START_INDEX, ///< name "points",         type Vector3 @SINCE_1_0.0
  60       CONTROL_POINTS,                               ///< name "controlPoints",  type Vector3 @SINCE_1_0.0
  61     };
  62   };
  63
  64   /**
  65    * @brief Creates an initialized Path handle.
  66    *
  67    * @SINCE_1_0.0
  68    * @return A handle to a newly allocated Dali resource
  69    */
  70   static Path New();
  71
  72   /**
  73    * @brief Downcasts a handle to Path handle.
  74    *
  75    * If handle points to a Path object, the downcast produces valid handle.
  76    * If not, the returned handle is left uninitialized.
  77    * @SINCE_1_0.0
  78    * @param[in] handle Handle to an object
  79    * @return Handle to a Path object or an uninitialized handle
  80    */
  81   static Path DownCast(BaseHandle handle);
  82
  83   /**
  84    * @brief Creates an uninitialized Path handle.
  85    *
  86    * This can be initialized with Path::New().
  87    * Calling member functions with an uninitialized Path handle is not allowed.
  88    * @SINCE_1_0.0
  89    */
  90   Path();
  91
  92   /**
  93    * @brief Destructor.
  94    *
  95    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  96    * @SINCE_1_0.0
  97    */
  98   ~Path();
  99
 100   /**
 101    * @brief This copy constructor is required for (smart) pointer semantics.
 102    *
 103    * @SINCE_1_0.0
 104    * @param[in] handle A reference to the copied handle
 105    */
 106   Path(const Path& handle);
 107
 108   /**
 109    * @brief This assignment operator is required for (smart) pointer semantics.
 110    *
 111    * @SINCE_1_0.0
 112    * @param[in] rhs A reference to the copied handle
 113    * @return A reference to this
 114    */
 115   Path& operator=(const Path& rhs);
 116
 117   /**
 118    * @brief Move constructor.
 119    *
 120    * @SINCE_1_9.22
 121    * @param[in] rhs A reference to the moved handle
 122    */
 123   Path(Path&& rhs);
 124
 125   /**
 126    * @brief Move assignment operator.
 127    *
 128    * @SINCE_1_9.22
 129    * @param[in] rhs A reference to the moved handle
 130    * @return A reference to this
 131    */
 132   Path& operator=(Path&& rhs);
 133
 134   /**
 135    * @brief Adds an interpolation point.
 136    *
 137    * @SINCE_1_0.0
 138    * @param[in] point The new interpolation point to be added
 139    */
 140   void AddPoint(const Vector3& point);
 141
 142   /**
 143    * @brief Adds a control point.
 144    *
 145    * @SINCE_1_0.0
 146    * @param[in] point The new control point to be added
 147    */
 148   void AddControlPoint(const Vector3& point);
 149
 150   /**
 151    * @brief Automatic generation of control points. Generated control points which result in a smooth join between the splines of each segment.
 152    *
 153    * The generating algorithm is as follows:
 154    * For a given knot point K[N], find the vector that bisects K[N-1],[N] and [N],[N+1].
 155    * Calculate the tangent vector by taking the normal of this bisector.
 156    * The in control point is the length of the preceding segment back along this bisector multiplied by the curvature.
 157    * The out control point is the length of the succeeding segment forward along this bisector multiplied by the curvature.
 158    *
 159    * @SINCE_1_0.0
 160    * @param[in] curvature The curvature of the spline. 0 gives straight lines between the knots,
 161    *                      negative values means the spline contains loops, positive values up to
 162    *                      0.5 result in a smooth curve, positive values between 0.5 and 1 result
 163    *                      in looped curves where the loops are not distinct (i.e. the curve appears
 164    *                      to be non-continuous), positive values higher than 1 result in looped curves
 165    * @pre There are at least two points in the path ( one segment ).
 166    *
 167    */
 168   void GenerateControlPoints(float curvature);
 169
 170   /**
 171    * @brief Sample path at a given progress. Calculates position and tangent at that point of the curve.
 172    *
 173    * @SINCE_1_0.0
 174    * @param[in] progress A floating point value between 0.0 and 1.0
 175    * @param[out] position The interpolated position at that progress
 176    * @param[out] tangent The interpolated tangent at that progress
 177    */
 178   void Sample(float progress, Vector3& position, Vector3& tangent) const;
 179
 180   /**
 181    * @brief Accessor for the interpolation points.
 182    *
 183    * @SINCE_1_0.0
 184    * @param[in] index The index of the interpolation point
 185    * @return A reference to the interpolation point
 186    */
 187   Vector3& GetPoint(size_t index);
 188
 189   /**
 190    * @brief Accessor for the control points.
 191    *
 192    * @SINCE_1_0.0
 193    * @param[in] index The index of the control point
 194    * @return A reference to the control point
 195    */
 196   Vector3& GetControlPoint(size_t index);
 197
 198   /**
 199    * @brief Gets the number of interpolation points in the path.
 200    *
 201    * @SINCE_1_0.0
 202    * @return The number of interpolation points in the path
 203    */
 204   size_t GetPointCount() const;
 205
 206 public: // Not intended for application developers
 207   /// @cond internal
 208   /**
 209    * @brief This constructor is used by Path::New() methods.
 210    *
 211    * @SINCE_1_0.0
 212    * @param[in] path A pointer to an internal path resource
 213    */
 214   explicit DALI_INTERNAL Path(Internal::Path* path);
 215   /// @endcond
 216 };
 217
 218 /**
 219  * @}
 220  */
 221 } // namespace Dali
 222
 223 #endif // DALI_PATH_H