inc/lottieanimation.h

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