Badlogic Games

Apart from the event based InputListener concept libgdx also allows you to poll for input. Polling means that you check the current state of the input devices. To poll the touch screen, keyboard and accelerometer we again use the Input instance provided by the Application. Let’s have a look at the corresponding methods of the Input interface:

public interface Input 
{
       ...
 
	public boolean isAccelerometerAvailable( );	
 
	public float getAccelerometerX( );
 
	public float getAccelerometerY( );
 
	public float getAccelerometerZ( );
 
	public int getX( );
 
	public int getY( );
 
	public boolean isTouched( );
 
	public boolean isKeyPressed( int key );
}

The first four methods allow use to poll the state of the accelerometer. The first method Input.isAccelerometerAvailable() tells us whether there’s an accelerometer installed on the device. The next three methods return the current values for the 3 axis of the accelerometer. When you hold your device in portrait mode then the x-axis goes from left to right, the y-axis from bottom to top and the z-axis points out of the device towards you. The values these 3 methods return are in the range [-10,10] and indicate how much acceleration occurs on a given axis. Note that if you hold your device in landscape mode the axis stay the same!

The next three methods tell you the x and y coordinate of a touch on the screen as well as whether the screen is actually touched. The coordinate system for the touch coordinates has it’s origin in the top left corner of the screen with the x-axis pointing to the right and the y-axis pointing downwards.

Finally there’s Input.isKeyPressed() which allows you to poll the state of the keyboard. You can use any constant in the Input.Keys class here which are the same as the corresponding Android constants.

Note that on the desktop the accelerometer is of course not available. For polling keyboard input the same rules apply as with the event based input method discussed last time. Not all keys are mapped.

That’s all there is to know about the Input module. Next time we’ll see how we manage files with libgdx. After we have understood that we can finally talk about the interesting stuff, graphics and audio programming.

Last time we learned how to instantiate a desktop and an Android application which share the source of an ApplicationListener. The ApplicationListener is great when you want to get life cycle related events like pause and resume but other than that you can’t really do anything interesting.

Today we will have our first excourse into the realms of the Graphics interface. Each Application implementation offers you an instance of that interface via its Application.getGraphics() method. From the Graphics implementation you can ask for an instance of GL10, GL11 or GL20. You can also make it create certain graphics resources like fonts or textures for you. Today however we want to concern ourselves with another piece of the puzzle. The RenderListener.

A RenderListener is an interface that you have to implement much like the ApplicationListener interface. Similarily you also have to register it somewhere, in this case with the Graphics instance of the Application. The Graphics instance will then call the methods of the RenderListener. Let’s see how we do that:

public class MyApp implements RenderListener
{
   @Override
   public void surfaceCreated( Application app )
   {
   }
 
   @Override
   public void surfaceChanged( Application app, int width, int height )
   {
   }
 
   @Override
   public void render( Application app )
   {
   }
 
   @Override
   public void dispose( Application app )
   {
   }
 
   public static void main( String[] argv )
   {
      JoglApplication app = new JoglApplication( "My Renderer App", 480, 320, false );
      app.getGraphics().setRenderListener( new MyApp( ) );
   }
}

public class MyAndroidApp extends AndroidApplication
{
   public void onCreate( Bundle bundle )
   {
      super.onCreate( bundle );
      initialize( false );
      getGraphics().setRenderListener( new MyApp() );
   }
}

Again we have a main class in the desktop project which implements the RenderListener interface and has a static main to get a JoglApplication running and an Activity derived from AndroidApplication which just uses the desktop class as its RenderListener.

Now, the Graphics instance on the desktop and on Android each have their own thread within which they continuously make the OpenGL surface rerender itself. When we register a RenderListener with a Graphics instance we get the oportunity to render to that surface ourselves via the RenderListener.render method. Apart from that method there are a couple of other methods in the RenderListener interface that get called on special occasions.

The RenderListener.surfaceCreated() method gets called each time the OpenGL surface is created. This happens at application startup and when an Application is resumed. The RenderListener.surfaceChanged() method gets called each time the OpenGL surface changed its dimensions. Finally, the RenderListener.dispose() method is called when a new RenderListener is registered or when the Application is shut down. Not that hard and very similar to what the Renderer interface and the GLSurfaceView do.

What you should take away from this is: rendering is done in a different thread than the GUI thread. Also, when an OpenGL surface is recreated after a resume event all the textures and other OpenGL resources your previously created are invalidated and have to be reloaded. In an earlier article i told you about managed resources informally. We’ll have a closer look at those in a future article.

Finally let us do something graphicy and clear the surface (which i’ll also refer to as framebuffer from time to time) with a color. We do this the old fashioned OpenGL way. For brevity i only post the render() method of the MyApp class here:

public void render( Application app )
{
   GL10 gl = app.getGraphics().getGL10();
   gl.glClearColor( 1, 0, 0, 1 );
   gl.glClear( GL10.GL_COLOR_BUFFER_BIT );
}

And we get a red window on the desktop as well as on Android! You could start playing around with OpenGL in there a little more. The Graphics instance can return you GL10, GL11 and GL20 interface instances. Note however that GL20 is only supported when you pass true as the last parameter to the JoglApplication constructor and to the AndroidApplication.initialize() method. GL10 and GL11 will not be available in that case as they are incompatible to GL20. We’ll have a closer look at those classes in a later article.

Everything in libgdx revolves around a so called Application. An application offers you several modules for various tasks. There’s a Graphics module which provides you with all things graphicy. There’s an Audio module which will allow you to play sound effects and music as well as accessing the audio hardware directly (to be re-implemented, the last thing that’s missing). The Input module gives you information about what the user is doing with his keyboard, touchscreen/mouse and so on. Finally there’s a Files module which allows you to read and write files in a system indepedant manner. We will discuss all of this modules in forthcoming articles. Today we want to focus on the Application interface, its implementations and an Application’s life cycle.

The first thing we need to know is how to setup an Application. This setup step is the only thing that will differ between the desktop and Android version of your application. You will have to create a static main method for the desktop version and instantiate a JoglApplication in there. In your Android project you will have to create a class that derives from AndroidApplication which itself is an Activity. Here’s two short snippets for doing just that:

public class MyAppDesktop
{
   public static void main( String[] argv )
   {
      JoglApplication app = new JoglApplication( "My App Title", 480, 320, false );
   }     
}

public class MyAppAndroid extends AndroidApplication
{
   public void onCreate( Bundle bundle )
   {
      super.onCreate( bundle );
      initialize( false );
   }
}

Now that was easy. The desktop version instantiates a JoglApplication. It’s constructor takes the window title, the window dimensions in pixels and wheter OpenGL ES 2.0 should be used or not. That’s it, now you have an OpenGL based application running on your desktop. The Android version is similar. We simply derive from AndroidApplication and overwrite the onCreate method. We first call the onCreate method of the super class and then call initialize which is a special method provided by the AndroidApplication. This method will setup the GLSurfaceView internally, the argument of the method determines wheter OpenGL ES 2.0 should be used or not (in this case we won’t use it). The AndroidApplication will switch to fullscreen. The orientation of the screen will be what it was before you started the application. You could hardcode the orientation before the call to initialize of course (and you probably should do that so you only have to layout your game in landscape mode for example).

Now, there’s not a lot happening. Both applications show a black screen and up until now we haven’t seen how we can do something usefull. What we have to understand first is what those applications do in the background as well as the life cycle of a libgdx application on the desktop and on Android.

On the desktop what happens is that a Swing JFrame is created along with a GLCanvas provided by Jogl which does the heavy lifting. To have continuous rendering a seperate thread is started which permanently tells the GLCanvas to redraw itself. The redrawing happens in the GUI thread on the desktop. On Android a new Activity is started and a GLSurfaceView is set as it’s content view. Additionally the GLSurfaceView starts a new thread which continuously renders the GLSurfaceView anew. The GUI thread is a different thread than the rendering thread on Android.

On Android we have become acustomed to the fact that an Activity can be paused and resumed at any time. An application is paused when an incoming call arrives or the user presses the home button. The application is not active during the pause period but it’s VM is put to sleep (more or less). The user can decide to resume the application later on and expects to find the application in the state it was left in when he paused the application. An application can also be destroyed completely when the user presses the back button while being in the application or when the application is in a paused state and the system needs the resources it occupies. We thus normally overwrite the methods onPause, onResume and onDestroy of an Activity on Android to get notified when any of these events happens. Note that before onDestroy is invoked the onPause is first called on Android. Note also that onResume is also called after the onCreate method was called after the application started the first time.

On the desktop there is no such things as pausing and resuming. A desktop application can only be created and destroyed. However, as Android is the final deployment target libgdx is emulating the onPause, onResume and onDestroy callbacks to some extends. For this we need to register an ApplicationListener with the Application instance. Here’s how we do that:

public class MyApp implements ApplicationListener
{
   public static void main( String[] argv )  
   {
      JoglApplication app = new JoglApplication( "My App title", 480, 320, false );
      app.setApplicationListener( new MyApp() );
   }
 
   public void onResumed( Application app )
   {
      app.log( "My App", "application resumed" );
   }
 
   public void onPaused( Application app )
   {
      app.log( "My App", "application paused" );
   }
 
   public void onDestroyed( Application app )
   {
      app.log( "My App", "application destroyed" );
   }
}

public class MyAppAndroid extends AndroidApplication
{
   public void onCreate( Bundle bundle )
   {
      super.onCreate( bundle );
      initialize( false );
      setApplicationListener( new MyApp() );
   }
}

Note how we use the MyApp from the desktop project class in the Android activity. This is the common pattern all libgdx applications will employ. Write your app on the desktop and simply deploy it to Android by just implementing the above AndroidApplication activity.

Once the ApplicationListener is set it will receive notification of pause, resume and destroy events. On the desktop the onResumed method will be called once on startup. When the window is closed the onPause method is first invoked followed by a call to onDestroyed. On Android the callbacks will be called just as their Activity counter parts would be called. When the application first starts onResumed is called. When the application goes into the background due to a press of the home button or another activity taking the foreground the onPaused method will be invoked. When the application is again brought to the foreground the onResumed method is called. Finally, when the application is destroyed first the onPaused method is called followed by an invocation of onDestroyed. We thus have the same life cycle event order on the Desktop and Android with the difference the a desktop application can not be paused.

I might add the possibility to pause and resume a desktop application by minimizing the window.

We still haven’t done anything interesting. However, for the user to be happy we have to implement the life cycle correctly so it doesn’t hurt to understand it. Next time we’ll see how we can actually draw something on the screen via the Graphics instance an Application provides us.

Today i present you libgdx, the framework i wrote in december last year for doing all my android game development. I open sourced it today under the LGPL license. You can find it at http://code.google.com/p/libgdx/. In this article we’ll see how we can easily setup a new project (actually two) so we can prototype and work on the desktop allowing fast iterations and have the same desktop code run on any Android device.

What you need:

• a properly setup JDK, 32-bit (no 64-bit support at the moment i’m afraid. But you can always install several JVMs alongside each other).
• Eclipse
• Android SDK and the Eclipse adt plugin correctly setup
• Windows or Linux (sorry Apple people, don’t have a Mac, can’t test)

If you read this blog you have all that setup already anyways i assume . Now there’s 3 ways to get libgdx up and running. The first one is checking out the source code, compile it and put together a proper project with the created libs. We won’t do that as compiling the whole thing for different platforms (win32, linux) is a bit of a hassle at the moment. The second way is to download the current release of libgdx from the google code site. You can find the most up to date version at http://libgdx.googlecode.com/files/gdx-0.2.zip. In there is a README file that explains you how to setup your own projects. For this post we are gonna use the 3rd way of setting up a libgdx project and that is by downloading the template “hello world” zip file from http://libgdx.googlecode.com/files/gdx-helloworld.zip.

Extract that zip file into your workspace and import the two projects contained in there. This is what you’ll see in your package explorer:

The first project we have a look at is the gdx-helloworld project. It has a couple of jars and shared libraries in the libs/ folder. Two of them are easily identifieable as libgdx jars, one containing the class files, the other containing the sources. The sources are in there so we have java docs when we write our libgdx application. The third jar called desktop-dependencies contains all the 3rd party libraries that libgdx uses on the desktop to for example decode ogg files and so on. Additionally there’s shared libraries which come for windows 32-bit and linux 32-bit and contain the native code of libgdx (to date this contains the native mp3 decoder). If you want to setup your own project you simply copy over this libs/ folder to your new project and add the contained jars to your java project. The armeabi/ folder are technically not needed in the Java project but i was to lazy to remove them

The second project is called gdx-helloworld-android. It also has a libs/ folder that contains the libgdx jar file as well as a subfolder called armeabi/ containing a shared library libgdx.so. We don’t need the desktop-dependencies.jar here as that won’t work on Android anyways.

Let’s have a look at what the HelloWorld.java file of the Java project contains:

package com.badlogic.gdx.helloworld;
package com.badlogic.gdx.helloworld;
 
import com.badlogic.gdx.Application;
import com.badlogic.gdx.RenderListener;
import com.badlogic.gdx.backends.desktop.JoglApplication;
 
 
public class HelloWorld implements RenderListener 
{
	public static void main( String[] argv )
	{
		JoglApplication app = new JoglApplication( "Hello World", 480, 320, false );
		app.getGraphics().setRenderListener( new HelloWorld() );
	}
 
	@Override
	public void dispose(Application app) 
	{	
 
	}
 
	@Override
	public void render(Application app) 
	{	
 
	}
 
	@Override
	public void surfaceChanged(Application app, int width, int height) 
	{	
 
	}
 
	@Override
	public void surfaceCreated(Application app) 
	{	
 
	}	
}

That’s the most basic libgdx application you can write. We start of by stating that the class HelloWorld implements the interface RenderListener. We’ll get to that in a later article. Next we have a nice little main function that instantiates a JoglApplication with certain properties (title, dimensions, whether to use OpenGL ES 2.0) and register a new instance of HelloWorld with it. The following method stubs are the implementation of the RenderListener interface. To start this application we create a new run configuration. As libgdx has part of its functionality implemented in native code we have to tell the JVM where to find the shared library. For this we go to the arguments tab of the run configuration and enter “-Djava.library.path=libs/” as the VM arguments:

If we run that we get the following output:

Black is beautiful. What we just did was setting up a complete application which initiates OpenGL in the background and creates a rendering thread which invokes the RenderListener.render() method of all registered RenderListeners, in our case that’s the HelloWorld instance.

Now we want to run the same RenderListener on Android. Let’s have a look at the GDXHelloWorld.java file in the Android project:

package com.badlogic.gdx;
 
import android.os.Bundle;
 
import com.badlogic.gdx.backends.android.AndroidApplication;
import com.badlogic.gdx.helloworld.HelloWorld;
 
public class GDXHelloWorld extends AndroidApplication
{
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        initialize( false );
        getGraphics().addRenderListener( new HelloWorld() );
    }
}

Now that is sleek. GDXHelloWorld is derived from AndroidApplication which is analogous to JoglApplication on the desktop. Both implement the Application interface which essentially hides all the platform specifics for us. The only plattform specific thing we have to code up is the instantiation of a proper Application subclass (either JoglApplication or AndroidApplication) and register a RenderListener with it. Here we see that instead of loading any views in the onCreate() method we first call the super.onCreate() method which does nothing fance. Next we call the AndroidApplication.initialize() method which sets up all the OpenGL and input things for us, much like the constructor of the JoglApplication does. Finally we set a RenderListener, in this case a new HelloWorld instance. This is the same class we defined in our Java project. The android project thus has to reference the Java project for this to work. Now create a run configuration for this activity and try it on the emulator or device. Here’s the result:

What have we done? We setup an OpenGL ES application on Android which runs the same code as the desktop version! From now on we don’t have to touch the Android project anymore as we’ll do all our development in the Java project. Via the link between the java and the Android project the later always has an up to date version of the HelloWorld class which is used as a RenderListener. The only time we modify the Android project is when we add Assets.

A black screen is not really interesting, so let’s draw something. As you might have guessed, the RenderListener interface we implemented is called each time a new frame has to be drawn, much like the Renderer interface of the GLSurfaceView works. The RenderListener.surfaceCreated() method is called once when we first register the RenderListener. In that method we are going to put all our initialization code, like loading textures and meshes. Once everything is setup the rendering thread is repeatedly calling the RenderListener.render() method. This is were we will do all our rendering. If you write a game you can also do your game logic in there, though some advocate to do that in a seperate thread and synchronize it with the rendering thread. I honestly don’t like this approach and have used the “do everything in the rendering thread” approach in all of my games so far. Finally, when the application is closing the RenderListener.dispose() method is called giving you a chance to save any data before exit. In a later article we’ll look into the RendererListener interface in detail as well as into the ApplicationListener interface which both together manage the life cycle of a libgdx application.

To make the hello world example a little bit more interesting let’s add a triangle. For this we simply construct a Mesh as well as a MeshRenderer. A Mesh holds the geometry for a model while the MeshRenderer is responsible for making OpenGL render the Mesh. Here’s a slightly extended version of the HelloWorld class showing you how to create a simple triangle.

package com.badlogic.gdx.helloworld;
 
import com.badlogic.gdx.Application;
import com.badlogic.gdx.RenderListener;
import com.badlogic.gdx.backends.desktop.JoglApplication;
import com.badlogic.gdx.graphics.FloatMesh;
import com.badlogic.gdx.graphics.GL10;
import com.badlogic.gdx.graphics.Mesh;
import com.badlogic.gdx.graphics.MeshRenderer;
 
 
public class HelloWorld implements RenderListener 
{
	MeshRenderer mesh;
 
	public static void main( String[] argv )
	{
		JoglApplication app = new JoglApplication( "Hello World", 480, 320, false );
		app.getGraphics().setRenderListener( new HelloWorld() );
	}
 
	@Override
	public void dispose(Application app) 
	{	
 
	}
 
	@Override
	public void render(Application app) 
	{	
		mesh.render( GL10.GL_TRIANGLES );
	}
 
	@Override
	public void surfaceChanged(Application app, int width, int height) 
	{	
 
	}
 
	@Override
	public void surfaceCreated(Application app) 
	{	
		Mesh m = new FloatMesh( 3, 3, false, false, false, 0, 0, false, 0 );
		m.setVertices( new float[] { -0.5f, -0.5f, 0, 
									  0.5f, -0.5f, 0,
									  0.0f,  0.5f, 0 } );
		mesh = new MeshRenderer( app.getGraphics().getGL10(), m, true, true );
	}	
}

I won’t go into the details of the Mesh and MeshRenderer class here as this is the topic of a later article. However, it should be straight forward to figure out what we do. We create a Mesh, set it’s vertices and then create a new MeshRenderer responsible for rendering that Mesh. This happens in the HelloWorld.surfaceCreated() method which get’s called once at start up. In the HelloWorld.render() we then simply call the MeshRenderer.render() method telling it that it should draw its data as triangles. Note that we use OpenGL constants here! Libgdx is tightly integrated with OpenGL ES for better or worse. Many graphics related classes will allow you to use familiar OpenGL constants and so on. We’ll talk more about that in a later article. Here’s the awesome output of the above program:

Yay, a triangle! Now here comes the beauty of libgdx. We don’t have any extra steps to do for that to work on Android. Simply execute the Android run configuration and check the output!

Nice, i like! That’s it for now. In the coming weeks i’ll introduce all the featuers of libgdx one by one. Libgdx encapsulates all necessary things like graphics, audio, user input and file i/o in a platform agnostic way so you can develop on the desktop and deploy to the mobile device seamlessly. So there’s a lot of things to learn. In the meantime you can check out the source code and read the Java doc. Everything is documented and should allow you to get up and running.

Have fun.