common Animation: introduce the Animation class.

This class serves as the base for Animation.
The main purpose of its APIs is to control the animation frames.

Its example will be provided in the upcoming commits.

@APIs:
Result Animation::frame(uint32_t no) noexcept;
Picture* Animation::picture() const noexcept;
uint32_t Animation::curFrame() const noexcept;
uint32_t Animation::totalFrame() const noexcept;
float Animation::duration() const noexcept;
static std::unique_ptr<Animation> Animation::gen() noexcept;

@Issue: https://github.com/thorvg/thorvg/pull/1450

inc/thorvg.h

@@ -1231,10 +1231,11 @@ public:
 /**
  * @class Picture
  *
- * @brief A class representing an image read in one of the supported formats: raw, svg, png, jpg and etc.
+ * @brief A class representing an image read in one of the supported formats: raw, svg, png, jpg, lottie(json) and etc.
  * Besides the methods inherited from the Paint, it provides methods to load & draw images on the canvas.
  *
  * @note Supported formats are depended on the available TVG loaders.
+ * @note See Animation class if the picture data is animatable.
  */
 class TVG_API Picture final : public Paint
 {
@@ -1351,8 +1352,8 @@ public:
      * @param[in] triangles An array of Polygons(triangles) that make up the mesh, or null to remove the mesh.
      * @param[in] triangleCnt The number of Polygons(triangles) provided, or 0 to remove the mesh.
      *
-     * @return Result::Success When succeed.
+     * @retval Result::Success When succeed.
-     * @return Result::Unknown If fails
+     * @retval Result::Unknown If fails
      *
      * @note The Polygons are copied internally, so modifying them after calling Mesh::mesh has no affect.
      * @warning Please do not use it, this API is not official one. It could be modified in the next version.
@@ -1660,6 +1661,101 @@ public:
 };
 
 
+/**
+ * @class Animation
+ *
+ * @brief The Animation class enables manipulation of animatable images.
+ *
+ * This class supports the display and control of animation frames.
+ *
+ * @BETA_API
+ */
+
+class TVG_API Animation
+{
+public:
+    ~Animation();
+
+    /**
+     * @brief Specifies the current frame in the animation.
+     *
+     * @param[in] no The index of the animation frame to be displayed. The index should be less than the totalFrame().
+     *
+     * @retval Result::Success Successfully set the frame.
+     * @retval Result::InsufficientCondition No animatable data loaded from the Picture.
+     * @retval Result::NonSupport The Picture data does not support animations.
+     *
+     * @see totalFrame()
+     *
+     * @BETA_API
+     */
+    Result frame(uint32_t no) noexcept;
+
+    /**
+     * @brief Retrieves a picture instance associated with this animation instance.
+     *
+     * This function provides access to the picture instance that can be used to load animation formats, such as Lottie(json).
+     * After setting up the picture, it can be pushed to the designated canvas, enabling control over animation frames
+     * with this Animation instance.
+     *
+     * @return A picture instance that is tied to this animation.
+     *
+     * @warning The picture instance is owned by Animation. It should not be deleted manually.
+     *
+     * @BETA_API
+     */
+    Picture* picture() const noexcept;
+
+    /**
+     * @brief Retrieves the current frame number of the animation.
+     *
+     * @return The current frame number of the animation, between 0 and totalFrame() - 1.
+     *
+     * @note If the Picture is not properly configured, this function will return 0.
+     *
+     * @see Animation::frame(uint32_t no)
+     * @see Animation::totalFrame()
+     *
+     * @BETA_API
+     */
+    uint32_t curFrame() const noexcept;
+
+    /**
+     * @brief Retrieves the total number of frames in the animation.
+     *
+     * @return The total number of frames in the animation.
+     *
+     * @note Frame numbering starts from 0.
+     * @note If the Picture is not properly configured, this function will return 0.
+     *
+     * @BETA_API
+     */
+    uint32_t totalFrame() const noexcept;
+
+    /**
+     * @brief Retrieves the duration of the animation in seconds.
+     *
+     * @return The duration of the animation in seconds.
+     *
+     * @note If the Picture is not properly configured, this function will return 0.
+     *
+     * @BETA_API
+     */
+    float duration() const noexcept;
+
+    /**
+     * @brief Creates a new Animation object.
+     *
+     * @return A new Animation object.
+     *
+     * @BETA_API
+     */
+    static std::unique_ptr<Animation> gen() noexcept;
+
+    _TVG_DECLARE_PRIVATE(Animation);
+};
+
+
 /**
  * @class Saver
  *

src/lib/meson.build

@@ -27,6 +27,7 @@ source_file = [
    'tvgShapeImpl.h',
    'tvgTaskScheduler.h',
    'tvgAccessor.cpp',
+   'tvgAnimation.cpp',
    'tvgBezier.cpp',
    'tvgCanvas.cpp',
    'tvgFill.cpp',

src/lib/tvgAnimation.cpp

@@ -0,0 +1,108 @@
+/*
+ * Copyright (c) 2023 the ThorVG project. All rights reserved.
+
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+//#include "tvgAnimationImpl.h"
+#include "tvgCommon.h"
+#include "tvgFrameModule.h"
+#include "tvgPictureImpl.h"
+
+/************************************************************************/
+/* Internal Class Implementation                                        */
+/************************************************************************/
+
+struct Animation::Impl
+{
+    //TODO: Memory Safety
+    Picture picture;
+};
+
+/************************************************************************/
+/* External Class Implementation                                        */
+/************************************************************************/
+
+Animation::~Animation()
+{
+
+}
+
+
+Animation::Animation() : pImpl(new Impl)
+{
+    pImpl->picture.pImpl->animated = true;
+}
+
+
+Result Animation::frame(uint32_t no) noexcept
+{
+    auto loader = pImpl->picture.pImpl->loader.get();
+
+    if (!loader) return Result::InsufficientCondition;
+    if (!loader->animatable()) return Result::NonSupport;
+
+    if (static_cast<FrameModule*>(loader)->frame(no)) return Result::Success;
+    return Result::InsufficientCondition;
+}
+
+
+Picture* Animation::picture() const noexcept
+{
+    return &pImpl->picture;
+}
+
+
+uint32_t Animation::curFrame() const noexcept
+{
+    auto loader = pImpl->picture.pImpl->loader.get();
+
+    if (!loader) return 0;
+    if (!loader->animatable()) return 0;
+
+    return static_cast<FrameModule*>(loader)->curFrame();
+}
+
+
+uint32_t Animation::totalFrame() const noexcept
+{
+    auto loader = pImpl->picture.pImpl->loader.get();
+
+    if (!loader) return 0;
+    if (!loader->animatable()) return 0;
+
+    return static_cast<FrameModule*>(loader)->totalFrame();
+}
+
+
+float Animation::duration() const noexcept
+{
+    auto loader = pImpl->picture.pImpl->loader.get();
+
+    if (!loader) return 0;
+    if (!loader->animatable()) return 0;
+
+    return static_cast<FrameModule*>(loader)->duration();
+}
+
+
+unique_ptr<Animation> Animation::gen() noexcept
+{
+    return unique_ptr<Animation>(new Animation);
+}

src/lib/tvgPictureImpl.h

@@ -70,6 +70,7 @@ struct Picture::Impl
     Picture* picture = nullptr;
     bool resizing = false;
     bool needComp = false;            //need composition
+    bool animated = false;            //picture is belonged to Animation
 
     Impl(Picture* p) : picture(p)
     {