Support for self explanatory KBCODE values

[cc65] / doc / atari.sgml

diff --git a/doc/atari.sgml b/doc/atari.sgml
index a0dbe2f471a4f9c84cdcc99cc8f8ce96071d7869..db76c673628fa62dddcad05b71bcea06e3f75086 100644 (file)
--- a/doc/atari.sgml
+++ b/doc/atari.sgml
@@ -1,12 +1,10 @@
 <!doctype linuxdoc system>
 
 <article>
-
 <title>Atari specific information for cc65
 <author>
 <url url="mailto:shawnjefferson@24fightingchickens.com" name="Shawn Jefferson"> and<newline>
 <url url="mailto:chris@groessler.org" name="Christian Groessler">
-<date>2014-04-24
 
 <abstract>
 An overview over the Atari runtime system as it is implemented for the cc65 C
@@ -317,6 +315,49 @@ chip registers.
 
 </descrip><p>
 
+<sect1>Display lists<p>
+
+A major feature of the Atari graphics chip "ANTIC" is to
+process instructions for the display generation.
+cc65 supports constructing these display lists by offering defines
+for the instructions. In conjunction with the "void"-variable extension
+of cc65, display lists can be created quite comfortable:
+
+<verb>
+...
+unsigned char ScreenMemory[100];
+
+void DisplayList =
+{
+    DL_BLK8,
+    DL_BLK8,
+    DL_BLK8,
+    DL_LMS(DL_CHR20x8x2),
+    ScreenMemory,
+    DL_CHR20x8x2,
+    DL_CHR20x8x2,
+    DL_CHR20x8x2,
+    DL_BLK4,
+    DL_CHR20x8x2,
+    DL_JVB
+};
+...
+POKEW(560,(unsigned int)&amp;DisplayList);      // SDLSTL
+...
+</verb>
+
+Please inspect the <tt/_antic.h/ header file to detemine the supported
+instruction names. Modifiers on instructions can be nested without need
+for an order:
+
+<tt/DL_LMS(DL_HSCROL(DL_VSCROL(DL_DLI(DL_MAP80x4x2))))/
+
+Please mind that ANTIC has memory alignment requirements for "player
+missile graphics"-data, font data, display lists and screen memory. Creation
+of a special linker configuration with appropriate aligned segments and
+switching to that segment in the c-code is usually neccessary. A more memory
+hungry solution consists in using the "<tt/posix_memalign()/" function in
+conjunction with copying your data to the allocated memory.
 
 <sect1>Character mapping<p>
 
@@ -351,7 +392,7 @@ under different mappings, defining remapped strings works only flawlessly
 with static array initialization:
 
 <verb>
-#include &lt;atari\_screen\_charmap.h&gt;
+#include &lt;atari_screen_charmap.h&gt;
 char pcScreenMappingString[] = "Hello Atari!";
 
 #include &lt;atari_atascii_charmap.h&gt;
@@ -370,6 +411,29 @@ char* pcAtasciiMappingString = "Hello Atari!";
 
 does not.
 
+<sect1>Keyboard codes<p>
+
+For direct keyboard scanning in conjunction with e.g. the OS location "CH" (764/$2FC),
+all keyboard codes are available as defined values on C and assembler side.
+
+Example:
+<verb>
+...
+    while (!kbhit());
+    switch (PEEK(764))
+    {
+        case KEY_RETURN:
+        ...
+        case KEY_SPACE:
+        ...
+        case KEY_1:
+        ...
+    }
+...
+</verb>
+
+You can find the C defines in the file "<tt/_pokey.h/" or "<tt/atari_pokey.inc/" for the assembler variant.
+
 
 <sect>Loadable drivers<p>
 
@@ -891,16 +955,16 @@ chunk #2 (RAM memory area).
 The contents of the new NEXEHDR and CHKHDR segments come from this
 file (split.s):
 <tscreen><verb>
-       .import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__
-       .import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__
+    .import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__
+    .import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__
 
-       .segment "NEXEHDR"
-       .word    __STARTUP_LOAD__
-       .word    __CODE_LOAD__ + __CODE_SIZE__ - 1
+    .segment "NEXEHDR"
+    .word    __STARTUP_LOAD__
+    .word    __CODE_LOAD__ + __CODE_SIZE__ - 1
 
-       .segment "CHKHDR"
-       .word    __RODATA_LOAD__
-       .word    __BSS_LOAD__ - 1
+    .segment "CHKHDR"
+    .word    __RODATA_LOAD__
+    .word    __BSS_LOAD__ - 1
 </verb></tscreen>
 <p>
 Compile with
@@ -967,16 +1031,16 @@ FEATURES {
 
 New contents for NEXEHDR and CHKHDR are needed (split2.s):
 <tscreen><verb>
-       .import __STARTUP_LOAD__, __BSS_LOAD__, __DATA_SIZE__
-       .import __DATA_LOAD__, __RODATA_LOAD__
+    .import __STARTUP_LOAD__, __BSS_LOAD__, __DATA_SIZE__
+    .import __DATA_LOAD__, __RODATA_LOAD__
 
-       .segment "NEXEHDR"
-       .word    __RODATA_LOAD__
-       .word    __DATA_LOAD__ + __DATA_SIZE__ - 1
+    .segment "NEXEHDR"
+    .word    __RODATA_LOAD__
+    .word    __DATA_LOAD__ + __DATA_SIZE__ - 1
 
-       .segment "CHKHDR"
-       .word    __STARTUP_LOAD__
-       .word    __BSS_LOAD__ - 1
+    .segment "CHKHDR"
+    .word    __STARTUP_LOAD__
+    .word    __BSS_LOAD__ - 1
 </verb></tscreen>
 
 Compile with
@@ -1055,14 +1119,14 @@ including commercial applications, and to alter it and redistribute it
 freely, subject to the following restrictions:
 
 <enum>
-<item> The origin of this software must not be misrepresented; you must not
-       claim that you wrote the original software. If you use this software
-       in a product, an acknowledgment in the product documentation would be
-       appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
-       be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
-       distribution.
+<item>  The origin of this software must not be misrepresented; you must not
+    claim that you wrote the original software. If you use this software
+    in a product, an acknowledgment in the product documentation would be
+    appreciated but is not required.
+<item>  Altered source versions must be plainly marked as such, and must not
+    be misrepresented as being the original software.
+<item>  This notice may not be removed or altered from any source
+    distribution.
 </enum>
 
 </article>