example/rlottiePlayer/rlottie.h

   1 /*
   2  * Copyright (c) 2020 Samsung Electronics Co., Ltd. All rights reserved.
   3
   4  * Permission is hereby granted, free of charge, to any person obtaining a copy
   5  * of this software and associated documentation files (the "Software"), to deal
   6  * in the Software without restriction, including without limitation the rights
   7  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   8  * copies of the Software, and to permit persons to whom the Software is
   9  * furnished to do so, subject to the following conditions:
  10
  11  * The above copyright notice and this permission notice shall be included in all
  12  * copies or substantial portions of the Software.
  13
  14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  19  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  20  * SOFTWARE.
  21  */
  22
  23 #ifndef _RLOTTIE_H_
  24 #define _RLOTTIE_H_
  25
  26 #include <future>
  27 #include <vector>
  28 #include <memory>
  29
  30 #if defined _WIN32 || defined __CYGWIN__
  31   #ifdef RLOTTIE_BUILD
  32     #define RLOTTIE_API __declspec(dllexport)
  33   #else
  34     #define RLOTTIE_API __declspec(dllimport)
  35   #endif
  36 #else
  37   #ifdef RLOTTIE_BUILD
  38       #define RLOTTIE_API __attribute__ ((visibility ("default")))
  39   #else
  40       #define RLOTTIE_API
  41   #endif
  42 #endif
  43
  44 class AnimationImpl;
  45 struct LOTNode;
  46 struct LOTLayerNode;
  47
  48 namespace rlottie {
  49
  50 /**
  51  *  @brief Configures rlottie model cache policy.
  52  *
  53  *  Provides Library level control to configure model cache
  54  *  policy. Setting it to 0 will disable
  55  *  the cache as well as flush all the previously cached content.
  56  *
  57  *  @param[in] cacheSize  Maximum Model Cache size.
  58  *
  59  *  @note to disable Caching configure with 0 size.
  60  *  @note to flush the current Cache content configure it with 0 and
  61  *        then reconfigure with the new size.
  62  *
  63  *  @internal
  64  */
  65 RLOTTIE_API void configureModelCacheSize(size_t cacheSize);
  66
  67 struct Color {
  68     Color() = default;
  69     Color(float r, float g , float b):_r(r), _g(g), _b(b){}
  70     float r() const {return _r;}
  71     float g() const {return _g;}
  72     float b() const {return _b;}
  73 private:
  74     float _r{0};
  75     float _g{0};
  76     float _b{0};
  77 };
  78
  79 struct Size {
  80     Size() = default;
  81     Size(float w, float h):_w(w), _h(h){}
  82     float w() const {return _w;}
  83     float h() const {return _h;}
  84 private:
  85     float _w{0};
  86     float _h{0};
  87 };
  88
  89 struct Point {
  90     Point() = default;
  91     Point(float x, float y):_x(x), _y(y){}
  92     float x() const {return _x;}
  93     float y() const {return _y;}
  94 private:
  95     float _x{0};
  96     float _y{0};
  97 };
  98
  99 struct FrameInfo {
 100     explicit FrameInfo(uint32_t frame): _frameNo(frame){}
 101     uint32_t curFrame() const {return _frameNo;}
 102 private:
 103     uint32_t _frameNo;
 104 };
 105
 106 enum class Property {
 107     FillColor,     /*!< Color property of Fill object , value type is rlottie::Color */
 108     FillOpacity,   /*!< Opacity property of Fill object , value type is float [ 0 .. 100] */
 109     StrokeColor,   /*!< Color property of Stroke object , value type is rlottie::Color */
 110     StrokeOpacity, /*!< Opacity property of Stroke object , value type is float [ 0 .. 100] */
 111     StrokeWidth,   /*!< stroke with property of Stroke object , value type is float */
 112     TrAnchor,      /*!< Transform Anchor property of Layer and Group object , value type is rlottie::Point */
 113     TrPosition,    /*!< Transform Position property of Layer and Group object , value type is rlottie::Point */
 114     TrScale,       /*!< Transform Scale property of Layer and Group object , value type is rlottie::Size. range[0 ..100] */
 115     TrRotation,    /*!< Transform Scale property of Layer and Group object , value type is float. range[0 .. 360] in degrees*/
 116     TrOpacity      /*!< Transform Opacity property of Layer and Group object , value type is float [ 0 .. 100] */
 117 };
 118
 119 struct Color_Type{};
 120 struct Point_Type{};
 121 struct Size_Type{};
 122 struct Float_Type{};
 123 template <typename T> struct MapType;
 124
 125 class RLOTTIE_API Surface {
 126 public:
 127     /**
 128      *  @brief Surface object constructor.
 129      *
 130      *  @param[in] buffer surface buffer.
 131      *  @param[in] width  surface width.
 132      *  @param[in] height  surface height.
 133      *  @param[in] bytesPerLine  number of bytes in a surface scanline.
 134      *
 135      *  @note Default surface format is ARGB32_Premultiplied.
 136      *
 137      *  @internal
 138      */
 139     Surface(uint32_t *buffer, size_t width, size_t height, size_t bytesPerLine);
 140
 141     /**
 142      *  @brief Sets the Draw Area available on the Surface.
 143      *
 144      *  Lottie will use the draw region size to generate frame image
 145      *  and will update only the draw rgion of the surface.
 146      *
 147      *  @param[in] x      region area x position.
 148      *  @param[in] y      region area y position.
 149      *  @param[in] width  region area width.
 150      *  @param[in] height region area height.
 151      *
 152      *  @note Default surface format is ARGB32_Premultiplied.
 153      *  @note Default draw region area is [ 0 , 0, surface width , surface height]
 154      *
 155      *  @internal
 156      */
 157     void setDrawRegion(size_t x, size_t y, size_t width, size_t height);
 158
 159     /**
 160      *  @brief Returns width of the surface.
 161      *
 162      *  @return surface width
 163      *
 164      *  @internal
 165      *
 166      */
 167     size_t width() const {return mWidth;}
 168
 169     /**
 170      *  @brief Returns height of the surface.
 171      *
 172      *  @return surface height
 173      *
 174      *  @internal
 175      */
 176     size_t height() const {return mHeight;}
 177
 178     /**
 179      *  @brief Returns number of bytes in the surface scanline.
 180      *
 181      *  @return number of bytes in scanline.
 182      *
 183      *  @internal
 184      */
 185     size_t  bytesPerLine() const {return mBytesPerLine;}
 186
 187     /**
 188      *  @brief Returns buffer attached tp the surface.
 189      *
 190      *  @return buffer attaced to the Surface.
 191      *
 192      *  @internal
 193      */
 194     uint32_t *buffer() const {return mBuffer;}
 195
 196     /**
 197      *  @brief Returns drawable area width of the surface.
 198      *
 199      *  @return drawable area width
 200      *
 201      *  @note Default value is width() of the surface
 202      *
 203      *  @internal
 204      *
 205      */
 206     size_t drawRegionWidth() const {return mDrawArea.w;}
 207
 208     /**
 209      *  @brief Returns drawable area height of the surface.
 210      *
 211      *  @return drawable area height
 212      *
 213      *  @note Default value is height() of the surface
 214      *
 215      *  @internal
 216      */
 217     size_t drawRegionHeight() const {return mDrawArea.h;}
 218
 219     /**
 220      *  @brief Returns drawable area's x position of the surface.
 221      *
 222      *  @return drawable area's x potition.
 223      *
 224      *  @note Default value is 0
 225      *
 226      *  @internal
 227      */
 228     size_t drawRegionPosX() const {return mDrawArea.x;}
 229
 230     /**
 231      *  @brief Returns drawable area's y position of the surface.
 232      *
 233      *  @return drawable area's y potition.
 234      *
 235      *  @note Default value is 0
 236      *
 237      *  @internal
 238      */
 239     size_t drawRegionPosY() const {return mDrawArea.y;}
 240
 241     /**
 242      *  @brief Default constructor.
 243      */
 244     Surface() = default;
 245 private:
 246     uint32_t    *mBuffer{nullptr};
 247     size_t       mWidth{0};
 248     size_t       mHeight{0};
 249     size_t       mBytesPerLine{0};
 250     struct {
 251         size_t   x{0};
 252         size_t   y{0};
 253         size_t   w{0};
 254         size_t   h{0};
 255     }mDrawArea;
 256 };
 257
 258 using MarkerList = std::vector<std::tuple<std::string, int , int>>;
 259 /**
 260  *  @brief https://helpx.adobe.com/after-effects/using/layer-markers-composition-markers.html
 261  *  Markers exported form AE are used to describe a segmnet of an animation {comment/tag , startFrame, endFrame}
 262  *  Marker can be use to devide a resource in to separate animations by tagging the segment with comment string ,
 263  *  start frame and duration of that segment.
 264  */
 265
 266 using LayerInfoList = std::vector<std::tuple<std::string, int , int>>;
 267
 268
 269 using ColorFilter = std::function<void(float &r , float &g, float &b)>;
 270
 271 class RLOTTIE_API Animation {
 272 public:
 273
 274     /**
 275      *  @brief Constructs an animation object from file path.
 276      *
 277      *  @param[in] path Lottie resource file path
 278      *  @param[in] cachePolicy whether to cache or not the model data.
 279      *             use only when need to explicit disabl caching for a
 280      *             particular resource. To disable caching at library level
 281      *             use @see configureModelCacheSize() instead.
 282      *
 283      *  @return Animation object that can render the contents of the
 284      *          Lottie resource represented by file path.
 285      *
 286      *  @internal
 287      */
 288     static std::unique_ptr<Animation>
 289     loadFromFile(const std::string &path, bool cachePolicy=true);
 290
 291     /**
 292      *  @brief Constructs an animation object from JSON string data.
 293      *
 294      *  @param[in] jsonData The JSON string data.
 295      *  @param[in] key the string that will be used to cache the JSON string data.
 296      *  @param[in] resourcePath the path will be used to search for external resource.
 297      *  @param[in] cachePolicy whether to cache or not the model data.
 298      *             use only when need to explicit disabl caching for a
 299      *             particular resource. To disable caching at library level
 300      *             use @see configureModelCacheSize() instead.
 301      *
 302      *  @return Animation object that can render the contents of the
 303      *          Lottie resource represented by JSON string data.
 304      *
 305      *  @internal
 306      */
 307     static std::unique_ptr<Animation>
 308     loadFromData(std::string jsonData, const std::string &key,
 309                  const std::string &resourcePath="", bool cachePolicy=true);
 310
 311     /**
 312      *  @brief Constructs an animation object from JSON string data and update.
 313      *  the color properties using ColorFilter.
 314
 315      *  @param[in] jsonData The JSON string data.
 316      *  @param[in] resourcePath the path will be used to search for external resource.
 317      *  @param[in] filter The color filter that will be applied for each color property
 318      *             found during parsing.
 319
 320      *  @return Animation object that can render the contents of the
 321      *          Lottie resource represented by JSON string data.
 322      *
 323      *  @internal
 324      */
 325     static std::unique_ptr<Animation>
 326     loadFromData(std::string jsonData, std::string resourcePath, ColorFilter filter);
 327
 328     /**
 329      *  @brief Returns default framerate of the Lottie resource.
 330      *
 331      *  @return framerate of the Lottie resource
 332      *
 333      *  @internal
 334      *
 335      */
 336     double frameRate() const;
 337
 338     /**
 339      *  @brief Returns total number of frames present in the Lottie resource.
 340      *
 341      *  @return frame count of the Lottie resource.
 342      *
 343      *  @note frame number starts with 0.
 344      *
 345      *  @internal
 346      */
 347     size_t totalFrame() const;
 348
 349     /**
 350      *  @brief Returns default viewport size of the Lottie resource.
 351      *
 352      *  @param[out] width  default width of the viewport.
 353      *  @param[out] height default height of the viewport.
 354      *
 355      *  @internal
 356      *
 357      */
 358     void   size(size_t &width, size_t &height) const;
 359
 360     /**
 361      *  @brief Returns total animation duration of Lottie resource in second.
 362      *         it uses totalFrame() and frameRate() to calculate the duration.
 363      *         duration = totalFrame() / frameRate().
 364      *
 365      *  @return total animation duration in second.
 366      *  @retval 0 if the Lottie resource has no animation.
 367      *
 368      *  @see totalFrame()
 369      *  @see frameRate()
 370      *
 371      *  @internal
 372      */
 373     double duration() const;
 374
 375     /**
 376      *  @brief Returns frame number for a given position.
 377      *         this function helps to map the position value retuned
 378      *         by the animator to a frame number in side the Lottie resource.
 379      *         frame_number = lerp(start_frame, endframe, pos);
 380      *
 381      *  @param[in] pos normalized position value [0 ... 1]
 382      *
 383      *  @return frame numer maps to the position value [startFrame .... endFrame]
 384      *
 385      *  @internal
 386      */
 387     size_t frameAtPos(double pos);
 388
 389     /**
 390      *  @brief Renders the content to surface Asynchronously.
 391      *         it gives a future in return to get the result of the
 392      *         rendering at a future point.
 393      *         To get best performance user has to start rendering as soon as
 394      *         it finds that content at {frameNo} has to be rendered and get the
 395      *         result from the future at the last moment when the surface is needed
 396      *         to draw into the screen.
 397      *
 398      *
 399      *  @param[in] frameNo Content corresponds to the @p frameNo needs to be drawn
 400      *  @param[in] surface Surface in which content will be drawn
 401      *  @param[in] keepAspectRatio whether to keep the aspect ratio while scaling the content.
 402      *
 403      *  @return future that will hold the result when rendering finished.
 404      *
 405      *  for Synchronus rendering @see renderSync
 406      *
 407      *  @see Surface
 408      *  @internal
 409      */
 410     std::future<Surface> render(size_t frameNo, Surface surface, bool keepAspectRatio=true);
 411
 412     /**
 413      *  @brief Renders the content to surface synchronously.
 414      *         for performance use the async rendering @see render
 415      *
 416      *  @param[in] frameNo Content corresponds to the @p frameNo needs to be drawn
 417      *  @param[in] surface Surface in which content will be drawn
 418      *  @param[in] keepAspectRatio whether to keep the aspect ratio while scaling the content.
 419      *
 420      *  @internal
 421      */
 422     void              renderSync(size_t frameNo, Surface surface, bool keepAspectRatio=true);
 423
 424     /**
 425      *  @brief Returns root layer of the composition updated with
 426      *         content of the Lottie resource at frame number @p frameNo.
 427      *
 428      *  @param[in] frameNo Content corresponds to the @p frameNo needs to be extracted.
 429      *  @param[in] width   content viewbox width
 430      *  @param[in] height  content viewbox height
 431      *
 432      *  @return Root layer node.
 433      *
 434      *  @internal
 435      */
 436     const LOTLayerNode * renderTree(size_t frameNo, size_t width, size_t height) const;
 437
 438     /**
 439      *  @brief Returns Composition Markers.
 440      *
 441      *
 442      *  @return returns MarkerList of the Composition.
 443      *
 444      *  @see MarkerList
 445      *  @internal
 446      */
 447     const MarkerList& markers() const;
 448
 449     /**
 450      *  @brief Returns Layer information{name, inFrame, outFrame} of all the child layers  of the composition.
 451      *
 452      *
 453      *  @return List of Layer Information of the Composition.
 454      *
 455      *  @see LayerInfoList
 456      *  @internal
 457      */
 458     const LayerInfoList& layers() const;
 459
 460     /**
 461      *  @brief Sets property value for the specified {@link KeyPath}. This {@link KeyPath} can resolve
 462      *  to multiple contents. In that case, the callback's value will apply to all of them.
 463      *
 464      *  Keypath should conatin object names separated by (.) and can handle globe(**) or wildchar(*).
 465      *
 466      *  @usage
 467      *  To change fillcolor property of fill1 object in the layer1->group1->fill1 hirarchy to RED color
 468      *
 469      *     player->setValue<rlottie::Property::FillColor>("layer1.group1.fill1", rlottie::Color(1, 0, 0);
 470      *
 471      *  if all the color property inside group1 needs to be changed to GREEN color
 472      *
 473      *     player->setValue<rlottie::Property::FillColor>("**.group1.**", rlottie::Color(0, 1, 0);
 474      *
 475      *  @internal
 476      */
 477     template<Property prop, typename AnyValue>
 478     void setValue(const std::string &keypath, AnyValue value)
 479     {
 480         setValue(MapType<std::integral_constant<Property, prop>>{}, prop, keypath, value);
 481     }
 482
 483     /**
 484      *  @brief default destructor
 485      *
 486      *  @internal
 487      */
 488     ~Animation();
 489
 490 private:
 491     void setValue(Color_Type, Property, const std::string &, Color);
 492     void setValue(Float_Type, Property, const std::string &, float);
 493     void setValue(Size_Type, Property, const std::string &, Size);
 494     void setValue(Point_Type, Property, const std::string &, Point);
 495
 496     void setValue(Color_Type, Property, const std::string &, std::function<Color(const FrameInfo &)> &&);
 497     void setValue(Float_Type, Property, const std::string &, std::function<float(const FrameInfo &)> &&);
 498     void setValue(Size_Type, Property, const std::string &, std::function<Size(const FrameInfo &)> &&);
 499     void setValue(Point_Type, Property, const std::string &, std::function<Point(const FrameInfo &)> &&);
 500     /**
 501      *  @brief default constructor
 502      *
 503      *  @internal
 504      */
 505     Animation();
 506
 507     std::unique_ptr<AnimationImpl> d;
 508 };
 509
 510 //Map Property to Value type
 511 template<> struct MapType<std::integral_constant<Property, Property::FillColor>>: Color_Type{};
 512 template<> struct MapType<std::integral_constant<Property, Property::StrokeColor>>: Color_Type{};
 513 template<> struct MapType<std::integral_constant<Property, Property::FillOpacity>>: Float_Type{};
 514 template<> struct MapType<std::integral_constant<Property, Property::StrokeOpacity>>: Float_Type{};
 515 template<> struct MapType<std::integral_constant<Property, Property::StrokeWidth>>: Float_Type{};
 516 template<> struct MapType<std::integral_constant<Property, Property::TrRotation>>: Float_Type{};
 517 template<> struct MapType<std::integral_constant<Property, Property::TrOpacity>>: Float_Type{};
 518 template<> struct MapType<std::integral_constant<Property, Property::TrAnchor>>: Point_Type{};
 519 template<> struct MapType<std::integral_constant<Property, Property::TrPosition>>: Point_Type{};
 520 template<> struct MapType<std::integral_constant<Property, Property::TrScale>>: Size_Type{};
 521
 522
 523 }  // namespace lotplayer
 524
 525 #endif  // _RLOTTIE_H_