Implement a Texture2D to support Lottie animation

[beicause]

Related proposals:

• Add support for Lottie animation using ThorVG godot-proposals#9104

• Bugsquad edit, closes: Add support for Lottie animation using ThorVG godot-proposals#9104

Edit:
Currently my implemention is a Texture2D that generates a sprite sheet, configured through the properties frame_begin, frame_end, frame_count and rows, and scale to change image size.

Also, this PR implement a resource loader for lottie json. Although editor import plugin may be better, it breaks the built-in json editor.

Here are two ways to use the LottieTexture2D:

1. Set frame_count to you want to generate a sprite sheet which and be used directly in Spriteframes, which requires more memory.
2. Set frame_count to 1 and attach this texture to Sprite or TextureRect, then update frame_begin in _process() to play the animation, which Increases CPU load for frame processing.

[fire]

I'll put this on my list to review for the pipeline import.

[fire]

1. Run the godot engine binary with --doctool to update the documentation
2. I'll try to give you guidance for the "json" property being set as the default value

Here are the changes: beicause/godot@lottie...V-Sekai:godot:vsk-lottie-4.3

3. Thoughts on extending Ref<Image> directly? You could also extend Ref<Texture2D>.
4. There's a system to convert ".json" to "LottieSheet" that is missing that goes through the ResourceImporter.

[beicause]

Thanks for your guide.
I have changed it to inherit Texture2D. Now in editor it display Lottie normally, but when running the game it's empty. I don't find the reason.

[fire]

I was stuck, I suspect we need to use the resource importer system that takes json and gives a LottieTexture2D

[beicause]

I was stuck, I suspect we need to use the resource importer system that takes json and gives a LottieTexture2D

Don't open json directly. Create a LottieTexture2D and add the json as subresource.

[beicause]

I'm not very familiar with custom resource. I still can't understan why using code to set this texture works:

texture=LottieTexture2D.create_from_string(FileAccess.get_file_as_string("res://lottie.json"),1.0)

But setting the texture in editor doesn't work in games. ( Update: create_from_json doesn't work too. Fixed by disabling JSON::stringify sort_keys )

For resource importer, since lottie extension name is also .json and will be recognized as JSON, we have to customize one, for example .lottie. Or don't implement resource importer for Lottie, just create it manually and use JSON as property.

[fire]

So there's a way to create a resource importer plugin that scans for "*.json" as lottie.

I'll try to give you instructions as soon as I can or you can try it.

[Calinou]

This implementation is simple and just works for me, by generating animation frame on-demand.

While this is a simpler approach, note that it'll result in less smooth animations that no longer look crisp when zoomed in (e.g. due to Camera2D zoom or canvas_items stretch mode).

I think Lottie's biggest use case is that it allows for vector-based 2D animation with an arbitrary amount of frames (in other words, things can be freely interpolated). While you could choose to import at a high framerate (which doesn't seem to be adjustable in this importer right now), targeting 60 FPS will require a lot of memory.

This might be a dealbreaker for some use cases, so it's worth considering whether a true vector-based approach is more suitable first.

Performance is also an important caveat, similar to AnimatedTexture. Updating texture data often is slow, and it can also be inflexible (e.g. it might not obey pausing as expected).

On the bright side, this texture-based approach has some upsides, such as being easier to use in 3D (e.g. with Sprite3D). A vector-based solution wouldn't be usable in 3D unless rendered to a texture via ViewportTexture, in which case it would also lose its vector-based nature.

[beicause]

The common use case of Lottie is UI or other short duration animation, where AnimatedTexture is convenient. We can add a resource loader to import Lottie as AnimatedTexture
( I just find AnimatedTexture is deprecated, so it's not a good solution. )

[hermet]

Hello, Texture (or AnimatedTexture) methods have several advantages.

Primarily, GPU with direct drawing is not always good & faster since the following factors:

• When using Lottie as a static resource like SVG, or when animations are paused, the result from one rendering can be quickly reused in subsequent frames. This is particularly evident when using Lottie with UI assets that rarely change resolution.
• Lottie requires more composition steps than expected to complete a scene. This process involves using a temporary framebuffer to create intermediate scenes, and then extracting pixel information from the framebuffer for blending. These requirements can be quite burdensome on a GPU-based graphics pipeline compared to current software rendering & texturing method.
• Sometimes, the GPU might have too many burdens to complete real-time game graphics.

On the other hand, directly outputting vector drawings without going through textures can be more efficient in terms of memory use & performance in situations such as:

• Super high resolution for Lottie Scenes.
• Outputting very simple Lottie design resources (such as icons) without any composition.

Obviously it could be more beneficial to unify the vector drawing primitives as a single form in the Godot, however, implementing complex rendering logic like Lottie directly in Godot can be costly in terms of development resources and maintenance. Therefore, using third-party libraries may be advisable. In such architectures, typically using FBOs or textures can provide a stable integration structure during the main rendering and thorvg rendering.

Moving forward, ThorVG would be able to attempt hardware acceleration through its own hw rendering backend in order to integrate with Godot's main rendering pipeline, targeting FBOs for drawing. Nevertheless, if performance issues arise, attempting an aggressive integration structure based on direct drawing methods and sharing rendering contexts might be considered, although it will be comparatively challenging.

[fire]

@beicause @hermet Is there a test project I can send to help ThorVG debug this?

[beicause]

@beicause @hermet Is there a test project I can send to help ThorVG debug this?

thorvg_test.zip

[hermet]

Hmm... it looks threading dead lock. let me review the patch first.

[hermet]

@beicause Could you please check the comments?

Also an opinion:
I just noticed that generating all frame images like this is quite intensive. I expect that dynamically updating the texture every frame by using ThorVG animation would be better for saving texture memory and reducing the harsh initialization bottleneck.

[beicause]

I think it's easier to use it in AnimationSprite2D/SpriteFrames by generating multiple frames at the same time. And if you just want one frame, you can set frame_count to 1 and set frame_begin. Playing the animation by dynamic updating the texture needs more codes for users.

Another option is implementing a import plugin to import Lottie as a image texture, like SVG. This avoids run-time cost, but increases app size.

[fire]

Another option is to treat this like theora like a video.

[beicause]

@hermet Hello, I made the change 6e56a6c according to your guidance, but still get stuck sometimes.

[hermet]

Thank you for your update. I have some additional feedback on your code, although it might not help to resolve this issue.

Unfortunately, I've tried similar calls with our ThorVG example with your attached resource(lottie.json in lottie_test.zip) using one extra thread but didn't encounter any issues, and even the thread sanitizer didn’t report anything.

I might need more context. Could you please conduct some tests and observe the results?

1. Disable the ThorVG threading feature and see the result:
   -> Remove #define THORVG_THREAD_SUPPORT in inc/config.h.
2. Does this worker thread seems not same with the thread which calls initialize_svg_module?
   
3. How many LottieTexture2D instances are created from this issue, and does update_image() calls are made just once per its instance?

[fire]

Godot 4.3 is out.

Let's try to get this ready for review and merge. It would be great to have this.

• Show some usage tests
• Finish review

[beicause]

There are two questions that need your advice:

1. Is loading lottie at runtime needed? Using editor importer to convert it to rasterized image is enough in most case.
2. After adding json importer, godot text editor cannot be used for json anymore.

[fire]

1. We may have to make a json to texture for runtime import like png or webp.
2. We probably need to add a placeholder json text resource so it prioritizes the current behaviour over lottie. Not sure the exact way.

[Calinou]

Is loading lottie at runtime needed? Using editor importer to convert it to rasterized image is enough in most case.

I'd keep it as an editor-only importer for now, and only add runtime loading if there's significant demand (due to the increase in binary size it would cause for export templates).

After adding json importer, godot text editor cannot be used for json anymore.

This is going to be an issue for users looking to read JSON output directly for files with the standard .json extension. Can't Lottie use its own file extension such as .lottie?

[hermet]

@Calinou @fire Hello, .lottie is a zipped format of Lottie animations (JSON), containing extra metadata for theming, state machines, interactivity, sounds, etc. There is a dotLottie player project, but currently, it's not adaptable for Godot because it only supports iOS, Android, and the web. If Godot wants to support dotLottie, it needs to build an integration layer, such as an adapter, where dotLottie-rs runs on the Godot runtime with its events/mainloop backborne as well as a bunch of user interfaces to control the designed dotlottie animations. (I don't think it's compatible with Godot right now.)

A key advantage of .lottie is that it is a compressed format, saving data size. Users can benefit from it even if it contains only a single animation json but currently, ThorVG only supports the pure Lottie specification with json. If Godot wants to support the .lottie file format, it could open the file, unzip it, and access only the animation JSON files located in .lottie/animations. Godot could then pass these animations to ThorVG.

[beicause]

Add basic support for dotLottie, and a ThroVG patch to fix the bug that loading Lottie with external images would cause Godot to crash. The test project lottie-test-project.zip

[fire]

My plan for this weekend is to spent some time with the lottie pr.

[fire]

Can you file a report on https://github.com/thorvg/thorvg/issues about the crash?

[fire]

It doesn't need to be this pull request but an importer for Lottie that generates something that can dragged from the filesystem section to the scene tree would make this more usable.

[beicause]

Can you file a report on https://github.com/thorvg/thorvg/issues about the crash?

I have reported and it will be fixed in v0.15 thorvg/thorvg#2733

It doesn't need to be this pull request but an importer for Lottie that generates something that can dragged from the filesystem section to the scene tree would make this more usable.

This is easier than I thought. I achieved it by saving metadata.

[hermet]

thorvg v0.15 is out: https://github.com/thorvg/thorvg/releases/tag/v0.15.0

[hermet]

Can you file a report on https://github.com/thorvg/thorvg/issues about the crash?

I have reported and it will be fixed in v0.15 thorvg/thorvg#2733

It doesn't need to be this pull request but an importer for Lottie that generates something that can dragged from the filesystem section to the scene tree would make this more usable.

This is easier than I thought. I achieved it by saving metadata.

@beicause A mistake occurred during the merge process. Please use v0.15.1 for a more stable release. Thank you.
branch: v0.15.x
release: https://github.com/thorvg/thorvg/releases/tag/v0.15.1