From 9ab25ab94638476706ca0a2e8b68eb163bd0f3cf Mon Sep 17 00:00:00 2001
From: jan <jp333n@gmx.de>
Date: Mon, 16 Dec 2024 19:19:20 +0100
Subject: [PATCH] Copied parts of the README to the document

---
 README.md                              |  2 +-
 sketch.svg => specification/sketch.svg |  0
 specification/specification.typ        | 66 ++++++++++++++++++++++----
 3 files changed, 59 insertions(+), 9 deletions(-)
 rename sketch.svg => specification/sketch.svg (100%)

diff --git a/README.md b/README.md
index 70679af..41620e7 100644
--- a/README.md
+++ b/README.md
@@ -56,7 +56,7 @@ It also means that there are no accelerators or tricks to help with performance.
 ### Setup
 Here is a sketch of all components of the virtual computer:
 
-![](sketch.svg)
+![](specification/sketch.svg)
 
 ### Instruction pointer
 
diff --git a/sketch.svg b/specification/sketch.svg
similarity index 100%
rename from sketch.svg
rename to specification/sketch.svg
diff --git a/specification/specification.typ b/specification/specification.typ
index a2f9c4d..914fb73 100644
--- a/specification/specification.typ
+++ b/specification/specification.typ
@@ -1,3 +1,4 @@
+#import "@preview/colorful-boxes:1.4.0":slanted-colorbox
 #set page(
 paper:"a4",
 background: rotate(24deg,
@@ -6,6 +7,12 @@ background: rotate(24deg,
   ]
 ))
 
+#let not-specified(txt) = slanted-colorbox(
+  title: "Not specified",
+  color: "gray",
+)[#txt]
+
+
 = SVC16: A Simple Virtual Computer
 
 == Motivation and Goals
@@ -26,16 +33,59 @@ It also means, that the performance characteristics must be the same.
 An emulator can either run the system at the intended speed, or it can not. 
 
 
-
 == General Principles
 
-== The Simulated System
-=== Screen and Colors 
-=== Input
-=== Synchronization
+Every value is represented as a (little-endian) unsigned 16-bit integer.
+That includes numbers, addresses, colors, the instruction pointer and the input.
+Booleans are represented as `u16` values as well: 0 for `false` and >0 for `true`. 
+Whenever an instruction writes out a boolean explicitly, it is guaranteed to represented as the number 1.
 
+All numerical operations that will appear in the instructions are wrapping operations. 
+This includes manipulations of the instruction pointer.
+
+Division by zero crashes the program.
+
+== The Simulated System
+#figure(
+  image("sketch.svg", width: 65%),
+  caption: [A sketch of all components of the virtual computer.],
+) <sketch>
+
+As seen in @sketch, the addressable memory contains one value for each address.
+There is a separate screen buffer of the same size as the main memory.
+The screen itself has a fixed resolution ($256 times 256$). 
+The instruction pointer is stored separately. 
+It always starts at zero. 
+
+=== Screen and Colors 
+The color of each pixel is represented with 16-bits using `RGB565`.
+The coordinate $(x,y)$ of the screen maps to the index $256 y + x$ in the screen buffer.
+The coordinate $(0,0)$ is in the upper left-hand corner. Changes to the screen-buffer are not reflected on the screen until the system is synchronized.
+
+#not-specified[
+- Colors do not have to be represented accurately (accessability options).
+- There is no rule for how scaling and aspect ratio might be handled.
+- It is not fixed what the screen shows before it is first synchronized.
+- A cursor can be shown on the window, as long as its position matches the mouse position passed to the system]
+
+=== Input
+The only supported inputs are the mouse position and the left and right mouse keys.
+This is because it makes it much easier to emulate the system consistently.
+
+The input the system sees is only allowed to change at synchronization.
+
+
+The input is represented with two values: the *position code* and the *key code*.
+The *position code* is the index of the pixel, the mouse is currently on. The *key code* is given by left_mouse+2*right_mouse. So it can have the values 0 1 2 or 3.
+
+Before the first synchronization, both input codes are zero.
+
+
+=== Synchronization
+When the console executes the *Sync* instruction, the screen buffer is drawn to the screen.
+It is not cleared. The system will be put to sleep until the beginning of the next frame. 
+The targeted timing is 30fps. There is a hard limit of 3000000 instructions per frame. 
+This means that if the Sync command has not been called for 3000000 instructions, it will be performed automatically.
+This can mean that an event (like a mouse click) is never handled.
 
 == Instruction Set
-
-
-