Skip to content

Viewer shows an empty canvas for sketches that set no screen map in setup() (e.g. Blink) #250

Closed

Description

@zackees

Summary

A sketch that never calls .setScreenMap() in setup() — for example the stock Blink example — shows an empty canvas in the viewer. The LEDs update in WASM, but the renderer never receives a layout for them.

FastLED does create a default layout for such strips, but only on the first frame, after the worker has already taken its one and only look at the layouts.

Where it happens

  1. The worker calls extern_setup(), then reads layouts exactly once with getScreenMapData():
    src/fastled/frontend/modules/core/fastled_background_worker.ts:627-668. If setup() registered none, the result is {}.
  2. FastLED creates the missing default layout lazily, when a frame is exported:
    getFrameData() / jsOnFrame() → jsFillInMissingScreenMaps() in FastLED src/platforms/wasm/js_bindings.cpp.hpp ("Creating linear screenmap for N").
  3. That function calls _jsSetCanvasSize(), which only logs Screenmap update available (worker will poll via getScreenMapData).
  4. Nothing polls again. Nothing in the frontend posts the screenmap_update message that handleScreenMapUpdate() (fastled_background_worker.ts:932) handles. The graphics manager keeps an empty layout for the rest of the session.

Reproduction

Observed 2026-09-14 on Linux (WebKitGTK 2.52, feat/kernal-api-migration build), with fastled <sketch> --test --test-screenshot ...:

  • Blink (no setScreenMap, delay()-based): the canvas stays empty.
  • The same 60-LED strip with a layout set in setup() renders and animates:
    fl::ScreenMap screenMap = fl::ScreenMap::DefaultStrip(NUM_LEDS, 1.5f, 0.5f);
    FastLED.addLeds<WS2812B, DATA_PIN, GRB>(leds, NUM_LEDS).setScreenMap(screenMap);
    Red/blue flips every 500 ms: X11 in-page captures RRBBRRRRBBRR; Wayland captures RBRRBB.

This is independent of the renderer path: it reproduces on both X11 and Wayland.

Suggested fix

Have the worker pick up layouts that appear after setup(), for example:

  • Re-read getScreenMapData() after a frame whenever the frame data lists a strip with no cached layout (cheap: only runs until every strip has one), or
  • Make FastLED's _jsSetCanvasSize() actually notify the worker (the comment says EM_JS had partial-link issues; a flag the worker checks per frame would avoid that).

The frontend also lives in FastLED at src/platforms/wasm/compiler/modules/core/fastled_background_worker.ts, so the fix should land in both places, or wherever the frontend is now owned.

Acceptance

  • The unmodified Blink example shows its LEDs in the viewer.
  • A --test render check covers a sketch with no setScreenMap() call.

Activity

  1. zackees commented on Sep 17, 2026

    @zackees
    MemberAuthor

    This also hits sketches that DO call setScreenMap() in setup(), and it blocks #247's verification.

    Reproduced on main (4ebcabd), NVIDIA Wayland, with a 60-LED strip whose setup() is exactly the workaround this issue suggests:

    fl::ScreenMap screenMap = fl::ScreenMap::DefaultStrip(NUM_LEDS, 1.5f, 0.5f);
    FastLED.addLeds<WS2812B, DATA_PIN, GRB>(leds, NUM_LEDS).setScreenMap(screenMap);

    fastled <sketch> --test --test-screenshot ... --test-exit-on-error exits 125, fastled: viewer did not render a canvas before --test-ready-timeout-secs, and no screenshot is written. Viewer log:

    0.2s Strip added: ID 0, LEDs 60
    0.2s js_bindings.cpp.hpp(340): INFO: Screenmap update available (worker will poll via getScreenMapData): {"0":{"strips":{"0":{"map":{"x":[8.853,...],"y":[...]},"diameter":0.500}}}}
    0.3s _setupCanvasAndDimensions: screenMapWidth is <= 0 or invalid, using MIN_DIMENSION {"screenMapWidth":null,"screenMapsCount":0}
    0.4s [GraphicsManagerThreeJS] No screenMap found for strip 0
    0.4s No screenMaps available for LED visual updates
    

    The layout is fully present in that update, and the renderer still has none: the worker's single getScreenMapData() read happened before it arrived. So the trigger is ordering, not whether setup() registers a map, and the "set a screen map in setup()" workaround does not reliably avoid it.

    Two consequences:

    1. The fix should be verified with a sketch that sets a screen map, not only with Blink.
    2. migration: real WASM viewer fails OffscreenCanvas WebGL2 compatibility in Linux smoke #247 cannot be closed until this lands. Its remaining step is one real --test render, and that render fails here for this reason, not for a WebGL2 reason. The WebGL2 part of migration: real WASM viewer fails OffscreenCanvas WebGL2 compatibility in Linux smoke #247 now behaves as intended: webgl2:false on OffscreenCanvas falls back to contextType: "main_thread" without error.

    Suggested RED -> GREEN for the fix: the command above exits 125 with no screenshot before, and exits 0 with a screenshot showing lit LEDs after.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions