Testing Live Android Wallpapers

by Shane Conder & Lauren Darcey

With a little RenderScript and some helper files from the Android Open Source Project, you can create a dazzling Android live wallpaper.

One of the compelling user features of the Android platform is the ability to customize many aspects of the user experience. Among these is the ability to customize the home screen wallpaper with something other than a static image. A "live" wallpaper can contain images, animations, interactive features or whatever you, the developer, desires.

Live wallpapers were introduced in Android 2.1 (API Level 7). The live wallpaper we're going to build in this tutorial is a horizontally animated star field. The star field effect uses fairly simple graphics and is not the focus of the article. We've implemented the effect using RenderScript, which means we're targeting Android 3 (API Level 11) and later.

We're also going to show how Android being an open platform can be extremely helpful to developers by leveraging some open source code helper files written by the Android team.

The code to use with this tutorial is available as an open source code project.

Getting Started with Android Live Wallpapers

Live wallpapers can be part of any existing Android app or simply standalone. Essentially, a live wallpaper is a special type of Android Service (android.service.wallpaper), and it includes a service tag entry in the Android manifest file. Additionally, a resource XML file is used to define how the wallpaper will appear in the system list. We'll create a new application project from scratch, but you could just as easily add a live wallpaper to an existing app.

Start by creating a new project called StarsLiveWallpaper. In the manifest file, add a uses-feature for android.software.live_wallpaper. Set the minSdkVersion to 11 (the minimum API level required for using RenderScript). Now add a service entry for the live wallpaper we'll create, such as:

android:permission="android.permission.BIND_WALLPAPER" >
<action android:name="android.service.wallpaper.WallpaperService" />

android:resource="@xml/stars_wallpaper" />

This service entry defines the wallpaper's service information and the appropriate intent filter. Now create a new wallpaper configuration file called stars_wallpaper.xml, located in the res/xml directory. It will look like the following:

<?xml version="1.0" encoding="utf-8"?>
<wallpaper xmlns:android="http://schemas.android.com/apk/res/android"
android:description="@string/wallpaper_desc" />

You'll need to create the appropriate string resources for use by these files (e.g. @string/wallpaper_name and @string/wallpaper_desc) as well. For the thumbnail, we've simply used the launcher icon resource, but you could also supply a custom drawable icon.

Creating the Service and Engine for Android Live Wallpapers

A live wallpaper is simply an implementation of WallpaperService. A WallpaperService implementation handles a single call, onCreateEngine(), and returns a valid instance of a WallpaperService.Engine. It's the Engine class that does the work of drawing to the given Surface.

This is where some work has already been done for us. Check out the Android Open Source Project, where you'll find some live wallpaper samples built using RenderScript. The Android team made a couple of helper files called RenderScriptScene and RenderScriptWallpaper. RenderScriptWallpaper, a WallpaperService, handles creating the WallpaperService.Engine class. It's a template class that takes the RenderScriptScene class.

Sound complex? All we have to do is create a scene extending from RenderScriptScene, then return that from a super simple implementation of RenderScriptWallpaper. First, we need to get the source to these files. We've put them in the code download for this tutorial, but we originally got them from the git repository:

git clone https://android.googlesource.com/platform/packages/wallpapers/Basic.git

Then from the com.android.wallpaper package grab RenderScriptScene.java and RenderScriptWallpaper.java.

Now we can create our scene, StarsRS.java:

public class StarsRS extends RenderScriptScene {
public static final int STAR_COUNT = 2500;
private ScriptC_stars mScript;

public StarsRS(int width, int height) {
super(width, height);

protected ScriptC createScript() {
ProgramFragmentFixedFunction.Builder pfb = new ProgramFragmentFixedFunction.Builder(

ScriptField_Star stars = new ScriptField_Star(mRS, STAR_COUNT);
Mesh.AllocationBuilder smb = new Mesh.AllocationBuilder(mRS);
Mesh sm = smb.create();

mScript = new ScriptC_stars(mRS, getResources(), R.raw.stars);
return mScript;


Here, we load the RenderScript that we created (found in stars.rs in the source code download, the graphics details of which are beyond the scope of this tutorial) and configure it. The script is then returned for use by RenderScriptWallpaper.

Next, we need to implement our wallpaper service:

public class StarsWallpaperService extends RenderScriptWallpaper {
protected StarsRS createScene(int width, int height) {
return new StarsRS(width, height);

We did say it was a super simple implementation, right?

Although that's all there is to creating the wallpaper, we've added a StarsLiveWallpaperActivity class as well as StarsTestView, used on that Activity. These additions provide a launcher icon and activity that will both show what the wallpaper will look like as well as provide a simple button to launch into the wallpaper settings. You can find the source code to these two classes in the sample code download.

Testing the Live Android Wallpaper

If you've done everything right, then when you press and hold on the wallpaper of your home screen (at least, in Android 4) you'll get the following dialog.

Android Live Wallpaper
Click here for larger image

Figure 1. Android Wallpaper Dialog on Home Screen

After that, you'll get a list of all the live wallpapers available:

Android Live Wallpaper
Click here for larger image

Figure 2. List of All Available Android Wallpapers

And then an animated preview, when you choose Stars.

Android Live Wallpaper
Click here for larger image

Figure 3. Animated Preview of Stars Android Wallpaper

Android Interactive Wallpapers

Live wallpapers can receive touch events and react to them. In the context of using the helper classes introduced above, simply override the onCommand() method of RenderScriptScene, look for the WallpaperManager.COMMAND_TAP, and take some action based on the position of the tap. Although this is beyond the scope of this tutorial, the code download includes a little extra for readers to enjoy.


You've learned how to create a simple Android live wallpaper. While doing so, you've also learned about some of the benefits of open source projects, and a fast method of creating a RenderScript-based wallpaper. Can you modify the script to make colored stars? Make the stars float towards you? Let us know what awesome live wallpapers you've created!

About the Authors

Shane Conder Shane Conder and Lauren Darcey--Contributing Editors, Mobile Development--have coauthored two books on Android development: an in-depth programming book entitled Android Wireless Application Development (ISBN-13: 978-0-321-62709-4) and Sams Teach Yourself Android Application Development in 24 Hours (ISBN-13: 978-0-321-67335-0). When not writing, they spend their time developing mobile software at their company and providing consulting services.

        Email        |        Blog        |        Twitter

Lauren Darcey
This article was originally published on Wednesday Jan 25th 2012
Mobile Site | Full Site