From d65f587f69ff5569223b77ac6f4b2e3500512252 Mon Sep 17 00:00:00 2001
From: IrgendwerA8 <c.krueger.b@web.de>
Date: Sat, 27 Aug 2016 22:02:08 +0200
Subject: [PATCH] Internal/screen character mapping: Supressed warnings for
 re-map and added documentation.

---
 doc/atari.sgml                 | 52 ++++++++++++++++++++++++++++++++++
 include/atari_screen_charmap.h |  8 +++++-
 2 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/doc/atari.sgml b/doc/atari.sgml
index e65a7869e..54f3aab78 100644
--- a/doc/atari.sgml
+++ b/doc/atari.sgml
@@ -318,6 +318,58 @@ chip registers.
 </descrip><p>
 
 
+<sect1>Character mapping<p>
+
+The Atari has two representations for characters:
+<enum>
+<item> ATASCII is character mapping which is similar to ASCII and used
+by the CIO system of the OS. This is the default mapping of cc65 when
+producing code for the atari target.
+<item> The internal/screen mapping represents the real value of the
+screen ram when showing a character.
+</enum>
+
+For direct memory access (simplicity and speed) enabling the internal
+mapping can be useful. This can be achieved by including the
+"<tt/atari_screen_charmap.h/" header.
+
+A word of caution: Since the <tt/0x00/ character has to be mapped in an
+incompatible way to the C-standard, the usage of string functions in
+conjunction with internal character mapped strings delivers unexpected
+results regarding the string length. The end of strings are detected where
+you may not expect them (to early or (much) to late). Internal mapped
+strings typically support the "<tt/mem...()/" functions.
+
+<em>For assembler sources the macro "<tt/scrcode/" from the "<tt/atari.mac/"
+package delivers the same feature.</em>
+
+You can switch back to the ATASCII mapping by including
+"<tt/atari_atascii_charmap.h/".
+
+A final note: Since cc65 has currently some difficulties with string merging
+under different mappings, defining remapped strings works only flawlessly
+with static array initialization:
+
+<verb>
+#include &lt;atari\_screen\_charmap.h&gt;
+char pcScreenMappingString[] = "Hello Atari!";
+
+#include &lt;atari_atascii_charmap.h&gt;
+char pcAtasciiMappingString[] = "Hello Atari!";
+</verb>
+
+delivers correct results, while
+
+<verb>
+#include &lt;atari_screen_charmap.h&gt;
+char* pcScreenMappingString = "Hello Atari!";
+
+#include &lt;atari_atascii_charmap.h&gt;
+char* pcAtasciiMappingString = "Hello Atari!";
+</verb>
+
+does not.
+
 
 <sect>Loadable drivers<p>
 
diff --git a/include/atari_screen_charmap.h b/include/atari_screen_charmap.h
index 4a76d479a..78051584f 100644
--- a/include/atari_screen_charmap.h
+++ b/include/atari_screen_charmap.h
@@ -30,7 +30,10 @@
 
 /* No include guard here! Multiple use in one file may be intentional. */
 
+#pragma warn (remap-zero, push, off)
 #pragma charmap (0x00, 0x40)
+#pragma warn (remap-zero, pop)
+
 #pragma charmap (0x01, 0x41)
 #pragma charmap (0x02, 0x42)
 #pragma charmap (0x03, 0x43)
@@ -64,7 +67,10 @@
 #pragma charmap (0x1E, 0x5E)
 #pragma charmap (0x1F, 0x5F)
 
-#pragma charmap (0x20, 0x00) 
+#pragma warn (remap-zero, push, off)
+#pragma charmap (0x20, 0x00)
+#pragma warn (remap-zero, pop)
+
 #pragma charmap (0x21, 0x01)
 #pragma charmap (0x22, 0x02)
 #pragma charmap (0x23, 0x03)