From 6b685dcaa32468a9b6cd29e8ffbc4a4bd3598d9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= <ondra@ondrovo.com>
Date: Wed, 7 Oct 2020 15:28:13 +0200
Subject: [PATCH] add docs for the screen module

---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 48 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ef0c163..43d9ad5 100644
--- a/README.md
+++ b/README.md
@@ -393,6 +393,52 @@ To delete a stack, drop its handle - `(drop @REG)`
 
 This module uses the minifb rust crate to provide a framebuffer with key and mouse input.
 
-Documentation TBD, see the extension's source code or the example programs
+Colors use the `RRGGBB` hex format.
 
-.
+If input events are required, then make sure to periodically call `(sc-blit)` or `(sc-poll)`.
+This may not be needed if the auto-blit function is enabled and the display is regularly written.
+
+The default settings are 60 FPS and auto-blit enabled.
+
+NOTE: Logging can significantly reduce crsn run speed.
+Make sure the log level is at not set to "trace" when you need high-speed updates, 
+such as animations.
+
+```
+; Initialize the screen (opens a window)
+(sc-init WIDTH HEIGHT)
+
+; Erase the screen (fill with black)
+(sc-erase)
+; Fill with a custom color
+(sc-erase 0xFF00FF)
+
+; Set pixel color
+(sc-px X Y COLOR)
+
+; Set screen option
+; 1 ... auto-blit (blit automatically on pixel write when needed to achieve the target FPS)
+; 2 ... frame rate
+(sc-opt OPTION VALUE)
+
+; Blit (render the pixel buffer).
+; This function also updates key and mouse states and handles the window close button
+(sc-blit)
+; Blit if needed (when the auto-blit function is enabled)
+(sc-blit 0)
+
+; Update key and mouse state, handle the window close button
+(sc-poll)
+
+; Read mouse position into two registers.
+; Sets the overflow flag if the cursour is out of the window
+(sc-mouse X Y)
+
+; Check key status. Keys are 0-127. Reads 1 if the key is pressed, 0 if not.
+; A list of supported keys can be found in the extension source code.
+(sc-key PRESSED KEY)
+
+; Check mouse button state
+; 0-left, 1-right, 2-middle
+(sc-mbtn PRESSED BTN)
+```