Titel:    Gamebox mit SAMSUNG SLM1608 Display
Autor:    (c) 2004-2006 by Malte Marwedel
Datum:    2006-11-03
Version:  1.00 (Final 1)
Zweck:    Spiele auf einem Grafikdisplay
Software: GCC-AVR / GCC
Hardware: LED Panel, ATMEGA32 oder hnlichen mit 8MHZ.
          Einzelne Module mssten auch auf einem ATMEGA16 laufen.
          "modul_pxxo" und "modul_psnake" knnten jedoch mangels RAM
          mglicherweise gar nicht oder nur fehlerhaft laufen.
          ODER:
          PC mit 500MHZ und 800x600 @ 256 Farben 3D beschleunigte Grafik
Bemerkung:Der Quellcode steht unter der GPL. Der Lizenztext kann in der Datei
          gpl-license.txt gefunden werden.
          Ausgenommen hiervon sind die Dateien "avr/Makefile" und
          "i386/Makefile". Sie entstammt dem Programm "mfile" und fr die Datei
          gelten entsprechende andere Bedingungen fr die Verwendung.
Wer Fragen oder Anregungen zu dem Programm hat, kann an
           m.marwedel <AT> onlinehome.de mailen.
          Mehr ber Elektronik und AVRs gibt es auf meiner Homepage:
           http://www.marwedels.de/malte/
Code Gre:ATMEGA32: 27194 Byte (getestet, alle Module)
Compiler Optionen:
          AVR: -Os -ffast-math -fweb -Winline
          PC: -Os -ffast-math -Winline --param max-inline-insns-single=100
Verwendete Software zum compilieren:
      AVR:
          gcc-avr  Version: 3.4.3
          avr-libc Version: 1.4.4
       PC:
          gcc Version: 4.0.2 oder  3.4.5 (empfohlen) oder 3.3.6
          GLUT

-------------------------Hinweise zur AVR und PC Version -----------------------
Die Software wurde ursprnglich nur zum Ausfhren auf einem Mikrocontroller
geschrieben. Die Mglichkeit die Software auch auf dem PC zu testen kam erst
spter hinzu. Dabei habe ich versucht den Code mglichst wenig zu ndern.
Im primrem Verzeichnis befindet sich der vom AVR und PC gemeinsam benutzte
Code. Das Verzeichnis /avr enthlt den AVR spezifischen und /i386 den PC
spezifischen Code. Der Code ist also optimiert fr einen Mikrocontroller, sprich
eine Endlosschleife erledigt die meisten Berechnungen und Zeitsteuerungen werden
sowohl ber Delay Schleifen, als auch ber einen 16Bit Timer geregelt. Der
Interrupt eines 8Bit Timers sorgt fr die Grafikausgabe und ein anderer
Interrupt eines zweiten 8Bit Timers sorgt fr die Joystick Eingabe.
Auf dem PC ist nun die Grafikausgabe und Tasteneingabe grundlegend anders, so
dass hier Anstelle der beiden 8Bit Timer Funktionen der GLUT Libray diese
Aufgabe bernehmen. Die Hauproutine (Endlosschleife) wird als extra Thread
gestartet und verbraucht somit soviel CPU Rechenzeit wie mglich. Dies bedeutet,
solange das Programm auf dem PC luft liegt die CPU Auslastung kontinuierlich
bei 100%. Dank des Betriebssystems bekommen aber natrlich auch andere Prozesse
Rechenzeit ab und der Rechner hngt nicht :-)
Die Delayschleife musste neu geschrieben werden und erledigt ihre Aufgabe durch
Auslesen der Systemzeit und Vergleich mit der gewnschten Delay Zeit.
Der ebenfalls zum Timing herangezogene 16Bit Timer wird simuliert indem Mithilfe
der GLUT Libray periodisch eine Funktion ausgefhrt wird welche die 16Bit Timer
Variable entsprechend erhht. Leider ist das periodische Ausfhren dieser
Funktion nur mit einer relativ niedrigen Frequenz mglich, so dass der Timer
immer um mehrer Zhlschritte auf einmal erhht werden muss. Auch ist die Dauer
zwischen dem Ausfhren der Funktion nicht immer gleich gro, so dass die
Zhlschritte mal grer und mal kleiner ausfallen. Dies liegt vorallem daran,
dass ein CPU Kern nur einen Thread zur Zeit bearbeiten kann und der Wechsel
zwischen den verschiedenen Threads seltener erfolgt als die Funktion zum Erhhen
des 16Bit Zhlers aufgerufen werden msste.
Das Resultat davon uert sich darin dass die Software etwas stockend und trge
wirkt. Auf dem AVR sind die Bewegungen deutlich gleichmiger und das Spielen
der Spiele macht definitiv mehr Spa!
Das Laufen auf dem PC dient daher eher
1. als Experiment in wie weit Code von der einen Plattform auch auf der andren
luft
2. Als Plattform um Fehler schneller zu finden - einfachere Fehlerausgabe, kein
umstndlicher Upload in den Mikrocontroller
und 3. um die Mglichkeiten der Gamebox auch Personen die die Hardware
(Mikrocontroller + Display) (noch) nicht haben zu zeigen.

---------------------------AVR Step-by-Step Anleitung --------------------------
1.Anpassen der Datei "avr/Makefile"
1.1 "MCU"
   In der Datei muss der passende MCU eingestellt werden. Die
   Standardeinstellung ist ein ATMGEGA32. Bei einem ATMEGA16 muss die
   Auswahl der Module begrenzt werden. Des weiteren ist nicht ausgeschlossen
   dass fr die Module "modul_pxxo", "modul_psnake" und "modul_prev" die ein
   KB RAM des ATMEGA16 ausreichen. (Der ATMEGA32 hat 2KB RAM).
   Ein ATMEGA8 msste auch mglich sein, jedoch kann aufgrund des knappen
   Programm Speichers nur wahlweise das Modul "modul_prace" oder
   "modul_psnake" verwendet werden. Beim "modul_psnake" knnen die gleichen
   Probleme wie beim ATMEGA16 auftreten. Des weiteren muss der Quellcode
   bei der Verwendung eines ATMEGA8 noch weitere kleine nderungen erhalten.
   Auswahlmglichkeiten fr MCU = sind also "atmega32", "atmega16" oder
   "atmega8". Wieweit der Quelltext auch mit anderen AVRs funktioniert wurde
   nicht berprft.
   Wirklich in der Praxis getestet ist nur der ATMEGA32 mit 8MHZ.
2.Anpassen der Datei "avr/main.h"
2.1 "F_CPU"
   Fr "F_CPU" muss der verwendete Takt eingestellt werden. 4MHZ sind das
   Minimum. Es ist nicht auszuschlieen dass das Timing oberhalb von 11MHZ
   falsch berechnet wird, dies htte jedoch hchstens minimale Auswirkungen.
   Standard ist 8MHZ also F_CPU = 8000000
2.2 "osccalreadout"
   Wird der interne Taktgenerator des AVRs verwendet so kann hier das
   Kalibrierungsbyte eingestellt werden. Der passende Wert kann mit dem
   verwendetem Programmer ausgelesen werden. Bei der Verwendung eines Quarzes
   oder einer anderen externen Taktes hat der Wert keine Bedeutung.
2.3 Die Module:
   Hier kann eingestellt werden, welche Programmteile verwendet werden sollen.
   Das "modul_plaby" ist noch nicht vorhanden und kann daher nicht ausgewhlt
   werden.
   Eine "1" bedeutet das Modul wird verwendet, bei einer "0" wird auf das Modul
   verzichtet. Alle derzeitigen Module bentigen zusammen rund 24,5KB Flash.
   Bei einem kleinerem AVR muss also auf manche Module verzichtet werden.
   Das "Grundgerst" aus Men, Displayansteuerung, Textausagabe u.s.w bentigt
   rund 7KB Flash.
2.3.1 modul_demo
   Ist die Grafik-Demo, welche es auch als Stand-alone Version gibt.
   Hinweis: Die Demo bentigt die Fliekomma Bibliothek. Parameter "-lm" in
   der Datei "Makefile".
   Code Gre: rund 5,5KB
2.3.2 modul_calib_save
   Ermglicht das Speichern der Joystick Kalibrierung im EEPROM
   Code Gre: knapp 1KB
2.3.3 modul_sram
   Ermittelt die kleinste Stack und grte Heap Adresse. Die Differenz
   wird als minimaler freier Speicher ausgegeben.
   Code Gre: knapp 300Byte
2.3.4 modul_highscore
   Ermglicht die hchsten erreichten Punkte in den Spielen im EEPROM
   abzuspeichern.
   Code Gre: knapp 1KB
2.3.5 modul_ptetris
   Das Spiel Tetris. Eine Reihe Abbauen: 1 Punkt. Zwei Reihen
   gleichzeitig: 3 Punkte, drei Reihen gleichzeitig 5 Punkte und 4 Reihen
   gleichzeitig bringen 8 Punkte. Links wird das derzeitige Level und die
   abgebauten Reihen angezeigt.
   Code Gre: rund 2KB
2.3.6 modul_prace
   Eine Art Rennspiel. Hindernissen muss ausgewichen werden. Links wird das
   Level und rechts die Lebenspunkte angezeigt. Das Berhren von grnen
   Hindernissen bringt einem Lebenspunkt, rote ziehen einem Lebenspunkt ab.
   Code Gre: gut 0,5KB
2.3.7 modul_pxxo
   Vier Gewinnt wahlweise fr ein oder zwei Spieler. Der Computer Gegner
   ist noch verbesserungsbedrftig und sehr langsam. Hier ist ein hherer
   AVR Takt von Vorteil. Der CPU Gegner bentigt auch eine Menge Stack,
   mglicherweise zu viel fr 1KB RAM.
   Code Gre: gut 4KB
2.3.8 modul_ppong
   Pong mit zwei Spielvarianten und verschiedenen Schwierigkeitsgrade. Modi 1
   bietet einen perfekten Gegner und es geht darum mglichst lange
   durchzuhalten. Modi 2 bis 4 bieten die Mglichkeit sich gegenseitig
   abzuschieen. Je hher der Modi, desto intelligenter der Gegner.
   Code Gre: gut 2KB
2.3.9 modul_prev
   Reversi fr ein oder zwei Spieler. Die Suchtiefe ist auf 4 Halbzge
   beschrnkt. Zu Beginn des Spiels scheint die KI recht gut zu spielen, 
   mangels einer gezielten Strategie ist Gewinnen jedoch relativ leicht.
   Die KI bentigt viel RAM und wird daher wahrscheinlich nur auf einem
   ATMEGA32 laufen. Am unteren Rand der Anzeige wird die Anzahl der von der KI
   bewerteten Spielmglichkeiten binr angezeigt.
   Code Gre: knapp 3KB
2.3.10 modul_psnake
   Snake, die rote Nahrung sammeln bringt Punkte und verlngert die Schlange.
   Je schneller man ist desto mehr Punkte bekommt man! Snake bentigt eine Menge
   Heap, so dass 1KB RAM mglicherweise nicht reichen. In diesem Fall wird eine
   Fehlermeldung angezeigt.
   Code Gre: gut 1KB
3.Anpassen der Datei "avr/graphicint.h"
   Die Pin Belegung des LED Moduls kann hier eingestellt werden.
   Standardmig sind alle Anschlsse auf PORTC gelegt. Beim ATMEGA8 ist das
   jedoch der Port mit dem A/D Wandler und wrde somit fr den Joystick bentigt
   werden. Ich hoffe die ganzen #defines sind dort selbsterklrend. Generell
   knnte jeder beliebige Anschluss des LED Modules an einen beliebigen Pin des
   AVRs angeschlossen werden. Dies ist auch Port bergreifend mglich!
4.Anpassen der Datei "avr/userinput.h"
   Alle Anschlsse des Joystick als Eingabegert mssen an dem Port mit dem A/D
   Wandler liegen. Welcher Pin des Ports mit welchem Anschluss belegt wird ist
   egal, dies kann beliebig eingestellt werden. Als Port muss beim ATMEGA16/32
   PORTA gewhlt werden. Beim ATMEGA8 wre es PORTC. Achtung: Standardmig
   liegt an PORTC das LED Modul. Die Ports knnen hier nicht fr beides
   verwendet werden!
5.Erzeugen der .hex Datei
   In der Kommandozeile in das passende Verzeichnis /avr wechseln und "make"
   aufrufen. Luft alles nach Plan, so wird eine Datei "main.hex" erzeugt, die
   dann mit einem Programmer in den AVR kopiert werden kann.
   Hinweis: Ich will nicht ausschlieen dass die "Makefile" unter Windows
   Probleme bereitet. In diesem Fall ist es am einfachsten mit dem Programm
   "mfile" eine neue Datei "Makefile" zu erzeugen. Die zustzlichen Sourcen
   eintragen und den MCU auswhlen. Fr das Modul "modul_demo" wird die
   Fliekomma Bibliothek bentigt.

----------------------------- PC Step-by-Step Anleitung ------------------------
Die Anpassung der zu Compilierenden Module erfolgt wie bei der AVR Anleitung
oben in den Punkten 2.3 nur eben in der Datei i386/main.h. Das Modul calib_save
(2.3.2) macht auf dem PC keinen Sinn und sollte daher nicht aktiviert
werden. Das Modul highscore (2.3.4) vergisst derzeit noch die Punkte
sobald das Programm beendet wird.
Das Modul sram (2.3.3) lsst sich zwar fehlerfrei Compilieren, die Ausgabe
fhrt jedoch zu fehlerhaften Werten da ein PC eben mehr als 64KB RAM hat...
Das restliche Programm wird durch das Modul aber nicht negativ beeinflusst.
Zur Compilierung wird die GLUT Bibliothek bentigt. Es sollten daher Pakete mit
den Namen freeglut3, freeglut3-dev und libglut3 installiert werden wenn die
Compilierung fehlschlgt. Unter Ubuntu lassen sich diese beispielsweise mit
>>sudo apt-get install freeglut3 freeglut3-dev libglut3<<
erledigen.
Falls gcc Version 3.4.x vorhanden ist, sollte wenn mglich diese verwendet
werden (siehe Bugs unten). Dazu muss in der Datei /i386/Makefile in Zeile 74
der Parameter von "CC = gcc" auf "CC = gcc-3.4" gendert werden.
Ein Aufruf von make im Verzeichnis /i386 erzeug das Programm. Starten lsst sich
das compilierte Programm danach mit ./main.elf

------------------------------ Eigene Spiele schreiben -------------------------
Wer eigene Spiele schreiben mchte schaut sich am besten mal den Quellcode der
anderen Spiele an. "graphicfunctions.h" stellt einige einfache Grafikfunktionen
wie das Zeichnen einer Linie oder Box zur Verfgung. Mit "userinput.h" ist es
mglich Benutzeriengaben abzufragen. Timer0 und Timer2 werden bereits verwendet.
Der 16Bit Timer1 steht jedoch zur Verfgung, auch wenn keine Interrupts mglich
sind. In "menu.c" knnen weitere Men Eintrge hinzugefgt werden.
Falls jemand ein Spiel geschrieben hat oder zumindest eine Idee fr eins hat,
wrde ich mich ber eine Mail freuen.

------------------------------ Bugs --------------------------------------------
AVR:
Ich werde das Gefhl nicht los, dass bei der Joystick Auswertung der Y Achse
irgend etwas faul ist. Manchmal wird eine Bewegung nach oben flschlicherweise
als eine nach unten interpretiert. Ich wei nicht ob dies an der Hard- oder
Software liegt. Die X Achse funktioniert einwandfrei und verwendet nahezu den
selben Quellcode.

PC:
Das Timing ist nicht optimal, dies knnte in seltenenen Fllen zu Fehlern in den
Spielen fhren. Beobachtet habe ich bisher aber keine.
Mit der gcc 4.0.2 wird an einer Stelle das Menu nicht richtig dargestellt,
auerdem wird flschlicherweise wegen eine nicht inititialisierten Variable
gewarnt. Falls mglich sollte gcc 3.4.5 verwendet werden, hier treten die oben
genannten Fehler nicht auf.

------------------------------ Changelog ---------------------------------------
Aktuelle Version: 1.00 (Version 1) Datum: 2006-11-03
  Verwendung von sizeof() korrigiert
  Kommentare aktualisiert
  XXO: Kleinere Bugs behoben
  Programm steht jetzt definitiv unter GPL
  Viele sehr kleine Code Verbesserungen und Korrekturen
    
ltere Version: 0.50 (Beta 2) Datum: 2006-10-19
  modul_calib_save: Bug behoben der Beta 1 nicht korrekt laufen lie
  Reversi: Binranzeige fr die bewerteten KI Zge
  Reversi: Reduzieren der Suchtiefe um einen Halbzug fr mehr Geschwindigkeit

ltere Version: 0.40 (Beta 1) Datum: 2006-10-04 (nie verffentlicht)
  Erhebliche Verbesserung des XXO Gegners
  Schreiben von Reversi
  Anpassen an die avr-libc 1.4
  
ltere Version: 0.30 (Alpha 3) Datum: 2006-05-19
  Bugfix beim Timing der PC Version
  Erweitern der readme.txt

ltere Version: 0.20 (Alpha 2) Datum: 2006-03-12  (nie verffentlicht)
  Untersttzung der Compilierung auf dem PC 

ltere Version: 0.10 (Alpha 1) Datum: 2005-08-20
Die Software basiert auf meiner Stand-alone Grafik Demo. Version 1.0

*END OF FILE*