[Copilot] Add FlatBuffer runtime interpreter for Lottie animations

[jonwis]

Summary

Adds a data-driven runtime path for Lottie animations:

1. LottieGen -Language flatbuffer converts Lottie JSON into a compact .lcomp FlatBuffer.
2. LottieRuntime validates the FlatBuffer and hydrates the corresponding Windows.UI.Composition visual tree.
3. Applications either compile the interpreter directly into native code or share it as a registration-free COM DLL.

The serialized graph supports the Composition objects, animations, effects, geometries, loaded images, and custom animation controllers emitted by the existing native generators.

Motivation

Generated C++/CX and C++/WinRT implementations duplicate the code needed to construct every object, property, animation, and expression in each animation. Complex animations produce large generated translation units and linked binaries. That increases DLL size, loaded code pages, private working set, and duplicated WinRT ABI call-site code.

The FlatBuffer path keeps each animation as data. One shared interpreter hydrates any number of animations into the same Composition object graph the generated implementations produce. Applications pay the interpreter cost once, then add only the FlatBuffer payload for each additional animation. The COM form can also be shared across binaries.

Size comparison

Measured with LottieSamples/Assets/LottieLogo1.json, targeting UAP 15 on both paths. Both native binaries used /O1, /Gy, string pooling, /GL + /LTCG, /OPT:REF, /OPT:ICF, and non-incremental linking.

Payload	Bytes	KiB
Generated C++/WinRT DLL	198,656	194.0
FlatBuffer (LottieLogo1.lcomp)	28,120	27.5
Shared interpreter DLL	155,136	151.5
FlatBuffer + interpreter for first animation	183,256	179.0

The first interpreted animation is 15,400 bytes (7.8%) smaller than the generated DLL, including the complete interpreter. Each additional animation adds only its FlatBuffer: 28,120 bytes instead of another 198,656-byte generated implementation for this sample, an 85.8% reduction in marginal binary payload.

The generated comparison DLL exports one creation entry point to keep the complete generated graph construction path reachable. The measurement excludes application host code and dependencies common to both approaches.

Runtime and ABI

LottieRuntime:

• verifies the LCMP identifier and FlatBuffer structure before reading data;
• validates the buffer's required Universal API contract before hydration;
• range-checks graph references and rejects geometry cycles;
• uses dense index-based caches so each string and Composition node is realized once;
• builds Direct2D path geometry without taking a Win2D dependency;
• exposes ILottieCompositionLoader::LoadComposition(UINT32, BYTE const*, REFIID, void**) as its DLL ABI;
• supports registration-free COM activation through LottieRuntime.manifest;
• keeps the C++ LoadComposition(Compositor, span<byte>) API available to applications that compile the implementation directly.

The DLL exports only DllGetClassObject and DllCanUnloadNow. C++ projection types and exceptions do not cross the DLL boundary. The DLL targets Windows 10 1809 / UniversalApiContract v7; individual buffers declare any newer contract they require.

Tooling

LottieRuntime.exe <path-to-flatbuffer> [--dump|--show] provides one native test and inspection tool:

• no option: validate and load the composition;
• --dump: print the hydrated Composition object hierarchy;
• --show: host and animate the resulting visual in a Win32 window.

Distribution

LottieGen.nupkg includes the complete native runtime source set under LottieRuntime/:

• direct-link C++ implementation and header;
• COM ABI, class factory, module definition, manifest, and native project;
• generated FlatBuffer C++ binding;
• pinned FlatBuffers headers and licenses;
• integration instructions for C++/WinRT and managed applications.

C++/WinRT applications can compile LottieRuntime.cpp directly into their product. Managed applications add LottieRuntime.vcxproj to the solution and copy LottieRuntime.dll plus LottieRuntime.manifest into application outputs.

Validation

• FlatBuffer serializer/deserializer corpus, robustness, and coverage tests: 23 passed.
• LottieLogo1.json converted to .lcomp, activated through registration-free COM, and hydrated successfully.
• LottieRuntime.exe validate, dump, and show modes exercised on Release x64.
• Runtime DLL and tool compile for x64 and ARM64.
• Runtime project extracted from LottieGen.nupkg and built independently.

(via Copilot)

[jonwis]

@dotnet-policy-service agree company="Microsoft"

[aborziak-ms]

@jonwis I left a few inline comments, but wanted to share some higher-level thoughts as well:

• I'd suggest scoping this PR to the .lcomp format + LottieGen output + a small native C++ runtime. For native, a simple .h/.cpp drop-in that takes the app's Compositor and works with AnimatedVisualPlayer should be enough. I don't think we necessarily need the COM DLL here, since C++ apps can just compile the drop-in. The C# interpreter would mostly duplicate Instantiator, which the managed side (Lottie-Windows package) can reuse.
• I can pick up the managed side separately and integrate lcomp into Lottie-Windows UWP and WinUI packages. The .lcomp graph is basically what Loader already builds from JSON, so we can load it through the existing LottieVisualSource path and get AnimatedVisualPlayer, images, WinUI 3 etc. for free.
• Since the format would be shared by both, it'd be good to settle a few things now: include all UAP versions (like codegen does), have a versioning for schema changes, and keep the generated types internal.
• For FlatBuffers, maybe just check in include/flatbuffers + LICENSE inside the native runtime folder instead of a full submodule? It's the only thing that needs the headers, it keeps the drop-in self-contained.

[aborziak-ms]

Lower-UAP translations are silently dropped here.

[jonwis]

I'll see what it takes to do that. I was hoping we'd be able to drop support for older UAPs and focus on WASDK version levels instead.

[aborziak-ms]

The loader creates its own Compositor, so the returned visual can't be attached to the host's tree. I think we should accept compositor parameter from the caller, e.g. LoadComposition(IUnknown* compositor, UINT32, BYTE const*, REFIID, void**)

[jonwis]

Sure. Will add the new parameter here and in the IDL, docs, etc.

[aborziak-ms]

Right now this only returns back a raw Visual, so it doesn't match what other generated code does. Should we wrap it in an IAnimatedVisualSource that exposes the same stuff the generated class does (Duration, Markers, FrameCount, FrameToProgress, SetColorProperty, etc.)? Then TryCreateAnimatedVisual(compositor) would return the visual with Size/Duration.

[jonwis]

Hm. That's a XAML type? Why not stay within the Composition scope so somebody can use it without XAML?

[aborziak-ms]

I think the managed side should just live in Lottie-Windows. Then there's one C# library that handles both JSON and .lcomp, and .lcomp can reuse the existing pipeline (CompositionDeserializer → Instantiator → AnimatedVisualPlayer) instead of a separate C# interpreter. I'd keep LottieRuntime as the small native runtime for C++ only. Otherwise, I'm worried we end up with too many pieces doing the same thing but a little differently.

[jonwis]

OK. I'll extend the existing C# library with this support instead and remove this one.

[aborziak-ms]

We might want to cap recursion depth here (and in GetShape/BuildGeometry). A relatively small malformed or malicious .lcomp could blow the stack.

[jonwis]

Seems reasonable. What cap depth seems good? I'll start with 256 maybe?

[jonwis]

• I don't think we necessarily need the COM DLL here, since C++ apps can just compile the drop-in. The C# interpreter would mostly duplicate Instantiator, which the managed side (Lottie-Windows package) can reuse.

OK, will narrow to just the producer and C++ consumer code, and update the C# instantiator. In Windows, we'll want to have a shared copy of the instantiator. What do you think about "a pretty OK sample" that shows using this in a common way? Or do we just assume the bots will figure out how to have one copy per process?

• pick up the managed side separately and integrate lcomp into Lottie-Windows UWP and WinUI packages.

That'd be great! Is there anything needed to get this ready for a C++/WinRT consumer of WASDK XAML/Composition? Does Lottie-Windows have a C++/WinRT package?

• it'd be good to settle a few things now: include all UAP versions (like codegen does), have a versioning for schema changes, and keep the generated types internal.

See note on supported UAP versions. At some point we should include "supported WASDK versions" and migrate people to using the Microsoft.UI types. I'll make the changes you suggest.

include/flatbuffers + LICENSE inside the native runtime

I'll have to see what that looks like; IIRC I had to tinker a bit to get flatc.exe working correctly.

Thanks for the comments!