DOCSEARCHbyAlgolia
Submit Docs

rlottie Documentation

repository·master·Indexed 23 days ago

https://github.com/samsung/rlottie

A platform-independent C++ library for real-time rendering of vector-based animations exported in the Bodymovin JSON format. It provides features for loading animations from files or raw data, synchronous and asynchronous rendering into rlottie::Surface, and dynamic runtime modification of properties via keypaths. The library includes a lottie2gif utility and supports build systems such as Meson and CMake.

Tokens
2.7K
Snippets
7
Records
16
Agent score
80%

What's inside rlottie

  1. Update animation properties dynamically

    master

    rlottie allows you to modify animation properties (like colors or opacity) at runtime using setValue<rlottie::Property>(). This is useful for theming or responding to events.

    To use setValue, you need:

    1. KeyPath: A string representing the hierarchy of the object (e.g., "Layer1.Box 1.Fill1"). Supports wildcards:
      • *: Matches any single content name in that position.
      • **: Globstar that matches zero or more layers.
    2. Property: An element from the rlottie::Property enum (e.g., FillColor, StrokeOpacity).
    3. Value: A constant value (like rlottie::Color) or a callback function that accepts rlottie::FrameInfo to return a value that changes per frame.
    // Set a constant color for all layers using a globstar
animation->setValue<rlottie::Property::FillColor>("**", rlottie::Color(0, 1, 0));

// Set a color that changes based on the current frame
animation->setValue<rlottie::Property::FillColor>("Layer1.Box 1.Fill1",
    [](const rlottie::FrameInfo& info) {
         if (info.curFrame() < 15 )
             return rlottie::Color(0, 1, 0);
         else {
             return rlottie::Color(1, 0, 0);
         }
     });

  3. Build and run rlottie tests

    master

    To build and execute the test suite using Meson:

    1. Enable tests during configuration:
    meson configure -Dtest=true
    1. Build the test suite:
    ninja
    1. Run the tests:
    ninja test
    meson configure -Dtest=true
ninja
ninja test

  4. Build rlottie using CMake

    master

    To build rlottie with CMake, follow these steps:

    1. Create a build directory:
    mkdir build
cd build
    1. Configure the project:
    cmake ..

    Custom Configuration Options:

    • Install to a specific path: Use -DCMAKE_INSTALL_PREFIX.
    • Static build: Use -DBUILD_SHARED_LIBS=OFF.
    1. Compile and install:
    make -j 2
make install

  5. Understand the Object hierarchy in the renderer

    master

    The rlottie::renderer uses an Object hierarchy to represent the various components of a Lottie shape (like paths, fills, and strokes):

    • Object: The base class for all renderable elements. It defines the update lifecycle and renderList interface.
    • Group: A container object that holds multiple Object children and applies a transformation matrix to them.
    • Shape: Represents geometric paths (e.g., Rect, Ellipse, Path, Polystar). Shapes are updated based on frame numbers and can be marked as 'dirty' if their geometry changes.
    • Paint: Defines how shapes are visually styled. Subclasses include Fill, GradientFill, Stroke, and GradientStroke.
    • Trim: An object that modifies how paths are rendered (e.g., for 'trim paths' animations).

  6. How Composition and Layers work in rlottie

    master

    The rendering process in rlottie is organized into a hierarchy of Composition and Layer objects.

    • Composition: The top-level container that manages the entire animation. It holds the model::Composition (the parsed Lottie data), manages a SurfaceCache for performance, and provides the primary render method to draw the animation onto a rlottie::Surface.
    • Layer: Represents a single layer within the composition. Layers can be of different types (e.g., CompLayer, SolidLayer, ShapeLayer, ImageLayer, NullLayer) and form a tree structure. Each layer handles its own transformation matrix, opacity, and visibility.

    To render an animation, you typically interact with the Composition object, which orchestrates the update and rendering of its internal layer tree.

  8. Render Lottie animation frames

    master

    Rendering is performed into an rlottie::Surface object, which wraps a memory buffer. You can render frames either synchronously or asynchronously.

    Synchronous Rendering: Blocks until the frame is rendered immediately into the surface.

    Asynchronous Rendering: Returns a std::future<rlottie::Surface> that allows you to continue other work while the frame is being processed.

    // Synchronous
rlottie::Surface surface(buffer, width , height , stride);
animation->renderSync(frameNo, surface);

// Asynchronous
rlottie::Surface surface(buffer, width , height , stride);
std::future<rlottie::Surface> handle = animation->render(frameNo, surface);
// ...
rlottie::Surface surface = handle.get();

  9. Query animation properties

    master

    You can retrieve metadata about a loaded animation using the following methods:

    • frameRate(): Returns the frame rate as a double.
    • totalFrame(): Returns the total number of frames as a size_t.
    • duration(): Returns the total animation duration in seconds as a double.
    double frameRate = animation->frameRate();
size_t totalFrame = animation->totalFrame();
double duration = animation->duration();

  10. Load Lottie animations

    master

    rlottie provides two primary ways to load animations:

    1. From a file: Use rlottie::Animation::loadFromFile with the absolute path to the JSON file.
    2. From raw data: Use rlottie::Animation::loadFromData by passing the raw data string and a cache key.

  11. Reference: rlottie::Property enumeration

    master

    The rlottie::Property enum defines the animatable properties available for dynamic updates. Common properties include:

    • FillColor: Color property of Fill object (type: rlottie::Color).
    • FillOpacity: Opacity property of Fill object (type: float [0 .. 100]).
    • StrokeColor: Color property of Stroke object (type: rlottie::Color).
    • StrokeOpacity: Opacity property of Stroke object (type: float [0 .. 100]).
    • StrokeWidth: Stroke width property (type: float).
    enum class Property {
    FillColor,     /*!< Color property of Fill object , value type is rlottie::Color */
    FillOpacity,   /*!< Opacity property of Fill object , value type is float [ 0 .. 100] */
    StrokeColor,   /*!< Color property of Stroke object , value type is rlottie::Color */
    StrokeOpacity, /*!< Opacity property of Stroke object , value type is float [ 0 .. 100] */
    StrokeWidth,   /*!< stroke with property of Stroke object , value type is float */
    ...
};

  12. Render an animation using Composition::render

    master

    The rlottie::renderer::Composition class is the primary interface for rendering a Lottie animation. Use the render method to draw the current frame onto a provided rlottie::Surface.

    Key methods:

    • update(int frameNo, const VSize &size, bool keepAspectRatio): Updates the composition state for a specific frame and target size.
    • render(const rlottie::Surface &surface): Renders the composition to the given surface.
    • setValue(const std::string &keypath, LOTVariant &value): Allows programmatic manipulation of Lottie properties via keypaths.