From 033801ec3ed520f1cb6aabcf78b8d344a7385df2 Mon Sep 17 00:00:00 2001 From: Hermet Park Date: Thu, 13 Dec 2018 14:44:58 +0900 Subject: [PATCH 1/1] updated doc. Change-Id: I712379928026a2101fdada48d7482ef6926a1040 --- inc/lottieanimation.h | 36 +++---- inc/lottieanimation_capi.h | 170 +++++++++++++++++++++++++++------ inc/lottiecommon.h | 22 +++++ src/binding/c/lottieanimation_capi.cpp | 18 ++-- 4 files changed, 191 insertions(+), 55 deletions(-) diff --git a/inc/lottieanimation.h b/inc/lottieanimation.h index e115ebf..4586ac8 100644 --- 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 --- 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 --- 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 --- 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 -- 2.7.4