michi's log

Recently I am very interested in creating a small game for Android. Since every game needs a proper working gameloop and a underlying drawing mechanism I started to look at some examples from the internet. My first attempt in searching a good example lead me to the Android Developers page. There is a good description on how to get started with 2D graphics. I decided to take the threaded aproach as described there. This means that there is a thread that draws everything into the view as fast as possible while not blocking the UI thread.

Some further poking on the Android Developers page lead me to the Lunar Lander example which looked right what I wanted to do. I installed it on my HTC and played around with it a bit when I suddenly received this error message:

What happened? To put it simple, there is a bug in Google’s Lunar Lander example. Let’s look at the implemenation of the thread that draws the game in LunarView.java and how it’s started:

1
2
3
4

public void surfaceCreated(SurfaceHolder holder) {
	thread.setRunning(true);
	thread.start();
}

The method surfaceCreated() is a callback method from the SurfaceHolder class. It is called whenever the Surface we want to draw on is created, for example when the application starts or when we return from a pause. Respectivly the method surfaceDestroyed() is called whenever the surface is destroyed, for example when the application terminates or another application gets the focus.

1
2
3
4
5
6
7
8
9
10
11

public void surfaceDestroyed(SurfaceHolder holder) {
	boolean retry = true;
	thread.setRunning(false);
	while (retry) {
		try {
			thread.join();
			retry = false;
		} catch (InterruptedException e) {
		}
	}
}

In the Lunar Lander implemention the drawing thread is terminated on the first time the surface is destroyed. If we then try to come back to the application, for example with a long click on the home button, the application throws this exception:

java.lang.IllegalThreadStateException: Thread already started.

We reached an illegal state because a thread is only allowed to be started a single time!

To fix this issue I don’t stop the drawing thread in my application if the app looses focus. Instead I just stop drawing and let the thread sleep for a while (and thus save the CPU resources etc). When the app gets focus again, the drawing starts over. In the example below this behaviour is controlled by the paused variable, running is the variable that is set to true when the game starts and is set to false when the app is terminated and the thread really needs to stop:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

@Override
public void run() {
	while (running) {
		while (paused) {
			try {
				Thread.sleep(50L);
			} catch (InterruptedException ignore) {
			}
		}
 
		Canvas canvas = null;
		try {
			canvas = holder.lockCanvas(null);
			draw(canvas);
		} finally {
			if (canvas != null) {
				holder.unlockCanvasAndPost(canvas);
			}
		}
	}
}

I’ve implemented this gameloop in a small example that displays Conway’s Game of Life:

Of course my implementation has a fixed timestep as suggested by the famous article Fix Your Timestep!

Download my example sourcecode here: android-gameloop-example-v1.zip
App in the Android Market: Gameloop Tutorial

In my current project I make heavy use of logging. To be able to customize logging I am using log4j. Unfortunately LWJGL doesn’t use a log framework of any kind and just outputs on the console via System.out.println(). To add these outputs to the logfile or a log4j console appender one has to reroute the output through log4j. Luckily there is a pretty easy way, I found it in a stackoverflow posting. So how does it work? There is a Java API that allows to set a new PrintStream for System.out and System.err:

1
2

System.setOut(PrintStream stream);
System.setErr(PrintStream stream);

So we simply have to add our own PrintStream implementation that calls the logger and we are done:

1
2
3
4
5

new PrintStream(realPrintStream) {
    public void print(final String message) {
        LOG.info(message);
    }
}

LOG would be our log4j Logger.

In Eclipse there is this wonderful little helper for adding Javadoc links while you’re typing a class name. It looks like this:

It suggests not just to put the classes name there but also use a @link tag so one can navigate the Javadoc sources later on. The finished comment:

Unfortunately this functionality is not available in JetBrains’ IntelliJ Idea. There is (of course) auto completion for classnames in Idea but it simply doesn’t put them in a @link tag. A simple trick saves the day: simply create a live template with context ‘Java comment’ like here:

EDIT: The screenshot is missing the word ‘link’. The complete template should be: ‘{@link $LINK$} ‘.

Don’t forget to click on ‘Edit variables’ and fill in ‘complete()’ as Expression. This activates the auto completion for classnames.

Now everytime a @link in the Javadocs is needed we invoke the Live Templates with Alt + J and enter a classname. The @link tag will be build around that name. It’s not as simple as with Eclipse, but works pretty well.

“Immediate mode rendering is dead” is the title of a topic on the Javagaming Forums I’ve been following the last two days. It is a really insightfull discussion about the use of Vertex Buffer Objects versus Vertex Arrays and the Immediate Mode.
One says the internet doesn’t forget and that is especially true for tutorials concerning OpenGL which have been around for a very long time now. Most of them start by showing how to draw simple geometry using the Immediate Mode and most people posting in the mentioned topic agree that this is the wrong thing to start learning with, at least nowadays.
The topic also includes some example code and benchmarking what methods and ways seem to be the fastest. The contributers just started comparing benchmarks and didn’t go very deep, but I really hope that there will be deeper insights revealed.
The whole discussion actually started here: Sprite!, where princec (from Puppygames) is writing about his sprite-engine. Also a very interesting read!

It has been a while since I last used Vertex Buffer Objects (VBO) with LWJGL. It seemed as if they had changed some of the method signatures since I used them last time. I couldn’t even get the simplest example running. After experimenting for a while I finally figured it out. Have a look at the signature of the VertexPointer method:

static void glVertexPointer(int size, int type, int stride, long pointer_buffer_offset);

With the last offset one can specify where the vertex information starts in the buffer given to the VBO management. Well, I could/should have guessed that this offset has to be in bytes since I am dealing with a buffer here but instead I used the number of floats.. So next time I see an operation dealing with buffers that takes a long argument I’ll try the byte-count from the beginning..

If you are using Meggy Jr with the Serial-to-USB Cable provided in the Evil Mad Scientist shop you might encounter the following error:

avrdude: stk500_getsync(): not in sync: resp=0×00
avrdude: stk500_disable(): protocol error, expect=0×14, resp=0×51

The error manifest while uploading a new sketch to Meggy. If you pull out the USB cable and plug it in again you can upload a sketch successful. But on the next time you try you’ll get the error again. Luckily there is a pretty simple solution. I found it while digging through the Evil Mad Scientist Forums. It involves setting the “Set RTS on close” flag of the COM Port. You can do this in the Device Manager. Find the COM Port that was installed when you first plugged in the USB-to-Serial cable. For me it’s COM3. In the connection settings click on details and mark the flag selected. That’s it. I tried this on Windows XP with Service Pack 3, but it should work similiarily on other Windows versions.

RTS Flag

Today I finished my first Meggy Jr program. The programming with the Arduino IDE was easy as expected. I wrote a simple Color Chooser application that let’s the user explore the variety of colors available on Meggy Jr.  Meggy Jr’s <em>Simple Library</em> only knows 16 predefined colors. It is possible though to define more colors with the Method EditColor(byte color, byte r, byte g, byte b) in which you simply specify the amount of red, green and blue you want in your final color. Each component takes a byte as input and therefore Meggy can display 4096 different colors, theoretically. In practice you will find that even small values for the blue component will make the resulting color blue.

In my last blog entry I mentioned that it is possibly to write data to the pc via a serial connection. The Color Chooser makes use of this feature and writes back the current color and its components to the pc so you can use the values in another project.

I made a video of the running application. The quality sucks, but you’ll get the idea:

During the programming I used the Meggy Jr Programming Guide, a pretty helpful document. You can get it at the Evil Mad Scientist Laboratories.

The sourcecode of this application is available as download.

Ich weiss garnicht mehr genau wann und wo ich Meggy Jr RGB zum ersten mal gesehen habe, aber mir war sofort klar, dass ich so ein Ding brauche! Meggy ist eine do-it-yourself Spielekonsole. Das bedeutet, dass man es selbst zusammenbaut und optional auch selbst Programme dafür schreibt. Entwickelt wurde das ganze von Evil Mad Scientist Laboratories als open-source Hardwareprojekt. Open-source bedeutet in diesem Zusammenhang, dass sowohl das Layout der Platine sowie die für die Programmierung benötigten Librarys frei erhältlich sind. In Meggy werkelt ein Atmega 168 Microcontroller vor sich hin. Meggy baut, im Hinblick auf einfache Toolchains und Prototyping-Qualitäten, auf Arduino auf.

Neben dem Microcontroller ist das Display sicherlich mit das größte Feature: Es ist eine LED Matrix bestehen aus 8×8 Elementen, die jeweils eine große Anzahl verschiedener Farben anzeigen können. Eine Auflösung von 8 auf 8 Pixel hört sich zwar klein an, aber schon die mitgelieferten Spiele zeigen, dass durchaus einiges Potential für gute Spiele vorhanden ist. Bisher habe ich sehr spaßige Meggy-Versionen von Frogger und Space Invaders gespielt. Das vorinstallierte Spiel ist ein sidescrolling Shoot-em-up bei dem man laut Beschreibung die Welt vor ein paar Tomaten rettet :) Es gibt sogar ein Meggy Roguelike (hier), allerdings habe ich es noch nicht selbst gespielt.

Aber Meggy eignet sich nicht nur als Spielekonsole. Mittlerweile gibt es auch eine ganze Reihe von Anwendungen die mit Spielen an sich nichts zu tun haben. Begünstigt wird das durch eine Serial Port mit dem man Meggy mit dem Rest der Welt sprechen lassen kann. Durch die Wahl von Arduino als Entwicklungsumgebung genügt dafür eine einzige Zeile für die Initialisierung und anschließend ein Serial.println("..."); um Text den Serial Port runterzuschicken. Als Beispiel sei hier mal das Projekt genannt in dem Meggy zusammen mit einem Arduino WaveShield als Sequenzer benutzt wird: MeggySeq

Hier ein paar Bilder vom Zusammenbauen:

Meggys Platine

Heh, ohne Kommentar..

Halbfertig mit Microcontroller und LED Treiber

Meggy Jr RGB fertig zusammengebaut

Shaderprogrammierung in GLSL, der Shadersprache unter OpenGL, war bisher ein Buch mit sieben Siegeln für mich. Aber da man ja alles lernen kann habe ich mich auf die Suche nach Tutorials gemacht und auch einige sehr gute entdeckt. Die Einführung von Lighthouse3d ist zum Beispiel sehr zu empfehlen. Hier wird wirklich mit den Grundlagen angefangen und erstmal eine Beschreibung geliefert wie die Pipeline der Grafikkarten aufgebaut sind und wo genau die verschiedenen Shader zum Einsatz kommen.

Natürlich muss man die geschriebenen (oder abgetippten) Shader auch irgendwie ausprobieren. Hier fand ich das Programm ShaderDesigner von Typhoon Labs ganz brauchbar. Leider scheint es die Firma nicht mehr zu geben, aber sowohl ShaderDesigner als auch ein ebenfalls super geschriebenes Tutorial für Shader lassen sich nach wie vor von der Seite runterladen.

Schließlich habe ich mich daran gemacht, die Shader auch in einem wirklichen Programm einzusetzen. Hierfür verwende ich die “Light Weight Java Games Library” (LWJGL), meinem Lieblingsbinding von OpenGL an Java. Es stellte sich heraus, dass wenn man mal einen funktionierenden Shader hat, diesen wirklich einfach in ein Programm einbinden kann. Wirklich geholfen hat mir der entsprechende Wikieintrag im LWJGL Wiki. Am besten speichert man Vertex- und Fragmentshader in einer Textdatei und legt sie irgendwo im Projektverzeichnis ab. Im Programm werden die Dateien dann mit ganz gewöhnlichen Hausmitteln erstmal geöffnet und in einem Bytearray gespeichert. Dies muss natürlich sowohl für Vertex- als auch für Fragmentshader passieren:

1
2
3
4
5
6
7
8
9
10
11

ClassLoader loader = ShaderTest.class.getClassLoader();
InputStream is = loader.getResourceAsStream(shadername);
byte[] shadercode = null;
try {
    DataInputStream dis = new DataInputStream(is);
    dis.readFully(shadercode = new byte[is.available()]);
    dis.close();
    is.close();
} catch (IOException e) {
    System.out.println(e.getMessage());
}

Anschließend werden die Bytearrays in einen ByteBuffer kopiert, den LWJGL lieber mag:

1
2
3

ByteBuffer shader = BufferUtils.createByteBuffer(shadercode.length);
shader.put(shadercode);
shader.flip();

Nicht vergessen die Buffer zu flippen!
Anschließend teilen wir OpenGL mit, dass wir zwei neue Shaderobjekte brauchen. Dies funktioniert genau wie wenn man eine Textur anlegt: Man teilt OpenGL mit, was man haben will und bekommt ein int zurück, mit dem man das neue Objekt referenzieren kann:

1
2
3
4

int vertexShaderID = ARBShaderObjects.glCreateShaderObjectARB(
ARBVertexShader.GL_VERTEX_SHADER_ARB);
int pixelShaderID = ARBShaderObjects.glCreateShaderObjectARB(
ARBFragmentShader.GL_FRAGMENT_SHADER_ARB);

Nachdem die entsprechenden Objekte nun OpenGL bekannt gemacht wurden müssen wir OpenGL nun mitteilen was die Shader genau machen sollen, sprich deren Quellcode übergeben. Danach werden die Shader kompiliert:

1
2
3
4
5

ARBShaderObjects.glShaderSourceARB(vertexShaderID, vertexShader);
ARBShaderObjects.glCompileShaderARB(vertexShaderID);
 
ARBShaderObjects.glShaderSourceARB(pixelShaderID, pixelShader);
ARBShaderObjects.glCompileShaderARB(pixelShaderID);

vertexShader und pixelShader sind die Variablen, die auf die ByteBuffer zeigen und den eingelesenen Quelltext enthalten.
Die beiden Shader werden nun zu einem Programm zusammengebunden. Ein Programm wird dabei ebenso wie ein Shaderobjekt erstellt: bei einem Methodenaufruf erhalten wir ein int mit dem wir das Programm in Zukunft referenzieren. Hat man nur einen Vertex- oder nur einen Fragmentshader zur Hand wird der jeweils andere Teil von OpenGL durch eine Standartimplementierung ersetzt. Zum Schluß werden die Teile ähnlich einem C Programm zusammengebunden.

1
2
3
4

int shaderProgramID = ARBShaderObjects.glCreateProgramObjectARB();
ARBShaderObjects.glAttachObjectARB(shaderProgramID, vertexShaderID);
ARBShaderObjects.glAttachObjectARB(shaderProgramID, pixelShaderID);
ARBShaderObjects.glLinkProgramARB(shaderProgramID);

Jetzt sind wir fertig und können den Shader beim Rendern benutzen. Hierzu ruft man im Renderloop bevor das Objekt das den Shader erhalten soll gezeichnet wird die folgende Methode auf

1

ARBShaderObjects.glUseProgramObjectARB(shaderProgramID);

Wird anstatt einem Shaderprogramm “0″ übergeben benutzt OpenGL die Standarteinstellungen (fixed Pipeline) zum Rendern.

Ein kleiner Test mit einem Toon-Shader aus dem Lighthouse Tutorial sieht dann zum Beispiel so aus:

Die Veränderung der Farbe des 3d Modells hängt nicht mit dem Licht zusammen sondern wird im Fragmentshader verursacht. Hierzu wird eine Variable vom Javaprogramm aus an den Shader übergeben, die die Zeit seit dem Beginn der Anwendung übergibt. Im Fragmentshader ist die Variable so definiert:

1

uniform float TIME_SINCE_INIT;

Bei jedem Durchlauf des Renderloops wird diese Variable vom Javaprogramm neu geschrieben. Um den Schreibvorgang durchzuführen wird vorher die Location der Variable bestimmt. Dazu wird OpenGL der mit 0 terminierte Name der Variablen übergeben. Existiert diese, dann liefert OpenGL eine Location in Form eines Integers zurück und man kann mit einem glUniform1fARB-Aufruf den Wert übergeben.

1
2
3
4
5
6
7
8

ByteBuffer buff = BufferUtils.createByteBuffer(
    "TIME_SINCE_INIT".length()+1);
buff.put( "TIME_SINCE_INIT".getBytes() );
buff.put((byte)0);
buff.flip();
int location = ARBShaderObjects.glGetUniformLocationARB(
    shaderProgramID, buff);
ARBShaderObjects.glUniform1fARB(location, gameLogicTimer.getTime());

Beim Stöbern durch die Bibliotheken von ACM bin ich auf folgenden Artikel gestoßen: Computer games as motivation for design patterns. Paul V. Gestwicki beschreibt darin wie er mit Hilfe eines Computerspiels seine Studenten motiviert sich mit Design Patterns zu beschäftigen. Obwohl man ja gerade bei Spielen oft darauf aus ist noch die letzten FPS aus dem Code herauszuquetschen lohnt es sich doch nicht allen Code auf Performance auszulegen, sondern einen strukturierten Ansatz zu verfolgen. Die Vorteile liegen auf der Hand: Der Code wird lesbarer, leichter wartbar und besser erweiterbar.

Das erste Design Pattern in seinem Paper ist das State Pattern. Anhand einer Sprite Klasse, die zuständig für das Aussehen, die Größe und Position des Spielers ist, erläutert er das Pattern. Der Spieler kann sich in mehreren Zuständen(=States) befinden und das Verhalten der Sprite Klasse ändert sich mit jedem Zustand. Eine naive Implementation würde jedem Zustand einen int-Wert geben und dann in einer update() Methode später einen großen switch-Block durchlaufen in dem jedes Verhalten in jedem Zustand beschrieben ist.

Im Buch Design Patterns von Gamma et. al. wird jedoch genau dies als Grundlage der Anwendbarkeit des State Pattern angegeben:

• An object’s behavior depends on its state, and it must change its behavior at run-time depending on that state
• Operations hve large, multipart conditional statements that depend on the object’s state. This state is usually represented by one or more enumerated constants.

Wie sieht nun so ein State Pattern aus? Zu allererst brauchen wir ein Interface, dass einen Zustand beschreibt:

1
2
3
4
5
6

public interface State {
public void install();
public void uninstall();
public void draw();
public void update();
}

Die Spieler Klasse muss nun eine Variable vom Typ State besitzen mit der angegeben wird in welchem Zustand der Spieler sich gerade befindet. Außerdem müssen alle Aufrufe die den Zustand des Spielers betreffen an die State-Implementation deligiert werden. Skizzenhaft sieht der Spieler dann so aus:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

public class Spieler{
State aktuellerZustand;
 
...
 
public void update(){
aktuellerZustand.update();
}
 
public void draw(){
aktuellerZustand.draw();
}
 
...
}

Was nun noch fehlt sind tatsächliche Implementationen des State-Interfaces. Hier hat man mehrere Möglichkeiten. Zum einen kann man innere anonyme Klassen verwenden:

1
2
3
4
5
6
7
8

//Konstruktor
public Spieler(){
aktuellerZustand = new State(){
public void install(){...};
public void uninstall(){...};
public void update(){...};
public void draw(){...};
}

oder man verwendet einfache innere Klassen, d.h. in der Spieler Klasse werden weitere Klassen definiert die jeweils das State Interface implementieren. Beides hat den Vorteil, dass man die Logik und das Verhalten des Spielers sehr nahe am Spieler selbst hat. Die inneren Klassen können auf Variablen der äußeren Zugreifen und so mit dem Spieler interagieren. Weiterhin verbirgt man die konkreten Zustände vor der Außenwelt.

Das Spieler Objekt könnte nun selbst entscheiden wann es welchen Zustand braucht, einfacher und manchmal auch schöner ist es jedoch die Zustände selbst entscheiden zu lassen. Hierfür gibt es die Methoden install() und uninstall(), die einen Übergang von einem zum anderen Zustand erlauben indem sie einfach die State Variable des Spielers neu setzen. Denkbar ist natürlich auch, dass in diesen Methoden spezielle Animationen für die Übergänge ausgelöst werden usw.