feat: add registerFont API for custom TTF font loading (#422)

* feat: add registerFont API for custom TTF font loading

Adds new `registerFont` API to load custom TTF fonts at runtime, enabling
proper text rendering with non-standard fonts in Lottie animations.

Changes:
- Core API:
  * Add `register_font` to Renderer trait as static method
  * Implement font loading in TvgRenderer with ThorVG's font API
  * Always copy font data (copy=true) for memory safety
  * Hardcode "ttf" mimetype for minimal binary size

- Fallback Font (tvg-ttf feature):
  * Add compressed default font (9.5KB, decompresses to 14.8KB at runtime)
  * Auto-load fallback font on first renderer initialization
  * Use LZSS compression for optimal size/performance balance

- FFI Layer:
  * Add `register_font([ByRef] string, [ByRef] bytes)` to UDL
  * Expose through DotLottiePlayer, DotLottiePlayerContainer, DotLottieRuntime
  * Add proper forwarding through all player abstraction layers

- WASM Bindings:
  * Register `VectorChar` type for Emscripten binding
  * Expose as `registerFont(fontName: string, fontData: Uint8Array)`
  * Fix: Remove unnecessary `load_dotlottie_data` wrapper (use direct binding)
  * Fix: Bind `loadDotLottieData` directly to C++ method

- Web Example:
  * Add `registerSystemFont()` helper to load fonts from Local Font Access API
  * Demonstrate loading system fonts (Arial, Impact) into player
  * Clean up font loading examples

Benefits:
- Enables custom font rendering in text layers
- Minimal binary size impact (~100 bytes for API forwarding)
- Type-safe Uint8Array → std::vector<char> conversion via registered types
- Automatic fallback font ensures text always renders

feat: add C FFI binding for registerFont API

Adds the `dotlottie_register_font` C FFI function to enable custom font
loading from C/C++ applications.

The function accepts a font name (C string) and font data (byte pointer +
size), following the same pattern as `dotlottie_load_dotlottie_data` for
handling binary data safely across FFI boundaries.

Changes:
- Added dotlottie_register_font() in src/ffi/mod.rs
- Updated bindings.h with the new C function declaration

feat: add native features to cargo build command in Makefile

* fix: lint warnings

* fix: update pointer type for font data in register_font method

* refactor: registerFont api from an intsnace method to a standalone function

Author: theashraf

Makefile

@@ -115,6 +115,7 @@ RELEASE = release
 RUNTIME_FFI = dotlottie-ffi
 DOTLOTTIE_PLAYER = dotlottie-player
 RUNTIME_FFI_HEADER = dotlottie_player.h
+NATIVE_FEATURES = ffi,tvg,tvg-sw,tvg-webp,tvg-png,tvg-jpg,tvg-ttf,tvg-threads,tvg-lottie-expressions
 
 DOTLOTTIE_PLAYER_NATIVE_RELEASE_DIR = $(RELEASE)/$(NATIVE)/$(DOTLOTTIE_PLAYER)
 DOTLOTTIE_PLAYER_NATIVE_RELEASE_INCLUDE_DIR = $(DOTLOTTIE_PLAYER_NATIVE_RELEASE_DIR)/include
@@ -132,7 +133,7 @@ endef
 # Build native libraries for the current platform
 native:
 	@echo "Building native libraries for current platform..."
-	cargo build --manifest-path $(RUNTIME_FFI)/Cargo.toml --release
+	cargo build --manifest-path $(RUNTIME_FFI)/Cargo.toml --features $(NATIVE_FEATURES) --release
 	$(NATIVE_RELEASE)
 	@echo "✓ Native build complete. Artifacts available in $(RELEASE)/$(NATIVE)/"
 

dotlottie-ffi/bindings.h

@@ -314,6 +314,10 @@ int32_t dotlottie_pause(struct DotLottiePlayer *ptr);
 
 int32_t dotlottie_play(struct DotLottiePlayer *ptr);
 
+int32_t dotlottie_register_font(const char *font_name,
+                                const char *font_data,
+                                size_t font_data_size);
+
 int32_t dotlottie_render(struct DotLottiePlayer *ptr);
 
 int32_t dotlottie_request_frame(struct DotLottiePlayer *ptr, float *result);

dotlottie-ffi/emscripten_bindings.cpp

@@ -14,13 +14,6 @@ val buffer(DotLottiePlayer &player)
     return val(typed_memory_view(buffer_len, reinterpret_cast<uint8_t *>(buffer_ptr)));
 }
 
-bool load_dotlottie_data(DotLottiePlayer &player, std::string data, uint32_t width, uint32_t height)
-{
-    std::vector<char> data_vector(data.begin(), data.end());
-
-    return player.load_dotlottie_data(data_vector, width, height);
-}
-
 struct ObserverCallbacks
 {
     std::function<void()> on_complete;
@@ -409,6 +402,7 @@ EMSCRIPTEN_BINDINGS(DotLottiePlayer)
     register_vector<float>("VectorFloat");
     register_vector<std::string>("VectorString");
     register_vector<Marker>("VectorMarker");
+    register_vector<char>("VectorChar");
 
     register_optional<std::vector<float>>();
     register_optional<std::string>();
@@ -466,6 +460,7 @@ EMSCRIPTEN_BINDINGS(DotLottiePlayer)
 
     function("createDefaultConfig", &create_default_config);
     function("transformThemeToLottieSlots", &transform_theme_to_lottie_slots);
+    function("registerFont", &register_font);
 
     class_<Observer>("Observer")
         .smart_ptr<std::shared_ptr<Observer>>("Observer")
@@ -511,7 +506,7 @@ EMSCRIPTEN_BINDINGS(DotLottiePlayer)
         .function("isStopped", &DotLottiePlayer::is_stopped)
         .function("loadAnimationData", &DotLottiePlayer::load_animation_data)
         .function("loadAnimationPath", &DotLottiePlayer::load_animation_path)
-        .function("loadDotLottieData", &load_dotlottie_data)
+        .function("loadDotLottieData", &DotLottiePlayer::load_dotlottie_data)
         .function("loadAnimation", &DotLottiePlayer::load_animation)
         // .function("manifest", &DotLottiePlayer::manifest)
         .function("manifestString", &DotLottiePlayer::manifest_string)

dotlottie-ffi/src/dotlottie_player.udl

@@ -3,6 +3,7 @@ namespace dotlottie_player {
     Config create_default_config();
     OpenUrlPolicy create_default_open_url_policy();
     string transform_theme_to_lottie_slots([ByRef] string theme_data, [ByRef] string animation_id);
+    boolean register_font([ByRef] string font_name, [ByRef] bytes font_data);
 };
 
 [Trait, WithForeign]

dotlottie-ffi/src/ffi/mod.rs

@@ -880,3 +880,17 @@ pub unsafe extern "C" fn dotlottie_state_machine_internal_unsubscribe(
         }
     })
 }
+
+#[no_mangle]
+pub unsafe extern "C" fn dotlottie_register_font(
+    font_name: *const c_char,
+    font_data: *const c_char,
+    font_data_size: usize,
+) -> i32 {
+    if let Ok(font_name) = DotLottieString::read(font_name) {
+        let font_data_slice = slice::from_raw_parts(font_data as *const u8, font_data_size);
+        to_exit_status(dotlottie_rs::register_font(&font_name, font_data_slice))
+    } else {
+        DOTLOTTIE_INVALID_PARAMETER
+    }
+}

dotlottie-ffi/src/uniffi_impl.rs

@@ -20,3 +20,7 @@ pub fn create_default_config() -> Config {
 pub fn transform_theme_to_lottie_slots(theme_data: &str, animation_id: &str) -> String {
     dotlottie_rs::transform_theme_to_lottie_slots(theme_data, animation_id).unwrap_or_default()
 }
+
+pub fn register_font(font_name: &str, font_data: &[u8]) -> bool {
+    dotlottie_rs::register_font(font_name, font_data)
+}

dotlottie-rs/src/dotlottie_player.rs

@@ -650,7 +650,7 @@ impl DotLottieRuntime {
         // directly updating fields that don't require special handling
         self.config.use_frame_interpolation = new_config.use_frame_interpolation;
 
-        if  Self::is_valid_segment(&new_config.segment) {
+        if Self::is_valid_segment(&new_config.segment) {
             self.config.segment = new_config.segment;
         }
         self.config.autoplay = new_config.autoplay;

dotlottie-rs/src/lib.rs

@@ -16,3 +16,9 @@ pub use state_machine_engine::events::*;
 pub use state_machine_engine::security::*;
 pub use state_machine_engine::*;
 pub use theming::*;
+
+#[cfg(feature = "tvg")]
+pub fn register_font(font_name: &str, font_data: &[u8]) -> bool {
+    use lottie_renderer::Renderer;
+    crate::TvgRenderer::register_font(font_name, font_data).is_ok()
+}

dotlottie-rs/src/lottie_renderer/fallback_font.bin

@@ -0,0 +1,55 @@
+// The font is embedded as compressed data and decompressed at runtime using LZSS algorithm.
+
+#[cfg(feature = "tvg-ttf")]
+const COMPRESSED_FONT_SIZE: usize = 9721;
+#[cfg(feature = "tvg-ttf")]
+const DEFAULT_FONT_SIZE: usize = 14852;
+#[cfg(feature = "tvg-ttf")]
+const COMPRESSED_FONT: &[u8] = include_bytes!("fallback_font.bin");
+#[cfg(feature = "tvg-ttf")]
+const DEFAULT_FONT_NAME: &str = "default";
+
+#[cfg(feature = "tvg-ttf")]
+pub fn font() -> (&'static str, Vec<u8>) {
+    let mut output = vec![0u8; DEFAULT_FONT_SIZE];
+    let mut input_pos = 0;
+    let mut output_pos = 0;
+
+    while input_pos < COMPRESSED_FONT_SIZE && output_pos < DEFAULT_FONT_SIZE {
+        let flags = COMPRESSED_FONT[input_pos];
+        input_pos += 1;
+
+        for bit in 0..8 {
+            if output_pos >= DEFAULT_FONT_SIZE {
+                break;
+            }
+
+            if (flags & (1 << bit)) != 0 {
+                // Literal byte
+                output[output_pos] = COMPRESSED_FONT[input_pos];
+                output_pos += 1;
+                input_pos += 1;
+            } else {
+                // Back reference
+                let offset_high = (COMPRESSED_FONT[input_pos] as u16) << 4;
+                input_pos += 1;
+                let length_offset = COMPRESSED_FONT[input_pos];
+                input_pos += 1;
+
+                let offset = offset_high | ((length_offset >> 4) as u16);
+                let length = ((length_offset & 0x0F) + 3) as usize;
+
+                let copy_pos = output_pos - offset as usize;
+                for i in 0..length {
+                    if output_pos >= DEFAULT_FONT_SIZE {
+                        break;
+                    }
+                    output[output_pos] = output[copy_pos + i];
+                    output_pos += 1;
+                }
+            }
+        }
+    }
+
+    (DEFAULT_FONT_NAME, output)
+}