inc/lottieanimation.h

   1 /*
   2  * Copyright (c) 2018 Samsung Electronics Co., Ltd. All rights reserved.
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  17  */
  18
  19 #ifndef _LOTTIE_ANIMATION_H_
  20 #define _LOTTIE_ANIMATION_H_
  21
  22 #include <future>
  23 #include <vector>
  24 #include <memory>
  25
  26 #ifdef _WIN32
  27 #ifdef LOT_BUILD
  28 #ifdef DLL_EXPORT
  29 #define LOT_EXPORT __declspec(dllexport)
  30 #else
  31 #define LOT_EXPORT
  32 #endif
  33 #else
  34 #define LOT_EXPORT __declspec(dllimport)
  35 #endif
  36 #else
  37 #ifdef __GNUC__
  38 #if __GNUC__ >= 4
  39 #define LOT_EXPORT __attribute__((visibility("default")))
  40 #else
  41 #define LOT_EXPORT
  42 #endif
  43 #else
  44 #define LOT_EXPORT
  45 #endif
  46 #endif
  47
  48 class AnimationImpl;
  49 struct LOTNode;
  50 struct LOTLayerNode;
  51
  52 namespace lottie {
  53
  54 class LOT_EXPORT Surface {
  55 public:
  56     /**
  57      *  @brief Surface object constructor.
  58      *
  59      *  @param[in] buffer surface buffer.
  60      *  @param[in] width  surface width.
  61      *  @param[in] height  surface height.
  62      *  @param[in] bytesPerLine  number of bytes in a surface scanline.
  63      *
  64      *  @note Default surface format is ARGB32_Premultiplied.
  65      *
  66      *  @internal
  67      */
  68     Surface(uint32_t *buffer, size_t width, size_t height, size_t bytesPerLine);
  69
  70     /**
  71      *  @brief Returns width of the surface.
  72      *
  73      *  @return surface width
  74      *
  75      *  @internal
  76      *
  77      */
  78     size_t width() const {return mWidth;}
  79
  80     /**
  81      *  @brief Returns height of the surface.
  82      *
  83      *  @return surface height
  84      *
  85      *  @internal
  86      */
  87     size_t height() const {return mHeight;}
  88
  89     /**
  90      *  @brief Returns number of bytes in the surface scanline.
  91      *
  92      *  @return number of bytes in scanline.
  93      *
  94      *  @internal
  95      */
  96     size_t  bytesPerLine() const {return mBytesPerLine;}
  97
  98     /**
  99      *  @brief Returns buffer attached tp the surface.
 100      *
 101      *  @return buffer attaced to the Surface.
 102      *
 103      *  @internal
 104      */
 105     uint32_t *buffer() const {return mBuffer;}
 106
 107     /**
 108      *  @brief Default constructor.
 109      */
 110     Surface() = default;
 111 private:
 112     uint32_t    *mBuffer{nullptr};
 113     size_t       mWidth{0};
 114     size_t       mHeight{0};
 115     size_t       mBytesPerLine{0};
 116 };
 117
 118 class LOT_EXPORT Animation {
 119 public:
 120
 121     /**
 122      *  @brief Constructs an animation object from file path.
 123      *
 124      *  @param[in] path Lottie resource file path
 125      *
 126      *  @return Animation object that can render the contents of the
 127      *          Lottie resource represented by file path.
 128      *
 129      *  @internal
 130      */
 131     static std::unique_ptr<Animation>
 132     loadFromFile(const std::string &path);
 133
 134     /**
 135      *  @brief Constructs an animation object from JSON string data.
 136      *
 137      *  @param[in] jsonData The JSON string data.
 138      *  @param[in] key the string that will be used to cache the JSON string data.
 139      *
 140      *  @return Animation object that can render the contents of the
 141      *          Lottie resource represented by JSON string data.
 142      *
 143      *  @internal
 144      */
 145     static std::unique_ptr<Animation>
 146     loadFromData(std::string jsonData, const std::string &key);
 147
 148     /**
 149      *  @brief Returns default framerate of the Lottie resource.
 150      *
 151      *  @return framerate of the Lottie resource
 152      *
 153      *  @internal
 154      *
 155      */
 156     double frameRate() const;
 157
 158     /**
 159      *  @brief Returns total number of frames present in the Lottie resource.
 160      *
 161      *  @return frame count of the Lottie resource.
 162      *
 163      *  @note frame number starts with 0.
 164      *
 165      *  @internal
 166      */
 167     size_t totalFrame() const;
 168
 169     /**
 170      *  @brief Returns default viewport size of the Lottie resource.
 171      *
 172      *  @param[out] width  default width of the viewport.
 173      *  @param[out] height default height of the viewport.
 174      *
 175      *  @internal
 176      *
 177      */
 178     void   size(size_t &width, size_t &height) const;
 179
 180     /**
 181      *  @brief Returns total animation duration of Lottie resource in second.
 182      *         it uses totalFrame() and frameRate() to calculate the duration.
 183      *         duration = totalFrame() / frameRate().
 184      *
 185      *  @return total animation duration in second.
 186      *  @retval 0 if the Lottie resource has no animation.
 187      *
 188      *  @see totalFrame()
 189      *  @see frameRate()
 190      *
 191      *  @internal
 192      */
 193     double duration() const;
 194
 195     /**
 196      *  @brief Returns frame number for a given position.
 197      *         this function helps to map the position value retuned
 198      *         by the animator to a frame number in side the Lottie resource.
 199      *         frame_number = lerp(start_frame, endframe, pos);
 200      *
 201      *  @param[in] pos normalized position value [0 ... 1]
 202      *
 203      *  @return frame numer maps to the position value [startFrame .... endFrame]
 204      *
 205      *  @internal
 206      */
 207     size_t frameAtPos(double pos);
 208
 209     /**
 210      *  @brief Renders the content to surface Asynchronously.
 211      *         it gives a future in return to get the result of the
 212      *         rendering at a future point.
 213      *         To get best performance user has to start rendering as soon as
 214      *         it finds that content at {frameNo} has to be rendered and get the
 215      *         result from the future at the last moment when the surface is needed
 216      *         to draw into the screen.
 217      *
 218      *
 219      *  @param[in] frameNo Content corresponds to the @p frameNo needs to be drawn
 220      *  @param[in] surface Surface in which content will be drawn
 221      *
 222      *  @return future that will hold the result when rendering finished.
 223      *
 224      *  for Synchronus rendering @see renderSync
 225      *
 226      *  @see Surface
 227      *  @internal
 228      */
 229     std::future<Surface> render(size_t frameNo, Surface surface);
 230
 231     /**
 232      *  @brief Renders the content to surface synchronously.
 233      *         for performance use the async rendering @see render
 234      *
 235      *  @param[in] frameNo Content corresponds to the @p frameNo needs to be drawn
 236      *  @param[in] surface Surface in which content will be drawn
 237      *
 238      *  @internal
 239      */
 240     void              renderSync(size_t frameNo, Surface surface);
 241
 242     /**
 243      *  @brief Returns root layer of the composition updated with
 244      *         content of the Lottie resource at frame number @p frameNo.
 245      *
 246      *  @param[in] frameNo Content corresponds to the @p frameNo needs to be extracted.
 247      *  @param[in] width   content viewbox width
 248      *  @param[in] height  content viewbox height
 249      *
 250      *  @return Root layer node.
 251      *
 252      *  @internal
 253      */
 254     const LOTLayerNode * renderTree(size_t frameNo, size_t width, size_t height) const;
 255
 256     /**
 257      *  @brief default destructor
 258      *
 259      *  @internal
 260      */
 261     ~Animation();
 262
 263 private:
 264     /**
 265      *  @brief default constructor
 266      *
 267      *  @internal
 268      */
 269     Animation();
 270
 271     std::unique_ptr<AnimationImpl> d;
 272 };
 273
 274 }  // namespace lotplayer
 275
 276 #endif  // _LOTTIE_ANIMATION_H_