In the image, I’ve set the debugger to show memory usage.  In this case it’s “lcduispace” — the top process on the list.  Next, I decided to try out the technique I described in my earlier post:  use the same lcdui game implementation, but write each frame into an image buffer and transfer it from the MIDP Graphics implementation to RIM’s proprietary implementation to display it in a RIMlet.  Here it is in the debugger:

This time the relevant process is “spacesprite,” shown at the bottom of the list.  You can see that — as expected — it’s using a lot more memory than the other implementation.

Next, I tried doing my own custom implementation of the Sprite and background functionality, using just the RIM graphics classes.  This is where I got a bit of a surprise in the debugger:

Again, it’s “spacesprite” (at the bottom of the list).  The odd thing is that this implementation doesn’t seem to be using any less memory than the implementation that copies the entire game image from one array to another for every frame of the game.  I’m not sure why — I can only guess that perhaps the RIM graphics components all by themselves consume a lot of memory, whereas the array copy is using memory in an efficient way.

It also demonstrates that this kind of memory profiling doesn’t give you all of the information you need.  Even though the two implementations are comparable in memory usage, the first one (which copies the image data) was visibly slow on a low-end BlackBerry smartphone, whereas the second implementation ran great on the same device.  So even if the array copy isn’t costing too much memory, it must cost a fair amount of processing time.

Then, for fun, I compared these two implementations against two SVG implementations.  The first just plays a fixed movie:

And in the second the user can actually drive the rocket ship around the screen:

You can see that these two used a bit more memory, but not too much.

As I’ve said, all of these are experiments that I did while writing my book Learn BlackBerry Games Development.  If you’d like to see how these examples work, just download the complete projects here.  The README file explains how to compile them (it’s just a standard JDE workspace, so you should be able to open and compile it in any BlackBerry JDE with version >= 4.6.1), and also explains how to switch the “spacesprite” project from one implementation to another.  (It’s just a question of which FieldAnimator implementation you instantiate from the SpaceManager class.)

I hope you find this example amusing and instructive.

But I wondered: What if I want to use the javax.microedition.lcdui.game package?  But I still want to take advantage of RIM’s proprietary UI component handling?  Is that even possible?  Note that you can’t just place an LCDUI Sprite onto a RIM Screen or use lcdui Images interchangeably with RIM Images.  Yet, there’s nothing to stop you from instantiating many of the lcdui graphics-related classes in a RIMlet — either type of application has access to the whole API.

Through experimentation, I found that it’s quite possible to take a game that was written using lcdui game Layers and run it in a RIMlet.  The trick is the following: To paint the Layer, call the paint() method yourself (instead of supposing the platform will do it).  First create a mutable (lcdui) Image, get its Graphics instance, and send it to the Layer’s paint() method (to render the layer into an Image buffer).  As I said, this Image can’t be placed directly into a RIM UI Component or Container, but its underlying RGB data array has the same format/structure as a RIM Bitmap.  So you can use getRGB() to get the data, then use setARGB() to place the data into a Bitmap.  Note that — despite the method name — the lcdui data array also includes the alpha channel, along with the red-green-blue.  (To see a working example, look at the ImageTransfer class in this sample code bundle.)

Now, you’re probably asking: “Wow, isn’t that incredibly inefficient?  Is it making a copy of the entire screen data array for every frame of your game (typically 20 per second)?  Wouldn’t it be simpler just to re-implement the parts of the lcdui API that you want to use for your game?”  The answers are yes, yes, and yes.  In Chapters 6 and 9 my co-author and I simply re-implemented the features we needed from the lcdui Sprite class.  (For more recent models, RIM has re-implemented the lcdui.game classes for you.)

Still, it turned out that it wasn’t quite as inefficient as I expected.  For fun, I wrote a bunch of different versions of a rocketship in space game — using a bunch of different techniques — and compared their memory consumption using the BlackBerry JDE debugger.  Here‘s the code bundle of my experiment, comparing an lcdui game implementation to a pure RIM proprietary implementation (plus I threw in an SVG implementation as well).

1. I don’t like Windows OS.  I’ll use it if I have to, but for my dev environment at home, I was just too tempted to clean the hard drive (once I’d finished my BlackBerry book), and replace the OS with Linux.  Naturally, I told myself I’d set my BlackBerry dev environment back up on some other machine or in a virtual machine or something, and — since I love installing Windows so much — you can imagine that that task hasn’t come to the top of my “to do” list.
2. I’m excited about my current job, and it’s something completely different: QA engineering for Dybuster.

Dybuster is a software suite that helps dyslexic kids learn to read.  For the kids it’s a game.  It works by giving the kids additional ways to learn words, using colors, tones, and 3D graphical representations:

Since I’ve been testing it, I can say that it has definitely improved my spelling in German.  Of course I’m not Dyslexic.

And, fortunately, there’s an English version available too (including a free downloadable demo version).

Have a look at the book’s website to get an idea of what you’ll see:

• Chapter 1. Gaming on BlackBerry!
• Chapter 2. BlackBerry Application Basics
  Why are there two types of BlackBerry Java applications? What are all those crazy files the compiler generated? And – most importantly – how do I get an application complied and running on my BlackBerry smartphone? Chapter 2 will answer all of these questions, plus help you set up a professional build with Ant.
• Chapter 3. Game Graphics and Events with MIDP and RIM Classes
  Using the classic Maze game as an example, you’ll see exactly how the two types of BlackBerry Java applications differ. You get an in-depth look at how the lifecycle, events, and graphics work in both cases so you’ll be ready to develop whichever kind is best suited to your game’s needs.
• Chapter 4. Adding a Professional Look and Feel
  Gorgeous graphics are critical for the game experience. To get your game’s visual theme pixel-perfect on every model, BlackBerry gives you the tools, and Chapter 4 explains how to use them.
• Chapter 5. Security and Selling Your Game
  As much as you love games for their own sake, at the end of the day it’s nice to get paid. In Chapter 5 you’ll see how to sell your game on BlackBerry App World (or on your own site) – plus how to apply the cryptography APIs to implement licensing and Digital Rights Management.
• Chapter 6. Swingin’ Light Saber
  With action, music, sound-effects, colliding game sprites, and even touch-screen input, Andrew shows you how to put it all together and develop a real game. Plus BlackBerry’s accelerometer lets you wield your saber like a true RIM-i Knight!
• Chapter 7. Play a Live Opponent with SMS
  That classic, tiny packet of data sent by the Short Message Service is still a favorite with users and operators alike. And it’s all you need to play a trans-atlantic game of Checkers with a friend – chosen from your BlackBerry contact list!
• Chapter 8. Using Scalable Vector Graphics
  2-D graphics are easy to master and allow you to create surprisingly impressive effects. Check out Chapter 8′s spinning spaceship video and learn the tricks to create it.
• Chapter 9. Creating Role-Playing Games on the Internet
  Since Internet everywhere is BlackBerry’s strong point, it was practically born for Massively Multiplayer Online Role-Playing Games (MMORPGs)! Chapter 9 uses Twitter to create a virtual asteroid belt that you can explore and find real people in their own virtual ships.
• Chapter 10. Remotely Drive a (toy) Sports Car
  What’s more fun than driving a remote controlled car? Driving one from your BlackBerry! Andrew illustrates Bluetooth programming in style.
• Chapter 11. Fox and Hounds
  Here’s something your stationary game console can’t do: a real live game of hot pursuit – based on GPS!
• Chapter 12. Introducing 3D with JSR 239
  Have a look at what the latest-and-greatest version 5 BlackBerry smartphones can do! Andrew explains 3-D graphics with OpenGL.

Also note: I have some “outtakes” — sample games and code that didn’t quite make it to the book but are nonetheless kind of interesting.  I’ll be posting them here over the next few months.

I recently added some tests to the automated build of a C++ project that uses Qt, which has a built-in unit testing framework: QTestLib. QTestLib seems reasonably well-designed in terms of features. There were just a couple of points I felt were missing from the tutorial, so I’m posting a few remarks for the sake of Q.A. engineers who need to dive straight into the Qt unit test framework. (Apologies in advance to C/C++ developers who will undoubtedly find these points laughably trivial…)

I’m assuming here that you’ve already done at least the first chapter of the tutorial.  If not, go do it now — it’s very short.

Done? OK, let’s get started. My #1 problem with the tutorial is that it explains how to create a stand-alone application that runs a single QTest class, but doesn’t explain how to create an application that will use QExec to run a series of QTest test suites. Like so many things in software engineering, it’s very simple (once you know the trick).  And today I’m going to tell you the trick!

I’ve gotten used to programming in Java, and I’d forgotten that a C application is only allowed to have one main() function.  Unlike in Java, if you have two program files that each have a main() function, then you can’t link them together into a single application. (This is because main() is global instead of being a class-specific method.)

Normally this isn’t a problem — just don’t write any main() functions except for the main main().  Except that the tutorial just shows you how to create a test class (in a single file) with an auto-generated main() function.  So how do I write a central application (with its own main) that can execute that set of tests in the “TestQString” class — plus execute the tests in other tests classes? The tutorial says this:

Finally, to make our test case a stand-alone executable, the following two lines are needed:

 QTEST_MAIN(TestQString)
 #include "testqstring.moc"

The QTEST_MAIN() macro expands to a simple main() method that runs all the test functions. Note that if both the declaration and the implementation of our test class are in a .cpp file, we also need to include the generated moc file to make Qt’s introspection work.

This is helpful as a start, but it kind of left me asking: What if I don’t want to put the declaration and the implementation in the same file? Then how do I include “the generated moc file” (whatever the hell that is)?

Answer: you don’t need to do anything — the generated main() function is included automatically if you have a separate header file for declarations.  Create a “TestQString.h” file and put the declaration part in it:

 #include <QtTest/QtTest>

 class TestQString: public QObject
 {
     Q_OBJECT
 private slots:
     void toUpper();
 };

Then add the #include “TestQString.h” line in the .cpp file, plus add “HEADERS += TestQString.h” to your .pro file.  The generated parts will take care of themselves in the “qmake” step.  (Again, sorry to belabor an obvious point, but I’m not the only one who was confused by this.)

Then there was one more (not-stated-in-the-tutorial-but-obvious-in-retrospect) point that I had to figure out for myself: The test class doesn’t need the generated main() in order to run the tests in sequence. The auto-generated main() runs the test in sequence — including the set-up and tear-down steps — but apparently Qtest::qExec does the same thing, without using the auto-generated main() function to do it. So if you’re using Qtest::qExec, you can just leave off the QTEST_QMAIN() entirely.

And — if you’d like to allow both options — just put the QTEST_QMAIN() statement in a separate .cpp source file (not the one where you implemented your tests). Then you can write two different project files — one that includes the source file with QTEST_QMAIN() (to build your tests in stand-alone mode), and one that leaves that file off of the SOURCES list (for when you want your tests to be run by a larger application).

Rizk’s book — being an intro book — doesn’t assume a high level of Java/programming knowledge. In Chapter 1, he warns the reader that “This book is not an introduction to object-oriented programming, or even to the Java language.” However, if you’ve taken one course in Java programming or have worked through an intro book on the subject, “Beginning BlackBerry Development” would be a fine next step. It covers all of the fundamentals of how to build and deploy a BlackBerry Java application, how the application lifecycle works, how to build a user-interface (and respond to user input), the differences among the four or more different types of data persistence on BlackBerry (and how to use them), the different types of BlackBerry network communications available, and how to program for the GPS.

They timed the book to come out in time for the holidays (as well as for a BlackBerry dev conference), and it’s true that the book would make a good gift for a technophile in your life who’s thinking of going into software engineering or for a software engineer in your life who has a BlackBerry and is thinking of maybe trying to sell an application on BlackBerry App World. (And if they like it — and want to take it to the next level with the techniques for making games on the BlackBerry — well, you can guess which book I’d recommend they try next. )

I needed an rocket sprite for my “Space Explorer” game.  Here’s what I came up with:

You can see that the four frames give a spinning effect.  (The lower row gives the frame sequence for when the engines are turned on.)  I’m more an engineer than an artist, but here’s how Inkscape and SVG made it easy for me to draw this:

The thing is that the lines of the drawing are objects that are easy to manipulate.  They’re easy to grab, modify, duplicate, and delete.  So for the animation, I just drew all of the elements onto a single drawing.  Then, I saved four copies, and on each one deleted the elements I didn’t need:

I temporarily colored different components different colors to keep track of which one was which. For the final sprite version, I filled the components with a radial gradient fill.  It’s surprising how much depth you get just from using a gradient when coloring in your sprite!

After I did one rocket sprite this way, I improved my technique while drawing a flying saucer sprite:

I started by creating a single SVG image file (in Inkscape) that contained all of the image elements:

Starting from this (SVG) image, I saved eight copies, one for each of the animation frames. You can see how drawing all of the elements onto a single drawing makes it very easy to place the different elements and to make sure that the images line up exactly from one frame to the next. Then, on each frame, I just deleted the elements I didn’t need (and changed some of the colors so that the bulbs are red when the engines are on).

Once I had my eight SVG files, it wasn’t too hard to place them all correctly into a single PNG file.  (The trouble is that they have to be placed so that the images line up exactly from one frame to the next.)

In the file menu of Inkscape, there’s an “Export Bitmap” option that allows you to export the image as a PNG file. It automatically crops the image tightly, which is quite helpful for creating frames that are all the right size. So I opened all eight PNG files in the GIMP, and created a new image that was exactly big enough to hold the eight frames.  Then I copied the eight images and pasted them all in.

The tricky part is placing each frame in exactly the right spot in the larger image.  It turns out that it’s not possible in the GIMP to select exact coordinates when pasting one image into another (eg. there’s no dialog that lets you say “paste the top left corner of the sub-image at pixel 34, 56 of the larger image”).  I Googled around for how to paste at a particular spot, and learned that it’s a feature that doesn’t exist.  And it’s particularly tricky with images that have transparent backgrounds (as sprites created in Inkscape do).  The GIMP copies only the non-transparent part of the image, so if you were using the transparent part as a guide for where to place the image within the frame, you lose that information when you do the copy-paste.

Here’s the solution I came up with:  Use the magnifying glass to expand each frame.  Then use the pencil tool to draw one black pixel in each of the bottom corners of the four bottom frames and one black pixel in each of the top corners of the for top frames. Then when I copy-paste each individual frame into the larger image, I can use the corner pixels to place the frames exactly.  There may be a simpler way to do it than that, but that was the simplest trick I found.

I had so much fun drawing spaceships, that I blew off programming for the day to draw some more:

(My 6-year-old Leo wanted one of the rockets in the game to have his name on it.)

Actually — since it’s more fun for the players if there’s a variety of interesting characters in your game’s universe — it’s nice to know that it isn’t too difficult and time-consuming to draw them.

Wrong.  The application was merely sent to the background.

I assume this behavior is mentioned somewhere in the bowels of the RIM documentation (although I’ve read quite a lot of it, and I haven’t seen mention of this). Nor do the sample applications appear to deal with it. I just figured it out when my colleague Andrew Davison sent me a game that plays music in the background. It was a tad loud, so I instinctively tried to shut it off in one click using the red key. And the game went away, but the music kept right on playing…

It reminds me of a little something I read in the PodTrapper story:

My curve has 32MB of RAM and 64MB of flash. The flash can be used for paging if it’s available, but on my device only about 20MB of it is, and that fills up fast installing applications (PodTrapper alone is 350k). Realizing that the OS and other apps also have to fit in RAM, leaking a 100kb string becomes a huge problem. There are lots of forum posts by people trying to figure out why their phone keeps running out of memory and needs to be rebooted. It’s a large enough problem that there are apps for automatically restarting your phone. I can definitely see why Apple has been hesitant to open up background processing on the iPhone. It’s really easy for bad developers to make the whole platform look bad.

Personally, I think it’s kind of cool that you can run apps in the background on BlackBerry, and send them to the foreground and back. However, I think the simplest, default behavior should lean towards cleaning up the app neatly, while sitting on memory and processes when your app goes out of scope should be a special behavior that advanced developers can request.  Not the other way around.

So what about that red key?  What if you’re developing a game or animation that makes no sense in the background, and you just want it to clean up whenever the user dismisses it?

Andrew proposed the following solution (for use in a subclass of Screen):

// keycodes for the green and red keys
private static final int GREEN_KEY = 1114112;
private static final int RED_KEY = 1179648;

protected boolean keyDown(int keycode, int time)
// terminate the game if the green or red keys are pressed
{
// System.out.println(“keyDown: ” + keycode);
if ((keycode == GREEN_KEY) || (keycode == RED_KEY)) {
isRunning = false;
return true;
}
return false;
}  // end of keyDown()

***

That works, but on some level I couldn’t help but feel like it’s absurd of RIM to expect developers to check for the key codes of the red key and green key instead of providing some sort of help.  This has got to be a fairly common scenario, doesn’t it?

Poking around the API a bit, I found it:  In your Application subclass, you implement deactivate().  Here’s the JavaDoc:

public void deactivate()
Handles backgrounding event.
The system invokes this method when sending this application to the background. By default, this method does nothing. Override this method to perform additional processing when being sent to the background.

So, if you’re writing an application that makes no sense in the background, then you implement this method and have it perform the app’s cleanup and shutdown.

Like so many aspects of BlackBerry programming, it’s quite simple once you notice the problem and figure out the trick.

If you’re interested, please leave a comment, and I’ll email you.  Thanks!