Skip to content

README.md

Latest commit

 

History

History
59 lines (42 loc) · 3.98 KB

README.md

File metadata and controls

59 lines (42 loc) · 3.98 KB
Raw

FastLED Platform: wasm

WebAssembly/browser platform with C++ ↔ JavaScript bridges and a pure data‑export pattern.

Files and directories (quick pass)

  • js_bindings.cpp: Critical C++↔JS bridge (EMSCRIPTEN_KEEPALIVE functions). Exports frame/strip/UI data as JSON and avoids embedded JS. JavaScript side handles async via modules in compiler/modules/.
  • entry_point.cpp, timer.cpp, ui.cpp, js.cpp, fs_wasm.*, fastspi_wasm.*: WASM platform runtime and I/O.
  • compiler/: Browser launcher and JS modules (async controller, events, graphics, UI, audio). Also includes build_flags.toml for WASM builds.

Threading Architecture (Worker Thread Mode)

FastLED WASM uses dedicated Web Workers (PROXY_TO_PTHREAD) for background execution. Asyncify was removed in 2025-01 to reduce binary size (44.4% reduction) and fix audio reactive mode issues.

Multithreading Support

WASM uses the stub platform threading profile (identical to host testing builds):

  • Threading detection: Defers to fl/stl/thread.h default logic (FASTLED_TESTING + pthread.h availability)
  • When enabled (FASTLED_MULTITHREADED=1):
    • Real mutexes: fl::mutex → std::mutex (POSIX pthread mutexes via Web Workers)
    • Real atomics: fl::atomic<T> → AtomicReal<T> (using __atomic compiler builtins)
    • Condition variables: fl::condition_variable → std::condition_variable
    • Thread-safe primitives: All FastLED synchronization primitives are thread-safe
  • When disabled (FASTLED_MULTITHREADED=0):
    • Falls back to fake mutex/atomic implementations (single-threaded mode)

Build flags in compiler/build_flags.toml provide pthread support:

  • -pthread (compiler and linker)
  • -sUSE_PTHREADS=1 (Emscripten pthread implementation)
  • -sPROXY_TO_PTHREAD (run main() on a pthread)

Design principle: WASM and stub platform share identical threading configuration, ensuring consistent behavior between WASM browser builds and desktop testing environments.

When adding or modifying C++ ↔ JS bridge functions:

  • Synchronous execution: All C++ ↔ JS bridge functions execute synchronously in the worker thread. No Asyncify.handleAsync or async/await needed for WASM calls.
  • Keep exported C functions stable: Treat names and parameter/return types as a strict ABI with the JS loader. If a signature must change, update both C++ and compiler/modules/ consumers together.
  • Prefer a data-export pattern: Allocate in C++, return ownership/size to JS, and provide matching free functions (e.g., getFrameData/freeFrameData). Do not embed JS in C++; centralize browser logic under compiler/modules/.
  • Worker thread benefits: True background threading without blocking UI. No manual yielding needed - OS scheduler handles thread scheduling naturally.

Recommended exported patterns:

  • Buffer export: extern "C" EMSCRIPTEN_KEEPALIVE const uint8_t* getFrameData(uint32_t* out_size); paired with freeFrameData(const uint8_t* ptr).
  • JSON export: return const char* to a stable, heap-allocated UTF-8 string with a corresponding free.
  • UI bridge: expose functions that poll/apply updates on frame boundaries (e.g., applyPendingUiJson()), and keep them non-blocking.

Behavior and constraints

  • Follows a pure data‑export approach for C++↔JS boundaries: C++ allocates/returns buffers and JS polls/reads; no embedded JS in C++.
  • Exported function signatures are a contract with JS (e.g., getFrameData, freeFrameData, getStripPixelData); changes require synchronized JS updates.

Optional feature defines

  • FASTLED_STUB_IMPL: Enables stubbed Arduino/system behaviors for WASM builds (set in led_sysdefs_wasm.h).
  • FASTLED_MULTITHREADED: Inherits stub platform's detection (based on FASTLED_TESTING + pthread.h). Can be overridden before including FastLED.h.
  • FASTLED_HAS_MILLIS: Default 1.
  • FASTLED_USE_PROGMEM: Default 0.
  • FASTLED_ALLOW_INTERRUPTS: Default 1.

Define before including FastLED.h if overriding defaults.