{"id":51030729,"url":"https://github.com/jtompuri/mandelbr8","last_synced_at":"2026-06-22T00:01:58.842Z","repository":{"id":355229757,"uuid":"1227282177","full_name":"jtompuri/mandelbr8","owner":"jtompuri","description":"Fast Mandelbrot generator for 8-bit computers in 100% assembly. C64, C128, Plus/4, VIC-20, PET, CBM-II, Atari, BBC Micro.","archived":false,"fork":false,"pushed_at":"2026-05-02T14:00:11.000Z","size":2861,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T15:32:21.252Z","etag":null,"topics":["6502","8-bit","assembly","atari-xl-computers","bbc-micro","commodore-128","commodore-64","fixed-point","fractal","mandelbrot","plus4","retrocomputing","vic-20"],"latest_commit_sha":null,"homepage":"","language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jtompuri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-02T13:17:16.000Z","updated_at":"2026-05-02T14:07:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jtompuri/mandelbr8","commit_stats":null,"previous_names":["jtompuri/mandelbr8"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jtompuri/mandelbr8","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtompuri%2Fmandelbr8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtompuri%2Fmandelbr8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtompuri%2Fmandelbr8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtompuri%2Fmandelbr8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jtompuri","download_url":"https://codeload.github.com/jtompuri/mandelbr8/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtompuri%2Fmandelbr8/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34629658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["6502","8-bit","assembly","atari-xl-computers","bbc-micro","commodore-128","commodore-64","fixed-point","fractal","mandelbrot","plus4","retrocomputing","vic-20"],"created_at":"2026-06-22T00:01:57.327Z","updated_at":"2026-06-22T00:01:58.832Z","avatar_url":"https://github.com/jtompuri.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mandelbr8\n\nA fast Mandelbrot generator for 8-bit computers, written in 100% assembly.\n\nThis is a fork of the original\n[`mandelbr8`](https://github.com/0x444454/mandelbr8) by `0x444454`.\nSee [Attribution](#attribution).\n\n## What's new in this fork\n\n- 40-pixel stripe Mariani-Silver rendering on C64: 27 % faster\n  multicolor, 33 % faster contour.\n- 320×200 monochrome contour mode for C64 (separate binary).\n- Edge-triggered input: one press, one action. Pan and zoom work\n  reliably under VICE warp mode.\n- Pan and zoom step sizes raised to ~4 % and ~8 % per press.\n- Vertical centering fixes for C64, C128 VIC-IIe, and C128 VDC.\n- Luma-ordered palettes for C64, C128, TED, and VIC-20.\n\n## Quick start\n\n1. Download a binary from the [`release/`](release/) folder for your\n   machine.\n2. Load and run it the usual way:\n   ```\n   LOAD\"*\",8,1\n   RUN\n   ```\n3. Use a joystick to pan and zoom. See [Controls](#controls).\n4. In [VICE](https://vice-emu.sourceforge.io/), turn on warp mode to\n   shorten render times.\n\n## Supported machines\n\n| Target          | Notes                                                          |\n|-----------------|----------------------------------------------------------------|\n| Commodore 64    | Multicolor and contour modes; optional Kawari acceleration     |\n| Commodore 128   | VIC-IIe (40-col) and VDC (80-col) modes                        |\n| Plus/4 / C16    | TED chip; 64 KB required                                       |\n| VIC-20          | 16 KB memory expansion required (Block 1 + Block 2 minimum)    |\n| PET             | 8 KB+ RAM; optional color support                              |\n| CBM-II (B128)   | 6xx and 7xx series                                             |\n| Atari XL/XE     | 64 KB; uses GTIA 16-luma mode                                  |\n| BBC Micro B     | 32 KB                                                          |\n\n## Controls\n\n| Target          | Joystick port / input                              |\n|-----------------|----------------------------------------------------|\n| C64 / C128      | Port 2                                             |\n| Plus/4 / C16    | Port 1                                             |\n| VIC-20          | Port 1                                             |\n| Atari XL/XE     | Port 1                                             |\n| PET / CBM-II    | WASD for directions, SHIFT for fire                |\n| BBC Micro       | Analog port 1, or cursor keys + Shift              |\n\n| Input               | Effect                                       |\n|---------------------|----------------------------------------------|\n| Direction (no fire) | Pan view (~4 % per press)                    |\n| Fire + Up           | Zoom in (~8 % per press)                     |\n| Fire + Down         | Zoom out                                     |\n| Fire + Right        | Increment max iterations (cap 255)           |\n| Fire + Left         | Decrement max iterations (floor 2)           |\n\nEach press triggers one action. Zoom saturates at the precision floor,\nabout 12× from the default view.\n\n## Screenshots\n\n### C64 multicolor (160×200, 16 colors, luma-ordered palette)\n\n![C64 multicolor default view](media/mandel8-c64-multicolor.png)\n![C64 multicolor zoomed](media/mandel8-c64-multicolor-zoom.png)\n\n### C64 contour (320×200 monochrome)\n\nDefault `max_iter = 32` gives 16 contour bands.\n\n![C64 contour default view](media/mandel8-c64-contour.png)\n![C64 contour zoomed](media/mandel8-c64-contour-zoom.png)\n\n### C128 VDC (160×100 in 80-column mode)\n\n![C128 VDC default view](media/mandel8-c128-vdc.png)\n![C128 VDC zoomed](media/mandel8-c128-vdc-zoom.png)\n\n### Plus/4 (TED, 160×200, uniform-luma palette)\n\n![Plus/4](media/mandel8-plus4.png)\n\n### VIC-20 (88×176, 4 fixed colors)\n\n![VIC-20](media/mandel8-vic20.png)\n\n### PET (40×25 text, color)\n\nPET has no bitmap mode; the renderer uses PETSCII glyphs for shading.\n\n![PET text mode](media/mandel8-pet-text.png)\n\n### CBM-II / B128 (80×25 text)\n\nCBM-II uses an 80-column text-mode render with PETSCII shading.\n\n![CBM-II text mode](media/mandel8-cbmii.png)\n\n### Deep zoom (C64 with SuperCPU, raised `max_iter`)\n\nA SuperCPU lifts the per-iteration cost enough that very deep zooms\nbecome practical. With `max_iter` raised via Fire+Right, more iter\nbands appear and fine fractal detail at the precision floor stays\nvisible.\n\n| Multicolor | Contour |\n|---|---|\n| ![C64 SuperCPU multicolor](media/mandel8-c64-super-cpu.png) | ![C64 SuperCPU contour](media/mandel8-c64-super-cpu-contour.png) |\n\n## Resolutions\n\n| Target                       | Lo-res preview        | Hi-res render                                    |\n|------------------------------|-----------------------|--------------------------------------------------|\n| C64 / C128 40-col / Plus/4   | 40×25, 16 colors      | 160×200, 16 colors (multicolor bitmap)           |\n| C64 contour                  | (skipped)             | 320×200 monochrome                               |\n| C128 80-col (VDC)            | 80×50, 16 colors      | 160×100, 16 colors (64 KB VDC RAM required)      |\n| VIC-20                       | 22×22, 16 colors      | 88×176, 4 colors (multicolor bitmap)             |\n| PET                          | 40×25 mono / 16-color | not supported                                    |\n| CBM-II                       | 80×25 mono            | not supported                                    |\n| Atari XL/XE                  | 40×25, 16 grey shades | 80×200, 16 grey shades (ANTIC F.1)               |\n| BBC Micro                    | 40×32, 8 colors       | 160×256, 8 colors                                |\n\n## Running in VICE\n\nTurn on warp mode to shorten render times. VICE emulates faster than\nreal time without changing the result, and the input handler stays\naccurate.\n\nVICE shortcut: Alt+W (macOS) or Page Up (Windows / Linux). Or\nSpeed → Warp mode in the menu.\n\n## Build from source\n\nBuilt with [64TASS](https://sourceforge.net/projects/tass64/) (≥ 1.59).\nOn macOS: `brew install 64tass`.\n\nThe target machine is selected by the `BUILD_*` flags at the top of\n`src/6502/mandelbr8.asm`. Exactly one must be `1`.\n\n```bash\n# C64 multicolor (default)\n64tass -o build/c64.prg -a src/6502/mandelbr8.asm\n\n# C64 contour (set BUILD_HIRES_CONTOUR = 1 in source first)\n64tass -o build/c64-contour.prg -a src/6502/mandelbr8.asm\n\n# C128, Plus/4, VIC-20, PET, CBM-II  (toggle the matching BUILD_* flag)\n64tass -o build/c128.prg  -a src/6502/mandelbr8.asm\n64tass -o build/ted.prg   -a src/6502/mandelbr8.asm\n64tass -o build/vic20.prg -a src/6502/mandelbr8.asm\n64tass -o build/pet.prg   -a src/6502/mandelbr8.asm\n64tass -o build/cbm2.prg  -a src/6502/mandelbr8.asm\n\n# Atari XL/XE\n64tass --output-exec=main --atari-xex \\\n       -o build/atari.xex -a src/6502/mandelbr8.asm\n\n# BBC Micro B (bootable SSD)\n64tass -b -o build/beeb.ssd -a src/6502/mandelbr8.asm\n```\n\nTunable build options at the top of `src/6502/mandelbr8.asm`:\n`BUILD_HIRES_CONTOUR`, `BUILD_MARIANI_SILVER_STRIPE`, `BUILD_LUMA_PALETTE`,\n`BUILD_BENCHMARK`, `BUILD_PERIODICITY`.\n\n## Technical details\n\n### Mandelbrot iteration\n\nEach iteration:\n\n```\nzx, zy ← zx + cx, zy + cy\nzx², zy² ← zx·zx, zy·zy\nif zx² + zy² ≥ 4: diverged, stop\nzx, zy ← zx² − zy², 2·zx·zy\n```\n\nMost 8-bit CPUs have no integer multiply, which makes naive\nimplementations slow. This algorithm uses Q5.11 fixed-point arithmetic\n(5-bit signed integer part, 11-bit fraction; range [−16, +16)) with a\nfast 16×16 signed multiply. The trade-off is a limited zoom range:\nthe precision floor is reached around 12× from the default view.\n\nIf the machine has at least 64 KB RAM, a 32 KB lookup table of squared\nQ4.10 values is built at startup. This eliminates two of the three\nmultiplies per iteration, leaving only `2·zx·zy` to compute via\n`smult12` (Toby Lobster's quarter-square multiply, ~234 cycles).\n\nIf a Kawari VIC-II replacement is detected on C64, hardware\nmultiplication via `$D02F–$D033` registers is used, saving ~25 % of\ntotal render time.\n\n### Q5.11 precision\n\nThe Mandelbrot set fits inside a circle of radius 2, but iteration can\nproduce intermediate magnitudes that exceed it. Q5.11 balances density\nagainst headroom for those intermediates.\n\n![max magnitudes](media/max_values.jpg)\n\n### Rendering passes\n\nMost targets render in two passes:\n\n1. Lo-res preview at e.g. 40×25 (one Mandelbrot point per cell).\n   Cardioid and period-2-bulb fast tests skip the iteration loop for\n   points known to be inside the set.\n2. Hi-res at full resolution. C64 uses stripe-wise Mariani-Silver\n   border tracing; other targets render row by row.\n\n### Stripe-wise Mariani-Silver (C64)\n\nThe hi-res image is built in 40-pixel stripes (10 multicolor cells or\n5 contour tiles per stripe). For each stripe:\n\n1. Border trace: compute the 92 perimeter samples (top + bottom rows\n   plus 6 interior pixels of each side column).\n2. Recursive subdivision: pop a sub-rectangle from a stack. If its\n   border samples are uniform, fill the interior with that iter\n   without further computation. Otherwise split at the midpoint,\n   compute the 6 pixels of the split column, and push the two halves.\n3. Sub-rectangles narrower than 6 pixels are brute-forced.\n\nDefault-view measurements on stock C64 (PAL):\n\n- Multicolor: 102 s with stripe MS, 140 s without.\n- Contour: 175 s with stripe MS, 261 s without.\n\n### Color clash\n\nVIC-II 4×8 multicolor blocks support 4 colors:\n\n- 1 shared background (black, used for the in-set Mandelbrot region).\n- 3 per-tile colors from the 16-color palette.\n\nA histogram of each tile's iter values selects the 3 most common as\nthat tile's per-tile colors. Some artifacts can remain depending on\ntile location in the complex plane.\n\n`BUILD_LUMA_PALETTE` (default-on) reorders the palette so adjacent\niter values map to perceptually adjacent luminance. The same flag\nalso gives:\n\n- C128 VDC: a luma-ordered 16-color palette mapped to the VDC\n  CGA-style colors.\n- TED (Plus/4 / C16): a uniform-luma palette. TED multicolor allows\n  only 2 cell-specific colors per 4×8 cell, so any luma variation\n  between cells creates visible stepping. Tunable via `TED_HI_LUMA`\n  in the source.\n- VIC-20: the 4 fixed multicolor slots reordered as\n  black → blue → purple → white.\n\n## License\n\nCreative Commons Attribution 4.0 International (CC BY 4.0).\n\n\u003chttps://creativecommons.org/licenses/by/4.0/\u003e\n\n## Attribution\n\nThis project is based on / adapted from `mandelbr8`, originally created\nby GitHub user `0x444454`.\n\nOriginal repository:\n\u003chttps://github.com/0x444454/mandelbr8\u003e\n\nThe original repository appears to be no longer available on GitHub.\nThe original project was licensed under Creative Commons Attribution\n(CC BY). This version contains modifications by Janne Tompuri /\n[`jtompuri`](https://github.com/jtompuri).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtompuri%2Fmandelbr8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjtompuri%2Fmandelbr8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtompuri%2Fmandelbr8/lists"}