inc/lottieanimation.h

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