# VIXEN-32 tutorials Thirteen small, self-contained programs — one hardware feature each. Every directory builds one `tutN.rvk`: copy it to the SD card anywhere under `/VIXEN-32/`, press HELP at Ready, pick it in the file browser and type RUN. | Tut | Shows | Key calls | |-----|-------|-----------| | tut1 | Hello world on the tile/text layer | `VIH_TILE_MAP0_BASE`, `vih_tile_cell_t` | | tut2 | Hardware sprite (flying balloon, 256 colors) | `vih_sprite_attr/pos`, `vih_set_palette` | | tut3 | Tiles, tile map, pixel scrolling | `VIH_TILE_SCROLL` | | tut4 | 256-color framebuffer + scrolling | `vih_gfx_ptr_addr`, `vih_gfx_scroll` | | tut5 | BOBs (blitter objects) + double buffering | `vih_blit_copy_key` | | tut6 | Blitter line draw | `vih_blit_line` | | tut7 | Gouraud shading | `vih_blit_gouraud` | | tut8 | Texture mapping (rotozoom) | `vih_blit_texload/texspan` | | tut9 | Copper raster bars | `vih_copper_entry/run` | | tut10 | SID sound (C64-style pokes) | `vih_sid` | | tut11 | ProTracker module playback | `mod_load`, `mod_tick` | | tut12 | Two tile maps + copper split screen | `VIH_TILE_MAP1_BASE`, `COP_REG_TILEMAP_ROW_PTR` | | tut13 | Overlapping parallax: gfx behind transparent banded tiles + sprite | `COP_REG_TILE_SCROLL`, `VIH_TILE_PRIORITY` | ## BASIC tutorials `basic/` holds a separate set of sixteen, written in EhBASIC rather than C — the same hardware reached with `POKE` instead of a register write, for people who will never open a cross-compiler. They ship as `.BAS` text in `/VIXEN-32/basic/` and as `.PRG` on the Basic-A.img disk, not as `.rvk`; see `basic/README.md`. ## Toolchain setup (once) The tuts build with **xPack RISC-V Embedded GCC** (`riscv-none-elf`, a plain portable tarball — no installer, no root) on Linux or WSL: mkdir -p ~/opt && cd ~/opt wget https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v15.2.0-1/xpack-riscv-none-elf-gcc-15.2.0-1-linux-x64.tar.gz tar xf xpack-riscv-none-elf-gcc-15.2.0-1-linux-x64.tar.gz Optionally add `~/opt/xpack-riscv-none-elf-gcc-15.2.0-1/bin` to your PATH. The Makefiles find the compiler on PATH, fall back to that `~/opt` location, or take an explicit override: make CROSS=/wherever/bin/riscv-none-elf- Any recent release works — the code is plain rv32im C. You also need `python3` and a host C compiler (`cc`) for the packer, both standard on Linux/WSL. ## Building Each directory is independent: cd tut1 && make -> tut1.rvk The Makefiles expect the repo layout: startup code (`crt0.S`) and the hardware headers (`vih_regs.h`, `mod_player.h`) come from `../..` (the `risc/` folder), shared assets from `../common`. Each tut carries its own linker script (`app.ld`) — that file IS the app memory map, worth a read. `common/make_balloon.py` regenerates `common/balloon.raw` (the sprite used by tut2, tut5 and tut13). ## The idioms every tut uses - `vblank(250)` — spin until the raster reaches line 250 (lower border), exactly once per frame. Register writes after it land between frames: no tearing. This is the main loop heartbeat everywhere. - First write wins: most VIH registers latch RISC-V ownership on the first write, so a fresh app just writes what it needs and the machine is its own. - Palette entries 0–15 are the C64 colors; set higher entries yourself (`vih_set_palette(index, r5, g6, b5)`).