From 15ba54eb77ca895b7e0b9235df121a5c0c08d41e Mon Sep 17 00:00:00 2001
From: Thomas Bernard <miniupnp@free.fr>
Date: Tue, 15 Dec 2020 23:34:43 +0100
Subject: [PATCH] picview.asm: improve documentation

---
 misc/c64viewer/README      | 31 ------------------------
 misc/c64viewer/README.md   | 49 ++++++++++++++++++++++++++++++++++++++
 misc/c64viewer/picview.asm | 23 ++++++++++++++++--
 3 files changed, 70 insertions(+), 33 deletions(-)
 delete mode 100644 misc/c64viewer/README
 create mode 100644 misc/c64viewer/README.md

diff --git a/misc/c64viewer/README b/misc/c64viewer/README
deleted file mode 100644
index 3fa35606..00000000
--- a/misc/c64viewer/README
+++ /dev/null
@@ -1,31 +0,0 @@
-XX format => text/bitmap color/multicolor / extended background mode
-
-$D020, 15 octets :
-BO BORDER
-BA BACKGROUND
-E1 Extra background color #1
-E2 Extra background color #2
-E3 Extra background color #3
-SE1 sprite extra color #1
-SE2 sprite extra color #2
-S0 sprite #0
-S1 sprite #1
-S2 sprite #2
-S3 sprite #3
-S4 sprite #4
-S5 sprite #5
-S6 sprite #6
-S7 sprite #7
-
-TP
-T = type
-    0 - end of file
-    1 - bitmap
-    2 - screen ram
-	3 - color ram
-	4 - border/background etc.
-P = packing
-    0 - no packing
-    1 - RLE packing
-    2 - color ram RLE packing
-
diff --git a/misc/c64viewer/README.md b/misc/c64viewer/README.md
new file mode 100644
index 00000000..68fe5370
--- /dev/null
+++ b/misc/c64viewer/README.md
@@ -0,0 +1,49 @@
+# picview.asm (c) 2019 Thomas Bernard
+
+This is a C64 image depacker and viewer designed to build self-displaying
+.prg pictures files.
+One has to concatenate the data to the viewer machine code to build a .prg
+file.
+
+## Data format
+-  1 byte for mode
+-  then one or several blocks, composed of :
+   1.  1 byte TP header :
+       - upper nibble T is type
+       - lower nibble P is packing
+   2.  n bytes data load, depending of type and packing
+
+### Mode byte
+0EBM0000 E=Extended Background mode. B=Bitmap Mode. M=Multicolor.
+
+### TP byte
+- T = type
+  - 0 - end of file
+  - 1 - bitmap                  8000 bytes
+  - 2 - screen ram              1000 bytes
+  - 3 - color ram               1000 bytes at $D800
+  - 4 - border/background etc.  15 bytes at $D020
+- P = packing
+  - 0 - no packing
+  - 1 - RLE packing
+  - 2 - color ram RLE packing
+
+All other values are reserved.
+
+
+## border/backgrounds at $D020, 15 bytes
+- BO BORDER
+- BA BACKGROUND
+- E1 Extra background color #1
+- E2 Extra background color #2
+- E3 Extra background color #3
+- SE1 sprite extra color #1
+- SE2 sprite extra color #2
+- S0 sprite #0
+- S1 sprite #1
+- S2 sprite #2
+- S3 sprite #3
+- S4 sprite #4
+- S5 sprite #5
+- S6 sprite #6
+- S7 sprite #7
diff --git a/misc/c64viewer/picview.asm b/misc/c64viewer/picview.asm
index fba71494..2aca406e 100644
--- a/misc/c64viewer/picview.asm
+++ b/misc/c64viewer/picview.asm
@@ -1,14 +1,33 @@
 ; vim:ts=8 sw=8:
 ;  Grafx2 - The Ultimate 256-color bitmap paint program
 ;
-;	Copyright owned by various GrafX2 authors, see COPYRIGHT.txt for details.
+; Copyright owned by various GrafX2 authors, see COPYRIGHT.txt for details.
 ;
 ; This code is embedded in C64 images saved by GrafX2, it can be distributed
 ; and modified without any restrictions.
+;
+; Designed to be built with The Ophis Assembler :
+; https://michaelcmartin.github.io/Ophis/
+; C64 picture unpacker and viewer.
+; - Supports all VIC-II modes, character or bitmap based.
+; - Supports raw data, RLE packing and specific color RAM RLE packing
+;
+; Memory map :
+; $0002       Low byte of count
+; $00FC-$00FD Data pointer
+; $0801-$080C Basic program : trampoline code
+; $080D-$xxxx 6502 machine language code
+; $xxxx-$xxxx (packed) picture data
+; $C000-$C3E8 Screen RAM               \
+; $C3F0-$C3FF VIC-II $D020-$D02E backup )- Upper RAM area
+; $C400-$C7FF Color RAM backup         /
+; $D000-$D02E VIC-II registers (writes from $D020 to $D02E)
+; $D800-$DBFF Color RAM
+; $E000-$FF40 Bitmap (behind KERNAL ROM)
 .word $0801
 .org  $0801
 	.word next, 1911	; next basic line and line number
-	.byte $9e,"2061",0	; SYS2061 
+	.byte $9e,"2061",0	; SYS2061
 next:	.word 0			; end of basic program
 
 	; $fb $fc $fd $fe => unused