From 55742003d63664c47b0dab179a0e7c3f0e8a1414 Mon Sep 17 00:00:00 2001
From: mrdudz <mrdudz@users.noreply.github.com>
Date: Tue, 17 Jun 2025 21:40:04 +0200
Subject: [PATCH 1/3] add some more comments

---
 include/tgi.h              | 9 +++++----
 libsrc/apple2/tgi_colors.s | 1 +
 libsrc/common/tgi_colors.s | 1 +
 libsrc/lynx/tgi_colors.s   | 1 +
 libsrc/tgi/tgi-kernel.s    | 2 +-
 libsrc/tgi/tgi_getcolor.s  | 2 +-
 libsrc/tgi/tgi_setcolor.s  | 4 ++--
 7 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/include/tgi.h b/include/tgi.h
index 2ef65b856..ecd98e6e8 100644
--- a/include/tgi.h
+++ b/include/tgi.h
@@ -141,15 +141,16 @@ unsigned char tgi_getmaxcolor (void);
 ** then be getmaxcolor()+1).
 */
 
-void __fastcall__ tgi_setcolor (unsigned char color);
-/* Set the current drawing color. */
+void __fastcall__ tgi_setcolor (unsigned char color_index);
+/* Set the current drawing color (palette index). */
 
 unsigned char tgi_getcolor (void);
-/* Return the current drawing color. */
+/* Return the current drawing color (palette index). */
 
 void __fastcall__ tgi_setpalette (const unsigned char* palette);
 /* Set the palette (not available with all drivers/hardware). palette is
-** a pointer to as many entries as there are colors.
+** a pointer to as many entries as there are colors required for the drivers
+** palette. This palette is the (only) place where to use the TGI_COLOR values.
 */
 
 const unsigned char* tgi_getpalette (void);
diff --git a/libsrc/apple2/tgi_colors.s b/libsrc/apple2/tgi_colors.s
index 53505b33d..936d89b76 100644
--- a/libsrc/apple2/tgi_colors.s
+++ b/libsrc/apple2/tgi_colors.s
@@ -1,6 +1,7 @@
 ;
 ; Target-specific black & white values for use by the target-shared TGI kernel
 ;
+; NOTE: These are indices into the default palette
 
         .include        "tgi-kernel.inc"
 
diff --git a/libsrc/common/tgi_colors.s b/libsrc/common/tgi_colors.s
index 6ef3729b4..ba14ffa09 100644
--- a/libsrc/common/tgi_colors.s
+++ b/libsrc/common/tgi_colors.s
@@ -1,6 +1,7 @@
 ;
 ; Target-specific black & white values for use by the target-shared TGI kernel
 ;
+; NOTE: These are indices into the default palette
 
         .include        "tgi-kernel.inc"
 
diff --git a/libsrc/lynx/tgi_colors.s b/libsrc/lynx/tgi_colors.s
index ebc8c2889..6d0ea442a 100644
--- a/libsrc/lynx/tgi_colors.s
+++ b/libsrc/lynx/tgi_colors.s
@@ -1,6 +1,7 @@
 ;
 ; Target-specific black & white values for use by the target-shared TGI kernel
 ;
+; NOTE: These are indices into the default palette
 
         .include        "tgi-kernel.inc"
 
diff --git a/libsrc/tgi/tgi-kernel.s b/libsrc/tgi/tgi-kernel.s
index cbd655279..c2d87b002 100644
--- a/libsrc/tgi/tgi-kernel.s
+++ b/libsrc/tgi/tgi-kernel.s
@@ -23,7 +23,7 @@ _tgi_error:         .res    1           ; Last error code
 _tgi_gmode:         .res    1           ; Flag: Graphics mode active
 _tgi_curx:          .res    2           ; Current drawing cursor X
 _tgi_cury:          .res    2           ; Current drawing cursor Y
-_tgi_color:         .res    1           ; Current drawing color
+_tgi_color:         .res    1           ; Current drawing color (palette index)
 _tgi_font:          .res    1           ; Which font to use
 _tgi_textdir:       .res    1           ; Current text direction
 _tgi_vectorfont:    .res    2           ; Pointer to vector font
diff --git a/libsrc/tgi/tgi_getcolor.s b/libsrc/tgi/tgi_getcolor.s
index c1c0022d0..95cf7d553 100644
--- a/libsrc/tgi/tgi_getcolor.s
+++ b/libsrc/tgi/tgi_getcolor.s
@@ -2,7 +2,7 @@
 ; Ullrich von Bassewitz, 22.06.2002
 ;
 ; unsigned char tgi_getcolor (void);
-; /* Return the current drawing color */
+; /* Return the current drawing color (palette index) */
 
 
         .include        "tgi-kernel.inc"
diff --git a/libsrc/tgi/tgi_setcolor.s b/libsrc/tgi/tgi_setcolor.s
index 16f075767..6f3bb1871 100644
--- a/libsrc/tgi/tgi_setcolor.s
+++ b/libsrc/tgi/tgi_setcolor.s
@@ -2,8 +2,8 @@
 ; 2002-06-21, Ullrich von Bassewitz
 ; 2020-06-04, Greg King
 ;
-; void __fastcall__ tgi_setcolor (unsigned char color);
-; /* Set the current drawing color */
+; void __fastcall__ tgi_setcolor (unsigned char color_index);
+; /* Set the current drawing color (palette index) */
 
 
         .include        "tgi-kernel.inc"

From 9edc396ce712e010392dc2ef60e39c846338e0fd Mon Sep 17 00:00:00 2001
From: mrdudz <mrdudz@users.noreply.github.com>
Date: Tue, 17 Jun 2025 22:27:47 +0200
Subject: [PATCH 2/3] fix TGI docs a bit

---
 doc/tgi.sgml | 56 ++++++++++++++++++++++++++++------------------------
 1 file changed, 30 insertions(+), 26 deletions(-)

diff --git a/doc/tgi.sgml b/doc/tgi.sgml
index 3b013664f..182ce2807 100644
--- a/doc/tgi.sgml
+++ b/doc/tgi.sgml
@@ -43,7 +43,7 @@ of range.
 <ref id="tgi_setcolor" name="tgi_setcolor">
 <tag/Example/<tscreen><verb>
 /* Draw the upper half of an ellipse */
-tgi_setcolor(TGI_COLOR_BLUE);
+tgi_setcolor(1);
 tgi_arc (50, 50, 40, 20, 0, 180);
 </verb></tscreen>
 </descrip>
@@ -67,7 +67,7 @@ be used in presence of a prototype.
 <tag/Availability/cc65
 <tag/See also/Other tgi function
 <tag/Example/<tscreen><verb>
-tgi_setcolor(TGI_COLOR_GREEN);
+tgi_setcolor(1);
 tgi_bar(10, 10, 100, 60);
 </verb></tscreen>
 </descrip>
@@ -94,7 +94,7 @@ be used in presence of a prototype.
 <ref id="tgi_pieslice" name="tgi_pieslice">,
 <ref id="tgi_setcolor" name="tgi_setcolor">
 <tag/Example/<tscreen><verb>
-tgi_setcolor(TGI_COLOR_BLACK);
+tgi_setcolor(1);
 tgi_circle(50, 40, 40);
 </verb></tscreen>
 </descrip>
@@ -154,7 +154,7 @@ be used in presence of a prototype.
 <ref id="tgi_pieslice" name="tgi_pieslice">,
 <ref id="tgi_setcolor" name="tgi_setcolor">
 <tag/Example/<tscreen><verb>
-tgi_setcolor(TGI_COLOR_RED);
+tgi_setcolor(1);
 tgi_ellipse (50, 40, 40, 20);
 </verb></tscreen>
 </descrip>
@@ -216,17 +216,15 @@ original aspect ratio.
 
 <quote>
 <descrip>
-<tag/Function/Return the current drawing color.
+<tag/Function/Return the current drawing color (palette index).
 <tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
 <tag/Declaration/<tt/unsigned char tgi_getcolor (void);/
 <tag/Description/The actual color is an index to a palette. During tgi_init
-you will get a default palette. The number of colors depend on the platform.
-All platforms recognize at least TGI_COLOR_BLACK and TGI_COLOR_WHITE. But some
-platforms have many more predefined colors. If you paint using TGI_COLOR_GREEN
-and then you change the green of the palette to blue using tgi_setpalette then
-after this painting in TGI_COLOR_GREEN will actually be blue.
+you will get a default palette. Note that both the number of colors, and also
+the available colors, depend on the platform.
 <tag/Availability/cc65
-<tag/See also/Other tgi functions
+<tag/See also/<ref id="tgi_setcolor" name="tgi_setcolor">,
+<ref id="tgi_setpalette" name="tgi_setpalette">
 <tag/Example/<tscreen><verb>
 color = tgi_getcolor();
 </verb></tscreen>
@@ -238,7 +236,8 @@ color = tgi_getcolor();
 
 <quote>
 <descrip>
-<tag/Function/Get the number of available colors.
+<tag/Function/Get the number of available colors in the palette for the current
+driver.
 <tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
 <tag/Declaration/<tt/unsigned char tgi_getcolorcount (void);/
 <tag/Description/TGI platforms use indexed color palettes. This function
@@ -287,8 +286,6 @@ if (num_colors == 0) {
 <tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
 <tag/Declaration/<tt/const unsigned char* tgi_getdefpalette (void);/
 <tag/Description/The tgi driver has a default palette that is active at startup.
-The named colors TGI_COLOR_BLACK, TGI_COLOR_WHITE, TGI_COLOR_RED... need this
-palette to work correctly.
 <tag/Availability/cc65
 <tag/See also/Other tgi functions
 <tag/Example/None.
@@ -418,10 +415,10 @@ be used in presence of a prototype.
 
 <quote>
 <descrip>
-<tag/Function/Get the color of a pixel from the viewpage.
+<tag/Function/Get the color (palette index) of a pixel from the viewpage.
 <tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
 <tag/Declaration/<tt/unsigned char __fastcall__ tgi_getpixel (int x, int y);/
-<tag/Description/Get the color of a pixel from the viewpage.
+<tag/Description/Get the color (palette index) of a pixel from the viewpage.
 <tag/Notes/<itemize>
 <item>The function is only available as fastcall function, so it may only
 be used in presence of a prototype.
@@ -626,7 +623,7 @@ be used in presence of a prototype.
 #define tgi_updatedisplay() tgi_ioctl(4, (void*)1)
 if (!tgi_busy()) {
   tgi_sprite(&amp;background);
-  tgi_setcolor(TGI_COLOR_BLUE);
+  tgi_setcolor(1);
   tgi_outttextxy(20,40,"Hello World");
   tgi_updatedisplay();
 }
@@ -791,7 +788,7 @@ of range.
 <ref id="tgi_setcolor" name="tgi_setcolor">
 <tag/Example/<tscreen><verb>
 /* Draw the closed upper half of an ellipse */
-tgi_setcolor(TGI_COLOR_BLUE);
+tgi_setcolor(1);
 tgi_pieslice (50, 50, 40, 20, 0, 180);
 </verb></tscreen>
 </descrip>
@@ -834,20 +831,21 @@ only in the presence of a prototype.
 
 <quote>
 <descrip>
-<tag/Function/Set color to be used in future draw operations.
+<tag/Function/Set color (palette index) to be used in future draw operations.
 <tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
-<tag/Declaration/<tt/void __fastcall__ tgi_setcolor (unsigned char color);/
-<tag/Description/Set color to be used in future draw operations.
+<tag/Declaration/<tt/void __fastcall__ tgi_setcolor (unsigned char color_index);/
+<tag/Description/Set color (palette index) to be used in future draw operations.
 <tag/Notes/<itemize>
 <item>The function is only available as fastcall function, so it may only
 be used in presence of a prototype.
 </itemize>
 <tag/Availability/cc65
-<tag/See also/Other tgi functions.
+<tag/See also/<ref id="tgi_getcolor" name="tgi_getcolor">,
+<ref id="tgi_setpalette" name="tgi_setpalette">
 <tag/Example/<tscreen><verb>
-tgi_setcolor(TGI_COLOR_BLACK);
+tgi_setcolor(1);
 tgi_bar(0,0,30,30);
-tgi_setcolor(TGI_COLOR_WHITE);
+tgi_setcolor(2);
 tgi_bar(10,10,20,20);
 </verb></tscreen>
 </descrip>
@@ -893,13 +891,19 @@ Palette is a pointer to as many entries as there are colors.
 <tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
 <tag/Declaration/<tt/void __fastcall__ tgi_setpalette (const unsigned char* palette);/
 <tag/Description/Set the palette (not available with all drivers/hardware).
-Palette is a pointer to as many entries as there are colors.
+Palette is a pointer to as many entries as there are colors. The values in the
+palette are target specific, some (hopefully, more or less) portable values are
+defined in the TGI_COLOR_XY defines.
 <tag/Notes/<itemize>
 <item>The function is only available as fastcall function, so it may only
 be used in presence of a prototype.
+<item>The palette is the (only) place where to use the TGI_COLOR_XY values. This
+has been an ongoing and reoccurring misunderstanding in the past: At every other
+place, the "color" values are indices into the current palette.
 </itemize>
 <tag/Availability/cc65
-<tag/See also/Other tgi functions.
+<tag/See also/<ref id="tgi_setcolor" name="tgi_setcolor">,
+<ref id="tgi_getpalette" name="tgi_getpalette">
 <tag/Example/None.
 </descrip>
 </quote>

From 8d763abe9298d9f567f8141fed38d1ed11f76ce2 Mon Sep 17 00:00:00 2001
From: mrdudz <mrdudz@users.noreply.github.com>
Date: Thu, 19 Jun 2025 19:58:36 +0200
Subject: [PATCH 3/3] Add notes on TGI_COLOR_BLACK and TGI_COLOR_WHITE

---
 doc/tgi.sgml | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/doc/tgi.sgml b/doc/tgi.sgml
index 182ce2807..96709ae31 100644
--- a/doc/tgi.sgml
+++ b/doc/tgi.sgml
@@ -220,8 +220,12 @@ original aspect ratio.
 <tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
 <tag/Declaration/<tt/unsigned char tgi_getcolor (void);/
 <tag/Description/The actual color is an index to a palette. During tgi_init
-you will get a default palette. Note that both the number of colors, and also
-the available colors, depend on the platform.
+you will get a default palette.
+A default palette has always two entries with values equal to TGI_COLOR_BLACK
+and TGI_COLOR_WHITE. However, which default palette entries have those two
+values is target specific.
+Note that both the number of colors, and also the available colors, depend on
+the target and/or driver.
 <tag/Availability/cc65
 <tag/See also/<ref id="tgi_setcolor" name="tgi_setcolor">,
 <ref id="tgi_setpalette" name="tgi_setpalette">
@@ -893,7 +897,9 @@ Palette is a pointer to as many entries as there are colors.
 <tag/Description/Set the palette (not available with all drivers/hardware).
 Palette is a pointer to as many entries as there are colors. The values in the
 palette are target specific, some (hopefully, more or less) portable values are
-defined in the TGI_COLOR_XY defines.
+defined in the TGI_COLOR_XY defines. Note that different platforms provide
+different colors, only TGI_COLOR_BLACK and TGI_COLOR_WHITE are guaranteed to
+exist (needed for the default palette).
 <tag/Notes/<itemize>
 <item>The function is only available as fastcall function, so it may only
 be used in presence of a prototype.