Clarify and document `charput` in `emulator/charput.inc`: added detailed comments...

diff --git a/emulator/charput.inc b/emulator/charput.inc
index 95b395f..4572389 100644 (file)
--- a/emulator/charput.inc
+++ b/emulator/charput.inc
@@ -1,66 +1,102 @@
-; part of virtual processor, emulator for FIFTH\r
-\r
-xcharput:\r
-       mov     eax, [es:edi]   ; chary\r
-       mov     [chary], eax\r
-       mov     ecx, [es:edi+4] ; charx\r
-       mov     eax, [es:edi+8] ; addrdest\r
-       add     eax, [xms_addr]\r
-       mov     ebx, [es:eax]\r
-       mov     [sizex], ebx\r
-       add     eax, 8\r
-       add     eax, ecx\r
-       push    eax\r
-       sub     edx, edx\r
-       mov     eax, [chary]\r
-       mul     dword [sizex]\r
-       pop     ebx\r
-       add     eax, ebx\r
-       mov     [addrdst], eax\r
-       mov     eax, [es:edi+12]\r
-       add     eax, [xms_addr]\r
-       mov     [addrsrc], eax\r
-       mov     al, [es:edi+16]\r
-       mov     [colorbg], al\r
-       mov     al, [es:edi+20]\r
-       mov     [colorfg], al\r
-       add     edi, 24\r
-\r
-       mov     [linenum], 8\r
-charl1:\r
-       mov     eax, [addrsrc]\r
-       mov     bx, [es:eax]\r
-       mov     edx, [addrdst]\r
-       mov     cx, 8\r
-charl2:\r
-       dec     cx\r
-       bt      bx, cx\r
-       jnc     charl3\r
-       mov     al, [colorfg]\r
-       jmp     charl4\r
-charl3:\r
-       mov     al, [colorbg]\r
-charl4:\r
-       mov     [es:edx], al\r
-       inc     edx\r
-       cmp     cx, 0\r
-       jne      charl2\r
-\r
-       mov     eax, [sizex]\r
-       add     [addrdst], eax\r
-       inc     [addrsrc]\r
-       dec     [linenum]\r
-       mov     al, [linenum]\r
-       cmp     al, 0\r
-       jne     charl1\r
-\r
-       jmp     emu\r
-\r
-colorfg db 0\r
-colorbg db 0\r
-charx  dd 0\r
-chary  dd 0\r
-addrsrc dd 0\r
-addrdst dd 0\r
-sizex  dd 0\r
-linenum db 0\r
+; Draw character
+;
+; Stack Effect: colorfg colorbg addrsrc addrdest x y --
+;
+; Draws an 8x8 character from a source memory buffer to a destination
+; image buffer at the specified (x, y) coordinates. Each byte in the
+; source buffer represents one row of the character (8 bits per row),
+; where each bit determines whether to use the foreground or background
+; color for that pixel.
+;
+; Parameters:
+; - colorfg: Foreground color value (0-255)
+; - colorbg: Background color value (0-255)
+; - addrsrc: Memory address pointing to 8 bytes of character data
+; - addrdest: Base address of the destination image buffer
+; - x: X-coordinate (0-based) where the character's left edge starts
+; - y: Y-coordinate (0-based) where the character's top edge starts
+;
+; Example:
+;   0xFF  ; White foreground
+;   0x00  ; Black background
+;   0x3000  ; Character data address
+;   0x5000  ; Video memory address
+;   20      ; y
+;   10      ; x
+;   charput
+;
+; Memory layout before execution:
+;   [es:edi] = y
+;   [es:edi+4] = x
+;   [es:edi+8] = addrdest
+;   [es:edi+12] = addrsrc
+;   [es:edi+16] = colorbg
+;   [es:edi+20] = colorfg
+;
+; Memory layout after execution:
+;   Character drawn at (x, y) in destination image
+
+xcharput:
+       mov     eax, [es:edi]   ; chary
+       mov     [chary], eax
+       mov     ecx, [es:edi+4] ; charx
+       mov     eax, [es:edi+8] ; addrdest
+       add     eax, [xms_addr]
+       mov     ebx, [es:eax]
+       mov     [sizex], ebx
+       add     eax, 8
+       add     eax, ecx
+       push    eax
+       sub     edx, edx
+       mov     eax, [chary]
+       mul     dword [sizex]
+       pop     ebx
+       add     eax, ebx
+       mov     [addrdst], eax
+       mov     eax, [es:edi+12]
+       add     eax, [xms_addr]
+       mov     [addrsrc], eax
+       mov     al, [es:edi+16]
+       mov     [colorbg], al
+       mov     al, [es:edi+20]
+       mov     [colorfg], al
+       add     edi, 24
+
+       mov     [linenum], 8
+charl1:
+       mov     eax, [addrsrc]
+       mov     bx, [es:eax]
+       mov     edx, [addrdst]
+       mov     cx, 8
+charl2:
+       dec     cx
+       bt      bx, cx
+       jnc     charl3
+       mov     al, [colorfg]
+       jmp     charl4
+charl3:
+       mov     al, [colorbg]
+charl4:
+       mov     [es:edx], al
+       inc     edx
+       cmp     cx, 0
+       jne      charl2
+
+       mov     eax, [sizex]
+       add     [addrdst], eax
+       inc     [addrsrc]
+       dec     [linenum]
+       mov     al, [linenum]
+       cmp     al, 0
+       jne     charl1
+
+       jmp     emu
+
+colorfg db 0
+colorbg db 0
+charx  dd 0
+chary  dd 0
+addrsrc dd 0
+addrdst dd 0
+sizex  dd 0
+linenum db 0