Software Fallback Smoke Matrix
Manual smoke-test checklist for the Canvas 2D software renderer.
This checklist is for quick manual verification of the software renderer. Originally written for the software-renderer
MVP; updated for auto-fallback and the engine overlay (backend shown on the top bar when isOverlayEnabled is true).
Scope
- Backend under test:
software(auto-fallback when WebGPU unavailable,?backend=software, orconfigure().backend = 'software') - Resolution target: low-res scenes (for example
320×240) - In scope: auto-fallback detection, overlay backend line, clear, clearRect, primitives, sprites, system text, bitmap text, camera offset, frame capture
- Out of scope: fullscreen shader/post-process effects (
effectAdd,effectRemove,effectClear) in software mode
Environment
- Browser: latest Chrome or Edge; Firefox on Linux without WebGPU (software path / auto-fallback)
- URL override for software mode:
?backend=software
- Optional baseline comparison:
- same page without override (WebGPU path)
Matrix
| Scene | What to verify | Software expected result | Notes |
|---|---|---|---|
Any page without ?backend=software | Auto-fallback when WebGPU is absent | Demo boots; BT.activeBackend = 'software' | No error page or hard stop |
| Any page with software active | Overlay top bar shows software | Top bar reads software | WxH (toggle with ~ or corner) | Disable with isOverlayEnabled: false |
tests/visual/fixtures/primitives.html | clear + clearRect + primitive rasterization | Matches expected primitive layout and colors | Check pixel edges are crisp |
tests/visual/fixtures/camera.html | camera offset applied to all draw calls | Geometry is shifted consistently by camera offset | No partial drift between primitives |
tests/visual/fixtures/sprites.html | indexed sprites + palette offsets + transparency | Sprite shapes/colors match expected output | Transparent pixels stay see-through |
tests/visual/fixtures/fonts.html | system text + bitmap font rendering | Text positions and glyph colors are correct | No missing glyph blocks |
tests/visual/fixtures/mixed.html | primitives + sprites + layering order | Same stacking as WebGPU for this fixture | Parity covered by Playwright snapshot |
Frame capture via BT.captureFrame() | PNG export in software mode | Promise resolves with PNG blob | Repeat capture across multiple frames |
Automated regression
Visual parity for software mode is exercised by Playwright under tests/visual/ (primitives, camera, sprites -
including the oriented, stretched, and nine-slice fixtures - fonts, mixed, and render-at specs load fixtures with
?backend=software). Run pnpm run test:visual after renderer changes that affect pixel output.
Known exclusions (expected in MVP)
Effects APIs fail in software mode
Calling fullscreen effects APIs in software mode should fail clearly:
BT.effectAdd(...)BT.effectRemove(...)BT.effectClear()
Expected message intent: software mode does not support fullscreen effects and suggests switching to WebGPU.
Pass criteria
- All rows in the matrix pass in software mode.
- Software output is visually stable run-to-run for the same scene.
- Effect API failures are clear and actionable.
See also
API: Core
Post-Process Effects
Testing
Overlay Guide
Last updated on October 18, 2026