Cross-platform Development – Build Once, Deploy Anywhere

Cross-platform Development – Build Once, Deploy Anywhere

you will learn more about the generated Eclipse projects and how
they work together. Also, you will learn more about the following components of
the Libgdx framework:
•  Backends
•  Modules
•  Application Life-Cycle and Interface
•  Starter Classes
At the end of this chapter, you will take a closer look at the demo application and
inspect the generated code of the Main class in great detail. You will learn how to
set breakpoints, run the application in debug mode, and speed up your overall
productivity with the awesome JVM Code Hot Swapping feature. The discussion
on the demo application ends with some simple and fun modifications to the code

accompanied by a demonstration of the JVM Code Hot Swapping feature

The demo application – how the projects
work together
 Introduction to Libgdx and Project Setup, we successfully created our demo
application, but we did not look at how all the Eclipse projects work together. Take
a look at the following diagram to understand and familiarize yourself with the
configuration pattern that all of your Libgdx applications will have in common:

What you see here is a compact view of four projects. The demo project to the very
left contains the shared code that is referenced (that is, added to the build path) by
all the other platform-specific projects. The main class of the demo application is
MyDemo.java. However, looking at it from a more technical view, the main class
where an application gets started by the operating system, which will be referred to
as Starter Classes from now on. Notice that Libgdx uses the term "Starter Class" to
distinguish between these two types of main classes in order to avoid confusion.
We will cover everything related to the topic of Starter Classes
in a moment.
While taking a closer look at all these directories in the preceding screenshot, you
may have spotted that there are two assets folders: one in the demo-desktop project
and another one in demo-android. This brings us to the question, where should you
put all the application's assets? The demo-android project plays a special role in this
case. In the preceding screenshot, you see a subfolder called data, which contains an
image named libgdx.png, and it also appears in the demo-desktop project in the
same place.

Just remember to always put all of your assets into the assets folder 
under the demo-android project. The reason behind this is that the 
Android build process requires direct access to the application's 
assets folder. During its build process, a Java source file, R.java, 
will automatically be generated under the gen folder. It contains special 
information for Android about the available assets. It would be the usual 
way to access assets through Java code if you were explicitly writing an 
Android application. However, in Libgdx, you will want to stay platform-independent as much as possible and access any resource such as assets 
only through methods provided by Libgdx. 

You may wonder how the other platform-specific projects will be able to access the 

very same assets without having to maintain several copies per project. Needless to 

say that this would require you to keep all copies manually synchronized each time 

the assets change.

Luckily, this problem has already been taken care of by the generator as follows:

The demo-desktop project uses a linked resource, a feature by Eclipse, to add 

existing files or folders to other places in a workspace. You can check this out by 

right-clicking on the demo-desktop project then navigating to Properties |  

Resource | Linked Resources and clicking on the Linked Resources tab.

The demo-html project requires another approach since Google Web Toolkit (GWT) 

has a different build process compared to the other projects. There is a special 

file GwtDefinition.gwt.xml that allows you to set the asset path by setting the 

configuration property gdx.assetpath, to the assets folder of the Android project. 

Notice that it is good practice to use relative paths such as ../demo-android/

assets so that the reference does not get broken in case the workspace is moved 

from its original location. Take this advice as a precaution to protect you and maybe 

your fellow developers too from wasting precious time on something that can be 

easily avoided by using the right setup right from the beginning.

The following is the code listing for GwtDefinition.gwt.xml from demo-html:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE module PUBLIC "-//Google Inc.//DTD Google Web Toolkit

  trunk//EN" "http://google-web-toolkit.googlecode.com/svn/trunk/

    distro-source/core/src/gwt-module.dtd">

<module>

<inherits name='com.badlogic.gdx.backends.gdx_backends_gwt' />

<inherits name='MyDemo' />

<entry-point  class='com.packtpub.libgdx.demo.client.GwtLauncher' />

  <set-configuration-property name="gdx.assetpath"

    value="../demo-android/assets" />

</module>

Backends

Libgdx makes use of several other libraries to interface the specifics of each platform 

in order to provide cross-platform support for your applications. Generally, a 

backend is what enables Libgdx to access the corresponding platform functionalities 

when one of the abstracted (platform-independent) Libgdx methods is called. For 

example, drawing an image to the upper-left corner of the screen, playing a sound 

file at a volume of 80 percent, or reading and writing from/to a file.

Libgdx currently provides the following three backends:

•  LWJGL (Lightweight Java Game Library)

•  Android

•  JavaScript/WebGL

LWJGL (Lightweight Java Game Library)

LWJGL (Lightweight Java Game Library) is an open source Java library originally 

started by Caspian Rychlik-Prince to ease game development in terms of accessing 

the hardware resources on desktop systems. In Libgdx, it is used for the desktop 

backend to support all the major desktop operating systems, such as Windows, 

Linux, and Mac OS X.

For more details, check out the official LWJGL website at http://www.lwjgl.org/.

Android

Google frequently releases and updates their official Android SDK. This represents 

the foundation for Libgdx to support Android in the form of a backend.

There is an API Guide available which explains everything the Android SDK has to 

offer for Android developers. You can find it at http://developer.android.com/

guide/components/index.html.

WebGL

WebGL support is one of the latest additions to the Libgdx framework. This backend 

uses the GWT to translate Java code into JavaScript and SoundManager2 (SM2), 

among others, to add a combined support for HTML5, WebGL, and audio  

playback. Note that this backend requires a WebGL-capable web browser  

to run the application.

You might want to check out the official website of GWT:  

https://developers.google.com/web-toolkit/.

You might want to check out the official website of SM2:  

http://www.schillmania.com/projects/soundmanager2/.

You might want to check out the official website of WebGL:  

http://www.khronos.org/webgl/.

There is also a list of unresolved issues you might want to check out at  

https://github.com/libgdx/libgdx/blob/master/backends/gdx-backends-gwt/issues.txt

Modules

Libgdx provides six core modules that allow you to access the various parts of the 

system your application will run on. What makes these modules so great for you 

as a developer is that they provide you with a single Application Programming 

Interface (API) to achieve the same effect on more than just one platform. This is 

extremely powerful because you can now focus on your own application and you 

do not have to bother with the specialties that each platform inevitably brings, 

including the nasty little bugs that may require tricky workarounds. This is all going 

to be transparently handled in a straightforward API which is categorized into logic 

modules and is globally available anywhere in your code, since every module is 

accessible as a static field in the Gdx class.

Naturally, Libgdx does always allow you to create multiple code paths for  

per-platform decisions. For example, you could conditionally increase the level  

of detail in a game when run on the desktop platform, since desktops usually  

have a lot more computing power than mobile devices.

The application module

The application module can be accessed through Gdx.app. It gives you access to the 

logging facility, a method to shutdown gracefully, persist data, query the Android 

API version, query the platform type, and query the memory usage.

Logging

Libgdx employs its own logging facility. You can choose a log level to filter what 

should be printed to the platform's console. The default log level is LOG_INFO. You 

can use a settings file and/or change the log level dynamically at runtime using the 

following code line:

Gdx.app.setLogLevel(Application.LOG_DEBUG);

The available log levels are:

•  LOG_NONE: This prints no logs. The logging is completely disabled.

•  LOG_ERROR: This prints error logs only.

•  LOG_INFO: This prints error and info logs.

•  LOG_DEBUG: This prints error, info, and debug logs.

To write an info, debug, or an error log to the console, use the following listings:

Gdx.app.log("MyDemoTag", "This is an info log.");

Gdx.app.debug("MyDemoTag", "This is a debug log.");

Gdx.app.error("MyDemoTag", "This is an error log.");

Shutting down gracefully

You can tell Libgdx to shutdown the running application. The framework will then 

stop the execution in the correct order as soon as possible and completely de-allocate 

any memory that is still in use, freeing both Java and the native heap. Use the 

following listing to initiate a graceful shutdown of your application:

Gdx.app.exit();

You should always do a graceful shutdown when you want to 

terminate your application. Otherwise, you will risk creating 

memory leaks, which is a really bad thing. On mobile devices, 

memory leaks will probably have the biggest negative impact 

due to their limited resources.