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