Files
VCCPlusDiagnostics/examples/fpga256/README.md
T

55 lines
2.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# FPGA Colour Lab
Assembly-only, user-facing diagnostic for the optional CoCo3FPGA/MiSTer
256-color extension and VCC Plus's matching core option. It is **not a standard
CoCo graphics mode**. Use a fresh disposable BASIC machine; the diagnostic uses
physical RAM4000..B7FF as its framebuffer. Eject SSC and enable the extension.
No private ROM bytes are included in the source or disk.
## Build
Python3.9+ and LWASM4.25 are sufficient, on Windows or Mac/Linux:
```sh
python3 examples/fpga256/build.py --lwasm /absolute/path/to/lwasm --output .build/colourlab-run1
```
On Windows, supply `lwasm.exe` and the installed Python executable. The builder
requires a fresh output folder and preserves prior disks. VCC Plus on Mac
bundles LWASM in its compiler stack; no C/CMOC build is needed here.
The tracked `generated.inc` also lets the native assembly workspace assemble
`colorlab.asm` directly. The Python builder regenerates that include and creates
the complete test disk; the include is authored test data, not a private ROM.
Outputs: COLORLAB.DSK (35-track DECB), COLORLAB.BIN, ASCII COLORLAB.BAS, listing,
generated banner/palette input and a source/artifact SHA256 manifest. Keep the
master and manifest together; copy the disk for interactive tests.
## Play and inspect
In the Mac development build, enable **FPGA 256-color support** in Machine
Settings and apply the change. Mount a writable copy in FD0 in Disk BASIC.
Type `RUN"COLORLAB"`, read the instructions, then
press any key. The launch assumes ordinary32-column BASIC and returns to that
mode; it does not attempt to read back write-only GIME registers.
- **Grid:** 16 columns ×16 rows,256 distinct colors. Small cells are ordered
left-to-right, then top-to-bottom. Look for missing/duplicated cells or colors.
- **Space:** cycle grid, byte ramp and one-pixel alternating stripes. Look for
stable edges and consistent pixel ordering/row alignment.
- **A:** toggle palette animation. Colors move without redrawing the picture;
the black/white header entries are retained for readable controls.
- **Q:** restore the saved MMU mapping, standard BASIC video/ROM setup and caller
stack, then return. The keyboard is scanned directly and debounced, avoiding
patched BASIC POLCAT hooks while in the temporary graphics mapping.
Take a gallery photograph/screenshot, note platform/core/version and which
controls worked, then report any missing colors, seams or unexpected resets.
The disk does not claim to measure analog calibration. It does not yet save a
result file; automatic native tests record exact pixel/control checks separately.
Guest validation covers actual assembly on both 6809 and 6309 engines and a real
Disk BASIC RUN/LOADM/EXEC path. This is distinct from native Mac UI or physical
MiSTer acceptance. See the [Mac validation record](../../docs/development/FPGA256_MAC_VALIDATION.md)
for the separate host checks.