updated doc.

Change-Id: I712379928026a2101fdada48d7482ef6926a1040

diff --git a/inc/lottieanimation.h b/inc/lottieanimation.h
index e115ebf..4586ac8 100644 (file)
--- a/inc/lottieanimation.h
+++ b/inc/lottieanimation.h
@@ -101,12 +101,12 @@ class LOT_EXPORT Animation {
 public:
 
     /**
-     *  @brief Constructs an animation object from filepath.
+     *  @brief Constructs an animation object from file path.
      *
      *  @param[in] path Lottie resource file path
      *
      *  @return Animation object that can render the contents of the
-     *          lottie resource represented by file path.
+     *          Lottie resource represented by file path.
      *
      *  @internal
      */
@@ -114,13 +114,13 @@ public:
     loadFromFile(const std::string &path);
 
     /**
-     *  @brief Constructs an animation object from json string data.
+     *  @brief Constructs an animation object from JSON string data.
      *
      *  @param[in] jsonData The JSON string data.
      *  @param[in] key the string that will be used to cache the JSON string data.
      *
      *  @return Animation object that can render the contents of the
-     *          lottie resource represented by JSON string data.
+     *          Lottie resource represented by JSON string data.
      *
      *  @internal
      */
@@ -128,9 +128,9 @@ public:
     loadFromData(std::string jsonData, const std::string &key);
 
     /**
-     *  @brief Returns default framerate of the lottie resource.
+     *  @brief Returns default framerate of the Lottie resource.
      *
-     *  @return framerate of the lottie resource
+     *  @return framerate of the Lottie resource
      *
      *  @internal
      *
@@ -138,9 +138,9 @@ public:
     double frameRate() const;
 
     /**
-     *  @brief Returns total number of frames present in the  lottie resource.
+     *  @brief Returns total number of frames present in the Lottie resource.
      *
-     *  @return frame count of the lottie resource.
+     *  @return frame count of the Lottie resource.
      *
      *  @note frame number starts with 0.
      *
@@ -149,7 +149,7 @@ public:
     size_t totalFrame() const;
 
     /**
-     *  @brief Returns default viewport size of the lottie resource.
+     *  @brief Returns default viewport size of the Lottie resource.
      *
      *  @param[out] width  default width of the viewport.
      *  @param[out] height default height of the viewport.
@@ -160,12 +160,12 @@ public:
     void   size(size_t &width, size_t &height) const;
 
     /**
-     *  @brief Returns total animation duration of lottie resource in second.
-     *         it uses totalFrame() and frameRate() to calcualte the duration.
+     *  @brief Returns total animation duration of Lottie resource in second.
+     *         it uses totalFrame() and frameRate() to calculate the duration.
      *         duration = totalFrame() / frameRate().
      *
      *  @return total animation duration in second.
-     *  @retval 0 if the lottie resource has no animation.
+     *  @retval 0 if the Lottie resource has no animation.
      *
      *  @see totalFrame()
      *  @see frameRate()
@@ -177,7 +177,7 @@ public:
     /**
      *  @brief Returns frame number for a given position.
      *         this function helps to map the position value retuned
-     *         by the animator to a frame number in side the lottie resource.
+     *         by the animator to a frame number in side the Lottie resource.
      *         frame_number = lerp(start_frame, endframe, pos);
      *
      *  @param[in] pos normalized position value [0 ... 1]
@@ -198,7 +198,7 @@ public:
      *         to draw into the screen.
      *
      *
-     *  @param[in] frameNo Content corresponds to the frameno needs to be drawn
+     *  @param[in] frameNo Content corresponds to the @p frameNo needs to be drawn
      *  @param[in] surface Surface in which content will be drawn
      *
      *  @return future that will hold the result when rendering finished.
@@ -212,9 +212,9 @@ public:
 
     /**
      *  @brief Renders the content to surface synchronously.
-     *         for performance use the asyn rendering @see render
+     *         for performance use the async rendering @see render
      *
-     *  @param[in] frameNo Content corresponds to the frameno needs to be drawn
+     *  @param[in] frameNo Content corresponds to the @p frameNo needs to be drawn
      *  @param[in] surface Surface in which content will be drawn
      *
      *  @internal
@@ -223,9 +223,9 @@ public:
 
     /**
      *  @brief Returns root layer of the composition updated with
-     *         content of the lottie resource at frame number {frameNo}.
+     *         content of the Lottie resource at frame number @p frameNo.
      *
-     *  @param[in] frameNo Content corresponds to the frameno needs to be extracted.
+     *  @param[in] frameNo Content corresponds to the @p frameNo needs to be extracted.
      *  @param[in] width   content viewbox width
      *  @param[in] height  content viewbox height
      *

diff --git a/inc/lottieanimation_capi.h b/inc/lottieanimation_capi.h
index d1c27eb..6b5bd66 100644 (file)
--- a/inc/lottieanimation_capi.h
+++ b/inc/lottieanimation_capi.h
@@ -12,51 +12,165 @@ extern "C" {
 
 typedef struct Lottie_Animation_S Lottie_Animation;
 
-LOT_EXPORT Lottie_Animation *lottie_animation_from_file(const char *file);
+/**
+ *  @brief Constructs an animation object from file path.
+ *
+ *  @param[in] path Lottie resource file path
+ *
+ *  @return Animation object that can build the contents of the
+ *          Lottie resource represented by file path.
+ *
+ *  @see lottie_animation_destroy()
+ *
+ *  @ingroup Lottie_Animation
+ *  @internal
+ */
+LOT_EXPORT Lottie_Animation *lottie_animation_from_file(const char *path);
+
+/**
+ *  @brief Constructs an animation object from JSON string data.
+ *
+ *  @param[in] data The JSON string data.
+ *  @param[in] key the string that will be used to cache the JSON string data.
+ *
+ *  @return Animation object that can build the contents of the
+ *          Lottie resource represented by JSON string data.
+ *
+ *  @ingroup Lottie_Animation
+ *  @internal
+ */
 LOT_EXPORT Lottie_Animation *lottie_animation_from_data(const char *data, const char *key);
+
+/**
+ *  @brief Free given Animation object resource.
+ *
+ *  @param[in] animation Animation object to free.
+ *
+ *  @see lottie_animation_from_file()
+ *  @see lottie_animation_from_data()
+ *
+ *  @ingroup Lottie_Animation
+ *  @internal
+ */
 LOT_EXPORT void lottie_animation_destroy(Lottie_Animation *animation);
-LOT_EXPORT void lottie_animation_get_size(const Lottie_Animation *animation, size_t *w, size_t *h);
+
+/**
+ *  @brief Returns default viewport size of the Lottie resource.
+ *
+ *  @param[in] animation Animation object.
+ *  @param[out] w default width of the viewport.
+ *  @param[out] h default height of the viewport.
+ *
+ *  @ingroup Lottie_Animation
+ *  @internal
+ */
+LOT_EXPORT void lottie_animation_get_size(const Lottie_Animation *animation, size_t *width, size_t *height);
+
+/**
+ *  @brief Returns total animation duration of Lottie resource in second.
+ *         it uses totalFrame() and frameRate() to calculate the duration.
+ *         duration = totalFrame() / frameRate().
+ *
+ *  @param[in] animation Animation object.
+ *
+ *  @return total animation duration in second.
+ *          @c 0 if the Lottie resource has no animation.
+ *
+ *  @see lottie_animation_get_totalframe()
+ *  @see lottie_animation_get_framerate()
+ *
+ *  @ingroup Lottie_Animation
+ *  @internal
+ */
 LOT_EXPORT double lottie_animation_get_duration(const Lottie_Animation *animation);
+
+/**
+ *  @brief Returns total number of frames present in the Lottie resource.
+ *
+ *  @param[in] animation Animation object.
+ *
+ *  @return frame count of the Lottie resource.*
+ *
+ *  @note frame number starts with 0.
+ *
+ *  @see lottie_animation_get_duration()
+ *  @see lottie_animation_get_framerate()
+ *
+ *  @ingroup Lottie_Animation
+ *  @internal
+ */
 LOT_EXPORT size_t lottie_animation_get_totalframe(const Lottie_Animation *animation);
+
+/**
+ *  @brief Returns default framerate of the Lottie resource.
+ *
+ *  @param[in] animation Animation object.
+ *
+ *  @return framerate of the Lottie resource
+ *
+ *  @ingroup Lottie_Animation
+ *  @internal
+ *
+ */
 LOT_EXPORT double lottie_animation_get_framerate(const Lottie_Animation *animation);
 
-/*
- * Get the render tree which contains the snapshot of the animation object at frame $frame_number
- * frame_number, the content of the animation in that frame number
- * width  , width of the viewbox
- * height , height of the viewbox
+/**
+ *  @brief Get the render tree which contains the snapshot of the animation object
+ *         at frame = @c frame_num, the content of the animation in that frame number.
  *
- * PS : user has to traverse the tree for rendering. @see LOTLayerNode and @see LOTNode
+ *  @param[in] animation Animation object.
+ *  @param[in] width requested snapshot viewport width.
+ *  @param[in] height requested snapshot viewport height.
+ *
+ *  @return Animation snapshot tree.
+ *
+ * @note: User has to traverse the tree for rendering.
+ *
+ * @see LOTLayerNode
+ * @see LOTNode
+ *
+ *  @ingroup Lottie_Animation
+ *  @internal
  */
 LOT_EXPORT const LOTLayerNode * lottie_animation_render_tree(Lottie_Animation *animation,
-                                                             size_t frameNo,
-                                                             size_t w, size_t h);
-
-/*
- * Request to render the content of the frame $frame_number to buffer $buffer asynchronously.
- * frame_number, the frame number needs to be rendered.
- * buffer , surface buffer use for rendering
- * width  , width of the surface
- * height , height of the surface
- * bytes_per_line, stride of the surface in bytes.
- *
- * PS : user must call lottie_animation_render_flush to make sure render is finished.
+                                                             size_t frame_num,
+                                                             size_t width, size_t height);
+
+/**
+ *  @brief Request to render the content of the frame @p frame_num to buffer @p buffer asynchronously.
+ *
+ *  @param[in] animation Animation object.
+ *  @param[in] frame_num the frame number needs to be rendered.
+ *  @param[in] buffer surface buffer use for rendering.
+ *  @param[in] width width of the surface
+ *  @param[in] height height of the surface
+ *  @param[in] bytes_per_line stride of the surface in bytes.
+ *
+ *  @note user must call lottie_animation_render_flush() to make sure render is finished.
+ *
+ *  @ingroup Lottie_Animation
+ *  @internal
  */
 LOT_EXPORT void
 lottie_animation_render_async(Lottie_Animation *animation,
-                              size_t frame_number,
+                              size_t frame_num,
                               uint32_t *buffer,
                               size_t width,
                               size_t height,
                               size_t bytes_per_line);
 
-
-/*
- * Request to finish the current asyn renderer job for this animation object.
- * if render is finished then this call returns immidiately
- * if not it waits till render job finish and then return.
- * user must use lottie_animation_render_async and lottie_animation_render_flush
- * together to get the benefit of async rendering.
+/**
+ *  @brief Request to finish the current async renderer job for this animation object.
+ *  If render is finished then this call returns immidiately.
+ *  If not, it waits till render job finish and then return.
+ *
+ *  @param[in] animation Animation object.
+ *
+ *  @warning User must call lottie_animation_render_async() and lottie_animation_render_flush()
+ *  in pair to get the benefit of async rendering.
+ *
+ *  @ingroup Lottie_Animation
+ *  @internal
  */
 LOT_EXPORT void
 lottie_animation_render_flush(Lottie_Animation *animation);

diff --git a/inc/lottiecommon.h b/inc/lottiecommon.h
index 0e89e01..2cd7f6a 100644 (file)
--- a/inc/lottiecommon.h
+++ b/inc/lottiecommon.h
@@ -25,6 +25,25 @@
 
 
 /**
+ * @defgroup Lottie_Animation Lottie_Animation
+ *
+ * Lottie Animation is a modern style vector based animation design. Its animation
+ * resource(within json format) could be generated by Adobe After Effect using
+ * bodymovin plugin. You can find a good examples in Lottie Community which
+ * shares many free resources(see: www.lottiefiles.com).
+ *
+ * This Lottie_Animation is a common engine to manipulate, control Lottie
+ * Animation from the Lottie resource - json file. It provides a scene-graph
+ * node tree per frames by user demand as well as rasterized frame images.
+ *
+ */
+
+/**
+ * @ingroup Lottie_Animation
+ */
+
+
+/**
  * @brief Enumeration for Lottie Player error code.
  */
 typedef enum
@@ -172,5 +191,8 @@ typedef struct LOTLayerNode {
 
 } LOTLayerNode;
 
+/**
+ * @}
+ */
 
 #endif  // _LOTTIE_COMMON_H_

diff --git a/src/binding/c/lottieanimation_capi.cpp b/src/binding/c/lottieanimation_capi.cpp
index 6c287b8..4152804 100644 (file)
--- a/src/binding/c/lottieanimation_capi.cpp
+++ b/src/binding/c/lottieanimation_capi.cpp
@@ -16,9 +16,9 @@ struct Lottie_Animation_S
     size_t                     mHeight{0};
 };
 
-LOT_EXPORT Lottie_Animation_S *lottie_animation_from_file(const char *file)
+LOT_EXPORT Lottie_Animation_S *lottie_animation_from_file(const char *path)
 {
-    if (auto animation = Animation::loadFromFile(file) ) {
+    if (auto animation = Animation::loadFromFile(path) ) {
         Lottie_Animation_S *handle = new Lottie_Animation_S();
         handle->mAnimation = std::move(animation);
         return handle;
@@ -44,11 +44,11 @@ LOT_EXPORT void lottie_animation_destroy(Lottie_Animation_S *animation)
         delete animation;
 }
 
-LOT_EXPORT void lottie_animation_get_size(const Lottie_Animation_S *animation, size_t *w, size_t *h)
+LOT_EXPORT void lottie_animation_get_size(const Lottie_Animation_S *animation, size_t *width, size_t *height)
 {
    if (!animation) return;
 
-   animation->mAnimation->size(*w, *h);
+   animation->mAnimation->size(*width, *height);
 }
 
 LOT_EXPORT double lottie_animation_get_duration(const Lottie_Animation_S *animation)
@@ -73,14 +73,14 @@ LOT_EXPORT double lottie_animation_get_framerate(const Lottie_Animation_S *anima
    return animation->mAnimation->frameRate();
 }
 
-LOT_EXPORT const LOTLayerNode * lottie_animation_render_tree(Lottie_Animation_S *animation, size_t frameNo, size_t w, size_t h)
+LOT_EXPORT const LOTLayerNode * lottie_animation_render_tree(Lottie_Animation_S *animation, size_t frame_num, size_t width, size_t height)
 {
     if (!animation) return nullptr;
 
-    animation->mFrameNo = frameNo;
-    animation->mWidth = w;
-    animation->mHeight = h;
-    return animation->mAnimation->renderTree(frameNo, w, h);
+    animation->mFrameNo = frame_num;
+    animation->mWidth = width;
+    animation->mHeight = height;
+    return animation->mAnimation->renderTree(frame_num, width, height);
 }
 
 LOT_EXPORT void