From be2d14562f064d56574ed2aa65c960861b02b3ca Mon Sep 17 00:00:00 2001
From: Svjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Date: Sun, 27 Oct 2024 16:19:54 +0200
Subject: [PATCH] Adding better code documentation.

---
 Graphics/Animations/txtpal.bas | 78 ++++++++++++++++++++++++----------
 1 file changed, 56 insertions(+), 22 deletions(-)

diff --git a/Graphics/Animations/txtpal.bas b/Graphics/Animations/txtpal.bas
index 9ab2e56..973a299 100755
--- a/Graphics/Animations/txtpal.bas
+++ b/Graphics/Animations/txtpal.bas
@@ -1,33 +1,56 @@
-' Svjatoslav Agejenko 2003.01
-' svjatoslav@svjatoslav.eu
+' This application produces beautiful colorful horizontal rainbows on the screen in text mode.
+' It works only on CRT monitors, because it accomplishes the effect by changing the color palette
+' while the CRT monitor is drawing the screen. As a result, unlimited number of colors can be
+' displayed on the screen simultaneously, regardless of the video card's color depth.
+'
+' By Svjatoslav Agejenko.
+' Email: svjatoslav@svjatoslav.eu
+' Homepage: http://www.svjatoslav.eu
+
+' Changelog:
+' 2003.01, Initial version
+' 2024, Improved program readability
 
 DEFINT A-Z
 CLS
 COLOR 7
 
+' Fill background with random colored random numbers.
 FOR b = 1 TO 500
-COLOR RND * 15
-PRINT RND;
+    COLOR RND * 15
+    PRINT RND;
 NEXT b
 
+' Set the background and text colors
 COLOR 0, 1
+
+' Clear rectangular area
 FOR y = 5 TO 20
-FOR x = 20 TO 50
-LOCATE y, x
-PRINT " "
-NEXT x
+    FOR x = 20 TO 50
+        LOCATE y, x
+        PRINT " "
+    NEXT x
 NEXT y
+
+' Print "[ TEST ]" at position (10, 25)
 LOCATE 10, 25
 PRINT "[ TEST ]"
 
+' Print "[ TEST ]" in color 2 at position (15, 37)
 LOCATE 15, 37
 COLOR 2
 PRINT "[ TEST ]"
 
+' Initialize variables
 wa = 1
 p = &H3DA
+
+' Loop to wait until CRT monitor has drawn single frame
 1
+' measure how much time was spent waiting for screen redraw to complete
 w = w + 1
+
+' Check if monitor is still drawing frame
 a = INP(p)
 IF a >= 128 THEN a = a - 128
 IF a >= 64 THEN a = a - 64
@@ -38,30 +61,41 @@ IF a < 8 THEN GOTO 1
 frm = frm + 1
 IF frm > 10000 THEN frm = -10000
 
-
+' Adjust the color palette change speed so that it takes approximately all of the time
+' when Ray is actually moving along screen surface and is drawing pixels.
+' So if we had to wait too long for drawing to complete at the end, it means
+' next frame we can be slower with our palette updates.
 IF w > 300 THEN wa = wa + 1 ELSE wa = wa - 1
 IF w < 250 THEN wa = wa - 5
 IF w > 3000 THEN wa = wa + 30
 IF w > 1000 THEN wa = wa + 5
 
+' Check if a key has been pressed
 IF INKEY$ <> "" THEN
-  OUT &H3C8, 0
-  OUT &H3C9, 0
-  OUT &H3C9, 0
-  OUT &H3C9, 0
-  SYSTEM
+    ' Reset color palette
+    OUT &H3C8, 0
+    OUT &H3C9, 0
+    OUT &H3C9, 0
+    OUT &H3C9, 0
+    ' exit application
+    SYSTEM
 END IF
 
+' Alter video graphics color palette while CRT screen in drawing scanlines simultaneously
 FOR a = 0 TO 70
-  b = a * 6 + frm
-  OUT &H3C8, 0
-  OUT &H3C9, SIN(b / 20) * 30 + 30
-  OUT &H3C9, SIN(b / 27) * 30 + 30
-  OUT &H3C9, SIN(b / 31) * 30 + 30
-  FOR u = 1 TO wa
-  NEXT u
+
+    b = a * 6 + frm
+
+    ' Alter palette within video card
+    OUT &H3C8, 0
+    OUT &H3C9, SIN(b / 20) * 30 + 30
+    OUT &H3C9, SIN(b / 27) * 30 + 30
+    OUT &H3C9, SIN(b / 31) * 30 + 30
+
+    ' Delay to give time for CRT screen to complete horizontal scanlines
+    FOR u = 1 TO wa
+    NEXT u
 NEXT a
 
 w = 0
 GOTO 1
-
-- 
2.20.1