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     Surface(uint32_t *buffer, size_t width, size_t height, size_t bytesPerLine);
  49
  50     /**
  51      *  @brief Returns width of the surface.
  52      *
  53      *  @return surface width
  54      */
  55     size_t width() const {return mWidth;}
  56
  57     /**
  58      *  @brief Returns height of the surface.
  59      *
  60      *  @return surface height
  61      */
  62     size_t height() const {return mHeight;}
  63
  64     /**
  65      *  @brief Returns number of bytes in the surface scanline.
  66      *
  67      *  @return number of bytes in scanline.
  68      */
  69     size_t  bytesPerLine() const {return mBytesPerLine;}
  70
  71     /**
  72      *  @brief Returns buffer attached tp the surface.
  73      *
  74      *  @return buffer attaced to the Surface.
  75      */
  76     uint32_t *buffer() const {return mBuffer;}
  77
  78     /**
  79      *  @brief Default constructor.
  80      */
  81     Surface() = default;
  82 private:
  83     uint32_t    *mBuffer;
  84     size_t       mWidth;
  85     size_t       mHeight;
  86     size_t       mBytesPerLine;
  87 };
  88
  89 class LOT_EXPORT Animation {
  90 public:
  91
  92     /**
  93      *  @brief Constructs an animation object from filepath.
  94      *
  95      *  @param[in] path Lottie resource file path
  96      *
  97      *  @return Animation object that can render the contents of the
  98      *          lottie resource represented by file path.
  99      */
 100     static std::unique_ptr<Animation>
 101     loadFromFile(const std::string &path);
 102
 103     /**
 104      *  @brief Constructs an animation object from json string data.
 105      *
 106      *  @param[in] jsonData The JSON string data.
 107      *  @param[in] key the string that will be used to cache the JSON string data.
 108      *
 109      *  @return Animation object that can render the contents of the
 110      *          lottie resource represented by JSON string data.
 111      */
 112     static std::unique_ptr<Animation>
 113     loadFromData(std::string jsonData, const std::string &key);
 114
 115     /**
 116      *  @brief Returns default framerate of the lottie resource.
 117      *
 118      *  @return framerate of the lottie resource
 119      *
 120      */
 121     double frameRate() const;
 122
 123     /**
 124      *  @brief Returns total number of frames present in the  lottie resource.
 125      *
 126      *  @return frame count of the lottie resource.
 127      *
 128      *  @note frame number starts with 0.
 129      */
 130     size_t totalFrame() const;
 131
 132     /**
 133      *  @brief Returns default viewport size of the lottie resource.
 134      *
 135      *  @param[out] width  default width of the viewport.
 136      *  @param[out] height default height of the viewport.
 137      *
 138      */
 139     void   size(size_t &width, size_t &height) const;
 140
 141     /**
 142      *  @brief Returns total animation duration of lottie resource in second.
 143      *         it uses totalFrame() and frameRate() to calcualte the duration.
 144      *         duration = totalFrame() / frameRate().
 145      *
 146      *  @return total animation duration in second.
 147      *  @retval 0 if the lottie resource has no animation.
 148      *
 149      *  @see totalFrame()
 150      *  @see frameRate()
 151      */
 152     double duration() const;
 153
 154     /**
 155      *  @brief Returns frame number for a given position.
 156      *         this function helps to map the position value retuned
 157      *         by the animator to a frame number in side the lottie resource.
 158      *         frame_number = lerp(start_frame, endframe, pos);
 159      *
 160      *  @param[in] pos normalized position value [0 ... 1]
 161      *
 162      *  @return frame numer maps to the position value [startFrame .... endFrame]
 163      *
 164      */
 165     size_t frameAtPos(double pos);
 166
 167     /**
 168      *  @brief Renders the content to surface Asynchronously.
 169      *         it gives a future in return to get the result of the
 170      *         rendering at a future point.
 171      *         To get best performance user has to start rendering as soon as
 172      *         it finds that content at {frameNo} has to be rendered and get the
 173      *         result from the future at the last moment when the surface is needed
 174      *         to draw into the screen.
 175      *
 176      *
 177      *  @param[in] frameNo Content corresponds to the frameno needs to be drawn
 178      *  @param[in] surface Surface in which content will be drawn
 179      *
 180      *  @return future that will hold the result when rendering finished.
 181      *
 182      *  for Synchronus rendering @see renderSync
 183      *  @see Surface
 184      */
 185     std::future<Surface> render(size_t frameNo, Surface surface);
 186
 187     /**
 188      *  @brief Renders the content to surface synchronously.
 189      *         for performance use the asyn rendering @see render
 190      *
 191      *  @param[in] frameNo Content corresponds to the frameno needs to be drawn
 192      *  @param[in] surface Surface in which content will be drawn
 193      */
 194     void              renderSync(size_t frameNo, Surface surface);
 195
 196     /**
 197      *  @brief Returns list of rendering nodes that that represents the
 198      *         content of the lottie resource at frame number {frameNo}.
 199      *
 200      *  @param[in] frameNo Content corresponds to the frameno needs to be extracted.
 201      *  @param[in] width   content viewbox width
 202      *  @param[in] height  content viewbox height
 203      *
 204      *  @return render node list.
 205      */
 206     const std::vector<LOTNode *> &renderList(size_t frameNo, size_t width, size_t height) const;
 207
 208     /**
 209      *  @brief Returns root layer of the composition updated with
 210      *         content of the lottie resource at frame number {frameNo}.
 211      *
 212      *  @param[in] frameNo Content corresponds to the frameno needs to be extracted.
 213      *  @param[in] width   content viewbox width
 214      *  @param[in] height  content viewbox height
 215      *
 216      *  @return Root layer node.
 217      */
 218     const LOTLayerNode * renderTree(size_t frameNo, size_t width, size_t height) const;
 219
 220     /**
 221      *  @brief default destructor
 222      */
 223     ~Animation();
 224
 225 private:
 226     /**
 227      *  @brief default constructor
 228      */
 229     Animation();
 230
 231     std::unique_ptr<AnimationImpl> d;
 232 };
 233
 234 }  // namespace lotplayer
 235
 236 #endif  // _LOTTIE_ANIMATION_H_