1 /** 2 * @file 3 * @brief Header file for the Keyframe class 4 * @author Jonathan Thomas <jonathan@openshot.org> 5 * 6 * @ref License 7 */ 8 9 /* LICENSE 10 * 11 * Copyright (c) 2008-2019 OpenShot Studios, LLC 12 * <http://www.openshotstudios.com/>. This file is part of 13 * OpenShot Library (libopenshot), an open-source project dedicated to 14 * delivering high quality video editing and animation solutions to the 15 * world. For more information visit <http://www.openshot.org/>. 16 * 17 * OpenShot Library (libopenshot) is free software: you can redistribute it 18 * and/or modify it under the terms of the GNU Lesser General Public License 19 * as published by the Free Software Foundation, either version 3 of the 20 * License, or (at your option) any later version. 21 * 22 * OpenShot Library (libopenshot) is distributed in the hope that it will be 23 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of 24 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 25 * GNU Lesser General Public License for more details. 26 * 27 * You should have received a copy of the GNU Lesser General Public License 28 * along with OpenShot Library. If not, see <http://www.gnu.org/licenses/>. 29 */ 30 31 #ifndef OPENSHOT_KEYFRAME_H 32 #define OPENSHOT_KEYFRAME_H 33 34 #include <cmath> 35 #include <vector> 36 37 #include "Fraction.h" 38 #include "Point.h" 39 #include "Json.h" 40 41 namespace openshot { 42 43 /// Check if the X coordinate of a given Point is lower than a given value 44 bool IsPointBeforeX(Point const & p, double const x); 45 46 /// Linear interpolation between two points 47 double InterpolateLinearCurve(Point const & left, Point const & right, double const target); 48 49 /// Bezier interpolation between two points 50 double InterpolateBezierCurve(Point const & left, Point const & right, double const target, double const allowed_error); 51 52 /// Interpolate two points using the right Point's interpolation method 53 double InterpolateBetween(Point const & left, Point const & right, double target, double allowed_error); 54 55 /** 56 * @brief A Keyframe is a collection of Point instances, which is used to vary a number or property over time. 57 * 58 * Keyframes are used to animate and interpolate values of properties over time. For example, a single property 59 * can use a Keyframe instead of a constant value. Assume you want to slide an image (from left to right) over 60 * a video. You can create a Keyframe which will adjust the X value of the image over 100 frames (or however many 61 * frames the animation needs to last) from the value of 0 to 640. 62 * 63 * Please see the following <b>Example Code</b>: 64 * \code 65 * Keyframe k1; 66 * k1.AddPoint(Point(1,0)); 67 * k1.AddPoint(Point(100,640)); 68 * 69 * kf.PrintValues(); 70 * \endcode 71 */ 72 class Keyframe { 73 74 75 private: 76 std::vector<Point> Points; ///< Vector of all Points 77 78 public: 79 /// Default constructor for the Keyframe class 80 Keyframe() = default; 81 82 /// Constructor which sets the default point & coordinate at X=1 83 Keyframe(double value); 84 85 /// Constructor which adds a supplied vector of Points 86 Keyframe(const std::vector<openshot::Point>& points); 87 88 /// Add a new point on the key-frame. Each point has a primary coordinate, a left handle, and a right handle. 89 void AddPoint(Point p); 90 91 /// Add a new point on the key-frame, with optional interpolation type 92 void AddPoint(double x, double y, InterpolationType interpolate=BEZIER); 93 94 /// Does this keyframe contain a specific point 95 bool Contains(Point p) const; 96 97 /// Flip all the points in this openshot::Keyframe (useful for reversing an effect or transition, etc...) 98 void FlipPoints(); 99 100 /// Get the index of a point by matching a coordinate 101 int64_t FindIndex(Point p) const; 102 103 /// Get the value at a specific index 104 double GetValue(int64_t index) const; 105 106 /// Get the rounded INT value at a specific index 107 int GetInt(int64_t index) const; 108 109 /// Get the rounded LONG value at a specific index 110 int64_t GetLong(int64_t index) const; 111 112 /// Get the fraction that represents how many times this value is repeated in the curve 113 Fraction GetRepeatFraction(int64_t index) const; 114 115 /// Get the change in Y value (from the previous Y value) 116 double GetDelta(int64_t index) const; 117 118 /// Get a point at a specific index 119 Point const & GetPoint(int64_t index) const; 120 121 /// Get current point (or closest point to the right) from the X coordinate (i.e. the frame number) 122 Point GetClosestPoint(Point p) const; 123 124 /// Get current point (or closest point) from the X coordinate (i.e. the frame number) 125 /// Either use the closest left point, or right point 126 Point GetClosestPoint(Point p, bool useLeft) const; 127 128 /// Get previous point ( 129 Point GetPreviousPoint(Point p) const; 130 131 /// Get max point (by Y coordinate) 132 Point GetMaxPoint() const; 133 134 // Get the number of values (i.e. coordinates on the X axis) 135 int64_t GetLength() const; 136 137 /// Get the number of points (i.e. # of points) 138 int64_t GetCount() const; 139 140 /// Get the direction of the curve at a specific index (increasing or decreasing) 141 bool IsIncreasing(int index) const; 142 143 // Get and Set JSON methods 144 std::string Json() const; ///< Generate JSON string of this object 145 Json::Value JsonValue() const; ///< Generate Json::Value for this object 146 void SetJson(const std::string value); ///< Load JSON string into this object 147 void SetJsonValue(const Json::Value root); ///< Load Json::Value into this object 148 149 /// Remove a point by matching a coordinate 150 void RemovePoint(Point p); 151 152 /// Remove a point by index 153 void RemovePoint(int64_t index); 154 155 /// Scale all points by a percentage (good for evenly lengthening or shortening an openshot::Keyframe) 156 /// 1.0 = same size, 1.05 = 5% increase, etc... 157 void ScalePoints(double scale); 158 159 /// Replace an existing point with a new point 160 void UpdatePoint(int64_t index, Point p); 161 162 /// Print a list of points 163 void PrintPoints() const; 164 165 /// Print just the Y value of the point's primary coordinate 166 void PrintValues() const; 167 168 }; 169 170 } 171 172 #endif 173