vendredi 1 janvier 2016

Pack textures and fonts at build time for your LibGDX project

When working with LibGDX and openGL ES we usually need to provide our application with various assets such as :
  • PNG for textures
  • Fonts (whether BitmapFont or FreeTypeFont) for texts
  • Sounds
  • 3D objects
  • etc...
When designing the application, we need to take care of :
  • Reducing the loading time of the assets by reducing the number of required assets
  • Reducing the rendering time of the required assets by packing assets together 
  • Reducing the integration time of the required assets by handling assets generation as part of the automated build process
A way of doing this is to pack all the required PNG for textures into a single TextureAtlas asset. LibGDX provides a TexturePacker utility for that. Some other third party utilities are usefull to generate BitmapFont that can be loaded by the LibGDX runtime.

As an experimented developper, we should expect regular changes among our application design during the development phase which means we should whether re-generate fonts and re-pack textures everytime or work with an application that is not efficient to load and to render (without packed assets and BitmapFont)... As a lazy developper, we might want all the assle of font and texture generation and packing to be handled automagically by the gradle build process.

Here is how we can achieve this...

The big picture

Okay, so let say we want to build an UI that renders a deck of cards using LibGDX :

Card Deck rendered with resources generated at build time

The UI is made of 52 sprites (one for each card) and a BitmapFont to render the label "LibGDX Card Deck"... Everything is laid out with a simple Table. What we want is to be able to change the finest detail with a little effort. For instance :
  • change the red tone used for hearts and diamonds
  • change the shape, the aspect ratio of the card
  • increase the size of the rank
  • decrease the size of the suite
  • change the position of the rank / suit inside the card
  • change the font used for the label

Project layout

When setting up a new LibGDX project you get something like this :

+ rootProject.projectDir
|--+ android
     |--+ assets
     |--+ build

     |--+ res
     |--+ src
     |--+ build.gradle
|--+ core
     |--+ src
     |--+ build.gradle
|--+ desktop
     |--+ src
     |--+ build.gradle
|--+ html

|--+ ios
|--+ resources
|--+ build.gradle

Where the ${rootProject.projectDir}/android/assets directory holds the assets required by the application (whatever the targeted platform : android, desktop, html or ios). So what we are going to do is to create a ${rootProject.projectDir}/resources directory containing the source files used to generate the required assets at build time. Intermediate temporary files will be generated into the ${rootProject.projectDir}/android/build directory.

Design of the cards

To design our card, we are going to use a SVG card pattern wich will define the overall aspect of the card : its shape and the position of the rank and the suit inside the shape. The SVG file will look something like this :

This SVG card pattern pattern use the custom SVGMASK file format defined by the AndroidSvgDrawable library. This allow us to generate all of the 52 combination of card rank x card suit without the need of 52 SVG files...

Then, we need 4 SVG files for suits (one for each card suit) and 13 SVG files for ranks (one for each card rank from 2 to A). Here are the sample files for Heart and King :


That's it, let see how we can now generate all of our 52 card textures at build time...

Generating the card textures

To generate the 52 textures, we will use the AndroidSvgDrawable plugin that now integrates better with LibGDX. First, we need to add the plugin dependency to our buildscript classpath in ${rootProject.projectDir}/build.gradle :

Then, we define a custom task in our ${rootProject.projectDir}/desktop/build.gradle file :

This will take the SVG card pattern file we put inside ${rootProject.projectDir}/resources/svg/mask and generate a PNG file for each SVG suit file x SVG rank file we put into ${rootProject.projectDir}/resources/svg/masked :



Generating the BitmapFont and the TextureAtlas

In order to generate the BitmapFont and the TextureAtlas at build time, we will rely on the API provided by LibGDX (we must use at least version 1.7.3-SNAPSHOT in order to be able to generate the BitmapFont as mentionned bellow). We should then add the necessary dependencies to our buildscript classpath in ${rootProject.projectDir}/build.gradle :

Most of the time, LibGDX APIs requires the LibGDX runtime to be loaded first, so we must add a specific task in our ${rootProject.projectDir}/desktop/build.gradle file that will load an headless LibGDX runtime for the build purpose :

Generating the BitmapFont

The BitmapFont will be generated from a TrueType font located in the ${rootProject.projectDir}/resources/font directory. A custom task in our ${rootProject.projectDir}/desktop/build.gradle file will generate the BitmapFont for us with the desired parameter :

A BitmapFont is made of 2 files :
  • a .fnt file that will be output in the ${rootProject.projectDir}/android/assets directory directly
  • a .png file that will be output in the ${rootProject.projectDir}/android/build/generated/assets directory because we want to merge it later with the others texture inside our final TextureAtlas...
You can refer to the LibGDX freetype documentation to customize the task to generate the desired font appearence. You can also use a more complexe task to generate BitmapFont of different size, colors, ...

Generating the Atlas

As all the required PNG are now generated inside the ${rootProject.projectDir}/android/build/generated/assets directory, we are now ready to pack them all inside a single TextureAtlas. Once again, we use a custom task in our ${rootProject.projectDir}/desktop/build.gradle file that will do the job for us :

And here is the final skin.png TextureAtlas generated with a default size of 1024 x 1024 that is available in the ${rootProject.projectDir}/android/assets directory along with its skin.atlas descriptor :

Once again you can refer to the LibGDX Texture packer documentation for more packing options and a finest control over the generated atlas. Note that LibGDX Texture packer support packing of NinePatch drawable that could be generated at build time with the AndroidSvgDrawable plugin.

Let's build it

In order to chain all of those tasks together, we bind the compileJava task from the java gradle plugin to our custom generateATLAS task :

Here we are, everything is ready, we can just sit and watch gradle work for us :

gradlew desktop:run

:core:processResources UP-TO-DATE
:desktop:initHeadlessLibGDX UP-TO-DATE
Writing 1024x1024: android\assets\skin.png
:desktop:processResources UP-TO-DATE


Total time: 11.758 secs

And if we build it once again, the Gradle magic happens, nothing is re-generated or re-packed because everything is UP-TO-DATE :

gradlew desktop:run

:core:compileJava UP-TO-DATE
:core:processResources UP-TO-DATE
:core:classes UP-TO-DATE
:core:jar UP-TO-DATE
:desktop:initHeadlessLibGDX UP-TO-DATE
:desktop:generateFONT UP-TO-DATE
:desktop:generatePNG UP-TO-DATE
:desktop:generateATLAS UP-TO-DATE
:desktop:compileJava UP-TO-DATE
:desktop:processResources UP-TO-DATE
:desktop:classes UP-TO-DATE


Loading and rendering the assets

Loading the assets requires only a single atlas to be loaded by the application while rendering all the cards and the label will bind a single OpenGL ES texture :

Want to be more optimal ? We can't !

Changing a detail

One more thing ! It's now possible to change the card layout for all our cards by changing only one file. If I modify the SVG card pattern to have the suit in the center of the card and the rank in the upper left corner and the lower right corner as well :

When building the project once again :

gradlew desktop:run

:core:processResources UP-TO-DATE
:desktop:initHeadlessLibGDX UP-TO-DATE
:desktop:generateFONT UP-TO-DATE
Writing 1024x1024: android\assets\skin.png
:desktop:processResources UP-TO-DATE


Total time: 11.758 secs

Then, the layout has been changed for all of the 52 cards :

Simple isn't it ?

You can find the whole LibGDX project in the sample directory of the AndroisSvgDrawable plugin GitHub project.

samedi 5 décembre 2015

How a rate button can actually improve your mobile app rating

When I decided to redesign my Android Spirit Level this summer, I was wondering wether or not I should add a "Rate" button to invite users to rate the Bubble Level application.

Get it on Google Play

What I was expecting was more feature requests and a better user feadback. I was also concern about how such a button could annoy users... In the long term, would it lead to a better user rating or a lower user rating ? Here is the answer :

Evolution of the app overall rating
Since the update of late august that added the rate button in the app, overall rating of the app increased faster than before... User feedback was also better because of the easy way to provide it when you see something wrong, something missing or something to improove. In the contrary, number of rates per month does not increase as expected :

Rates per month per value and average rating

I'm not sure wether or not this stat reflect rate that get updated by users... But to provide you with more stats, the rate button has a click to rate rate ;-) of 1 generated rate out of 16 clicks... which is quite low but sufficient to increase the overall rating of the app.

mercredi 29 avril 2015

Certificat based client authentication with apache server

This post describe how to create and use a custom certification authority to generate client certificate that will later be used to authenticate users against apache mod_ssl and pass the credential to the underlying server that processes the client requests : Tomcat, JBOSS or anything else... Apache mod_ssl will be configured to use client certificat based strong authentication that only accept requests that comes from clients presenting a certificat signed by a trusted authority.

Creating the certificates

Certification authority

The first step is to generate our own certification authority certificate. This will be done using standard openssl command to generate a RSA key stored under ca.key. This key will be used to generate a self signed certificate under ca.crt :
The RSA key of our own authority
The self signed certificate associated with our authority
The public key of our authority

Server certificate

The server certificate will be used by the server and presented to the client. It will be signed by the certification authority certificate created above. During the certificate signing request, we'll be asked for a Distinguished Name (DN) or Common Name (CN). The value of that field MUST match the ServerName used in the Apache httpd.conf configuration file. The generation of an unprotected key will allow apache to start without the prompt of a passphrase... which might be useful in some cases.

Client certificate

The client certificate is generated like the server certificate. Each client will have its own certificate that uniquely identifies him. It will be signed by the same certification authority. during the creation of the X.509 client certificat, you'll be prompted for Subject informations. Those informations will be used as credentials to authenticate the user on the underlying server that actually processes the request.

Apache server configuration

The Apache server will be configured to only accept requests that comes from clients presenting a client certificate that is signed by our own certification authority. This is done in the httpd.conf by using those directives in the dedicated SSL VirtualHost :

The require value force the client to provide its own X.509 certificate during the SSL handshake.
Specifies the minimum depth that will be scanned by the server to check for trusted certification authority in the client certificate. A value of 0 will only allow self signed certificates. A value of 1 will accept both self signed certificates and certificates signed by an authority known by the server. In our case, we will use a value of 2 that will only accept certificates signed by an authority known by the server.
Specifies the trusted certification authorities.
Thus, only the requests signed by our clients will be authorized.
Fork me on GitHub