From 3dac4685e3d84bdf60d530e2bf6f5e5708fdcf99 Mon Sep 17 00:00:00 2001
From: Svjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Date: Tue, 17 Feb 2026 01:26:27 +0200
Subject: [PATCH] Clarify and document `charput` in `emulator/charput.inc`:
 added detailed comments on stack effects, parameters, memory layout, and
 usage example.

---
 emulator/charput.inc | 168 ++++++++++++++++++++++++++-----------------
 1 file changed, 102 insertions(+), 66 deletions(-)

diff --git a/emulator/charput.inc b/emulator/charput.inc
index 95b395f..4572389 100644
--- a/emulator/charput.inc
+++ b/emulator/charput.inc
@@ -1,66 +1,102 @@
-; part of virtual processor, emulator for FIFTH
-
-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
+; 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
-- 
2.20.1