Fix fragmented SVG rendering in a kiosk browser

What the tiles are and the flag that clears them

Chromium builds a page in stages. One stage, rasterization, turns vector drawings such as SVG paths into pixels. When that stage runs on the GPU and the image has a fault in its GPU raster path, the pixels come out as fragments: tiles, strips and half-drawn icons that move when the page redraws. Photos and text can stay clean, because they arrive as bitmaps and glyphs on a different path.

The switch --disable-gpu-rasterization moves that one stage back to the CPU. It is a long-standing Chromium switch, carried and discussed in public browser project trackers since 2020. The other GPU stages keep their own settings, which you confirm after the change at chrome://gpu.

Symptoms and what each one points to

• SVG icons and line art fragment into tiles or strips while text and photos stay clean, and the tiles shift when the page scrolls. That is the raster stage drawing on the GPU. It points at the browser image.
• A VNC capture of the desktop shows the same tiles. The compositor container ships a VNC option (ENABLE_VNC=1 in its environment). If the capture carries the fault, the pixels are wrong before the video output, and the cable, panel and timing are cleared.
• The VNC capture is clean while the physical screen corrupts. The fault sits between the module and the glass: cable, adapter or the HDMI path. Work it as a signal problem, the way troubleshooting an embedded controller's video display lays out.
• Every application corrupts, launcher included. The browser is not the culprit. The GPU driver or the compositor container is, and the rasterization switch will not touch it.
• The window is black while navigation sounds keep playing. A different failure with its own causes, covered in fixing an embedded browser editor black screen.
• The page draws but sizes wrong for its window. Geometry, not pixels; see diagnosing kiosk browser sizing in an HMI window.
• The renderer crashes on heavy pages instead of misdrawing. That points at shared memory. The compose stack that documented this fault sets shm_size: 256mb on the kiosk service; keep at least that.

Checks that clear the cable and the timing

Compare the logged mode against the format table. The compositor log prints the mode it settled on; in the documented case, 1920 x 1080 at 60.0 Hz with a 148.5 MHz pixel clock on HDMI-A-1. A 148.5 MHz clock at 1920 x 1080 and 60 Hz is the standard 1080p60 timing in the CEA-861 format table, and the arithmetic is in the example below. A match this exact tells you the timing is standard and the fault sits upstream of the cable.

Compare container tags. Run tag 2.5 and tag 2.6.0 on the same module with the same page. The documented fault appeared exactly between those two tags.

Read the raster status. Start the kiosk on chrome://gpu as its URL and read the feature list; the raster line tells you which path is drawing. For a quick look without editing files, chrome://flags carries a GPU rasterization override you can set to Disabled, but flags-page settings live in the browser profile. The flags file is the form that survives a container rebuild.

The fix, step by step

1. Write the flags file on the host next to your compose file, named default-flags. Start from the stock file in the container, which enables rasterization with --enable-gpu-rasterization, and flip that one switch to the disable form:

--disable-gpu-rasterization

Append this flag to the existing CHROMIUM_FLAGS export line in the stock file and leave the rest of the file as it is.

2. Mount it into the kiosk service at the path the browser wrapper reads:

    volumes:
      - ./default-flags:/etc/chromium.d/default-flags

If you build a derived image, COPY the file to the same path instead.

3. Recreate the browser container with docker compose up -d kiosk. The compositor service stays as it is; only the browser reads this file.

4. Verify two things: the page that fragmented now draws clean, and chrome://gpu shows the raster stage on the software path. Video decode and compositing should still list as GPU features. If one of those changed too, something else in the stack moved with your change and the result deserves a second look.

Example: one 1080p kiosk from tiles to clean icons

The build that documented the fault: an arm64 system-on-module with a hardware GPU, the vendor's Weston compositor container at tag 2.7.2, and their Chromium kiosk container at tag 2.6.0, on OS build 5.6.0. The compositor logged 1920 x 1080 at 60.0 Hz, 148.5 MHz pixel clock, on HDMI-A-1.

Clear the timing first with arithmetic. Active pixels: 1920 x 1080 = 2,073,600. The CEA-861 1080p60 format blanks each line to 2200 pixels and each frame to 1125 lines, so one frame carries 2200 x 1125 = 2,475,000 pixels. At 60.0 Hz: 2,475,000 x 60 = 148,500,000 pixels per second, which is the logged 148.5 MHz exactly. The mode is the standard one.

Then place the fault. A VNC capture showed the same tiles as the glass, so the wrong pixels were already in the render. Rolling the browser container back to tag 2.5 on the same hardware drew the same pages clean, which put the fault in tag 2.6.0's GPU raster path. The vendor reproduced the result on a second module family, on OS build 5.6.0 and on a 5.7.0 nightly, and called it a fault in their image.

The fix on that stack: mount the flags file with --disable-gpu-rasterization, recreate the kiosk container, reload the icon page. The tiles cleared, chrome://gpu showed raster on the software path, and the kiosk kept tag 2.6.0's GPU acceleration for the stages that still used it. In that discussion the newest image, tag 2.7.0-20220825, still shipped Chromium 101, so the flag and the rollback tag were the two working tools.

Which route for which kiosk

• Notice boards and static pages whose SVGs redraw rarely. Mount the flags file and keep tag 2.6.0. Software raster costs almost nothing while the page holds still.
• Dashboards with animated SVGs redrawing every second. Measure processor load with the flag on while the heaviest page runs. With headroom, keep the flag. At saturation, run that screen on the Cog kiosk browser, which the vendor's own tests drew correctly with hardware acceleration, or roll back to tag 2.5 and give up 2.6.0's acceleration.
• Kiosks whose payload is video, with SVG only as decoration. Keep the flag and confirm at chrome://gpu that video decode stayed on the GPU. The switch names raster only.
• Corruption outside the browser too. The switch is the wrong tool. Take it to the compositor or GPU driver path with your vendor.

Recommendation: mount /etc/chromium.d/default-flags with --disable-gpu-rasterization and stay on the container tag you tested. Keep the flag until the vendor's release notes name this SVG fault as fixed, then retest without it. When a page animates constantly and the CPU cannot spare the raster work, move that screen to the Cog browser or to tag 2.5.

When the screen does not need a browser

A kiosk browser earns its keep when the content is live pages. A plant notice board showing prepared safety notices, shift figures and a looping video needs no browser at all: a screen that plays images and video from a card has no rasterization stage, no container and no render bug to chase. Our factory displays do that job from a card, offline, with the player software included and no subscription. Whether a given screen should be a live dashboard or a playing sign is its own decision; live factory data display: signage or dashboard works it through, and factory data table signage for offline screen content covers building the content that goes on the card.

Questions