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] 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.