Update README

Author: Timendus

README.md

@@ -1,49 +1,17 @@
 # Silicon8
 
 Silicon8 is an implementation of a runtime for Chip-8, SCHIP and XO-Chip in Go
-that can run as a standard Go module, or be compiled to WebAssembly with TinyGo.
-Please note that it is currently a work in progress, and far from perfect.
+that can be used in Go projects or it can be compiled to WebAssembly so it can
+run in your web browser (or anywhere WebAssembly can run).
 
-This is my first experiment with WebAssembly and with Go. So I'll probably look
-back on this repository with shame in a very short amount of time 😉 But that's
-the point of this, this is a learning project for me.
-
-## Developer instructions
-
-### How to run
+To try it running in your browser, visit https://timendus.github.io/silicon8/
+and load a CHIP-8 ROM file.
 
-To try it running in your browser, visit https://timendus.github.io/silicon8/ and drag a CHIP-8 ROM file onto the monitor.
+Please note that it is not perfect, and you may run into some bugs. Especially when the auto-detection fails to detect SCHIP and XO-CHIP programs. More about that [below](#august-2021).
 
-In the console, using NodeJS:
-
-```bash
-git clone [email protected]:Timendus/silicon8.git
-cd silicon8
-./run.js ./tests/abc.ch8 # Should run the interpreter with a given CHIP-8 binary
-```
-
-Key `Q` or `Ctrl+C` exits the interpreter.
-
-### How to serve the website
-
-```bash
-npm install
-npm run serve # Should serve the web version on localhost:8080
-```
-
-### How to build
-
-```bash
-brew install tinygo # Or use your own favourite package manager
-npm run build # Should rebuild the WebAssembly Go module
-```
-
-### How to test
-
-```bash
-npm install
-npm test # Should run the tests
-```
+This is my first experiment with both WebAssembly and Go. So I'll probably look
+back on this repository with shame in a very short amount of time 😉 But that's
+the point of this, this is a learning project for me.
 
 ## Development log
 
@@ -74,6 +42,8 @@ present, so I decided to start writing some automated tests. After about a week
 of writing tests and fixing bugs here and there, on and off, I think I now feel
 kind of safe saying that the interpreter works as it should for CHIP-8.
 
+![Space Invaders by David Winter, although that has a bug in and of itself](console.png)
+
 Also, I added a web-based front-end for the interpreter that works nicer and
 looks better than the console based version.
 
@@ -97,6 +67,75 @@ still expect to be run on SCHIP with all the quirks of that platform, for
 example. Same with developers writing programs for XO-CHIP without actually
 using anything beyond CHIP-8 and SCHIP instructions. No way to tell.
 
+### Second half of August 2021
+
+After doing a pretty big refactor, the host environment now just has to call the
+`clockTick` function 60 times per second, and it will get a callback with the
+new image to display when the screen has been updated. This is a much cleaner
+solution that doesn't require as much knowledge of the interpreter internals on
+the host side.
+
+Also, as mentioned above, the image that the host environment receives is now a
+colour image (three bytes per pixel), which has allowed me to more easily
+implement XO-CHIPs four colour mode. Beyond that, I added the option to draw 16
+colours to the screen using four planes. [John
+Earnest](https://github.com/JohnEarnest) mentions this posibility in [his
+proposal for XO-CHIP](https://github.com/JohnEarnest/Octo/blob/gh-pages/docs/XO-ChipSpecification.md),
+but Octo doesn't implement it:
+
+> Encoding is chosen such that it would be possible to provide 4 bitplanes (and
+> thus 16 colors!) in the future should it prove necessary.
+
+Although I'm not quire sure I would call it necessary, it's certainly cool.
+
+![Showing 16 colours in Silicon8](colours.png)
+
+To properly test all the display stuff I added two expectations to Jest that
+allow me to capture the contents of the display in a BMP file, and then test
+against that file. This allows for easy and quick visual inspection to see if
+the test results in the right image, and to be alerted when anything breaks
+that.
+
+Finally, I made ["Pixel Studio"](https://timendus.github.io/silicon8/pixel-studio/)
+to convert images to sprite data in a what-you-see-is-what-you-get type of way.
+It supports one through four planes of colour, all possible sprite sizes and
+optional dithering.
+
+## Developer instructions
+
+### How to run
+
+In the console, using NodeJS:
+
+```bash
+git clone [email protected]:Timendus/silicon8.git
+cd silicon8
+./run.js ./tests/abc.ch8 # Should run the interpreter with a given CHIP-8 binary
+```
+
+Key `Q` or `Ctrl+C` exits the interpreter.
+
+### How to serve the website
+
+```bash
+npm install
+npm run serve # Should serve the web version on localhost:8080
+```
+
+### How to build
+
+```bash
+brew install tinygo # Or use your own favourite package manager
+npm run build # Should rebuild the WebAssembly Go module
+```
+
+### How to test
+
+```bash
+npm install
+npm test # Should run the tests
+```
+
 ## TODO
 
 In no particular order 😉
@@ -106,5 +145,6 @@ interpreter type
 * [ ] Write more tests for SCHIP and XO-CHIP instructions
 * [ ] Rewrite scroll routines to scroll selected plane(s)
 * [ ] Re-implement clipQuirk in draw function
-* [ ] Properly skip over i := long 0xNNNN
+* [ ] Properly skip over `i := long 0xNNNN`
 * [ ] Implement XO-CHIP's `audio`
+* [ ] Fix exception when input image doesn't align with sprite size in Pixel Studio