Weekend project: porting a game to QVGA

Following a mediaplayer, games would be next thing people ask for Angstrom. So, I decided to look what would be good candidates to add to feed. There're bunch of different games' recipes in OE, but I was thinking about some catchy, dynamic arcade. Of course, SuperTux came to mind! ;-)

OE already has recipe for SuperTux, and quick try in QEMU showed it works. In VGA mode. Attempt to run with QVGA screen resulted only in error that suitable video mode cannot be found. So, I decided to see if quick hack could solve this, and then document what it would take to do so.

Quick look at the source code showed that it is one of the critical cases of software engineering - 640x480 resolution is deadly hardcoded, with numeric coordinates spread around the code. Fortunately, short after I spent 10 mins figuring where to stuff divisions by 2, I googled for "supertux qvga". Hits followed! SuperTux was ported to GP2X and even to WinCE. I took GP2X version to look at.

GP2X port is nice produce of folks who have motivation to do something, but don't know what the diff is ;-). It was also done against SuperTux 0.1.3, while OE had 0.1.2. On the way, I bumped OE's version to 0.1.3 too, while finding that fixed-point patch for 0.1.2 no longer applies to 0.1.3 (will need to rediff). Finally, making diff out of GP2X version and cutting off changes related to autoconf-generated files, I got ~70K patch implementing --enable-320x240 and --enable-gp2x options (adding those was neat, unlike not producing a diff). Applying that patch on top of pristine 0.1.3 (with bitbake recipe of course!) and cleaning off some sloppy gp2x changes which were compiled in even though --enable-gp2x was not given, I finally got the package built. Quickly checking that it doesn't work in 240x320 mode, I had it run with xrandr applied, just to see garbaged fonts and graphics. Of course! Of course gp2x patch doesn't resize the original graphics on the fly, but expects it to be downscaled already, even though such gfx is not included in source archive. I pulled it from binary package though, and few minutes later saw the expected fun:


So, thank you scachi (Ingo Arndt) for doing all the fun work, and leaving dirty work of cleaning it all up to me! ;-D

On that route I proceeded, and next task was figuring out what to do with graphics. Having a binary drop of graphics was for sure no more acceptable than a complete source archive instead of diff. We talk port here, not something. I still don't target that at upstream, but not because it's not worth being there, but because it would be hard to explain what's it all about to people who write draw(537, 39) ;-(. Nonetheless, QVGA graphics must be produced from upstream version during build time. Just few days before I heard pH5 talking about imagemagick-native, so having checked it was not in OE (while target version was), I caught him on IRC to find out that it belongs to "would be nice to have" category. 15mins later it was there, fortunately "inherit native" was all needed for it.

My initial attempts at resizing original SuperTux graphics at 50% proved to give rather bad results, having size as big as original, or even bigger, and for sure much bigger than gp2x versions. But man'ing thru and recalling my old ImageMagick experience quickly gave its fruit by applying adequate color quantization after resize (I used --colors 64). Adding pngcrush-native and running magick's images thru it was final touch - in the end, I got image set ~30% smaller than gp2x's, while still looking better!

What's next? Too big a package. It would be nice to let people install this thing to flash, plus I target it for inclusion in LiveRamdisks, so 6.5Mb compressed package was not very bright. Glancing over data files shipped with SuperTux, it turned that music/ is nice candidate for slimming. First of all, there're few duplicate tunes, just one copy with "fast" suffix. Size was same, and diffing them, there were handful byte changed. Looking thru code, "fast" version is played when level's time limit is running out. I llluv that feature! But not at the expense of my flash ;-I. "fast" version went to /dev/null for the QVGA, and now, small-size version. Secondly, there was a credit.ogg file, which gp2x port replaced with some .xm. Trying .ogg still, I found that SDL can't scroll screen and play 160kbit ogg at the same time, on PXA 400MHz. So, bye, .ogg, good riddance! And thanks gp2x again for offering a replacement.

Now I finally decided to run game on full-fledged hardware - h4000, as earlier I ran it in QEMU and on h3900, which lacks audio. It immediately crashed on startup, complaining about not being bale to load a .mod music. A check of source, then libsdl-mixer recipe and - the latter has mikmod support disabled. Poor. With it on, I finally have a nice, commercial-grade arcade running on a Linux PDA! I even was able to quickly finish couple of levels, even though controlling PDA in a landscape position is not ideal.

Final touch I made was extracting bonus levels to separate packages. Level description are text files, taking more than a megabyte in raw size, but packages turned out to be ~50K. Well, let's save space for ext2 people nonetheless, and most importantly, have a complete experience of what it takes to produce a nice PDA port of a game.

So, that's how it was. I took time to write this long, if not detailed, description, in the hope that it will both motivate people to port games to OE/Angstrom, and will give hints how to do that. So, let's hope that people will care for their favorite OpenSource games, or choose to have such a weekend fun ;-). Otherwise, thinking about it, games are likely the best candidates for bounty-sponsored porting - after all, due to the manner many games are written, it's not too easy to port them to a lower resolution/smaller size/more CPU efficiency. So, if people want more fun, they should take the fun of doing a port (it's much more fun than playing a game itself, trust me ;-D ), or motivate other people who want to do that ;-).


Oh, and back to tux the super: the supertux-qvga recipe should land soon in OE. I hope to dump packages to unstable feed too. Then, there're following TODOs before it's perfect:

1. Forward-port fixed-point patch to 0.1.3 (I get ~25fps with sound, and that's not too much, and there's jerky scrolling sometimes).
2. There're few relatively big .mod's which are used relatively rarely. It would be nice to leave just a couple of smaller ones in a core package, to really slim it down, and put the rest in extra-music package.
3. Fully clean up gp2x patch, it's still too dirty.

info reg, for a ducat, info reg!

Back in my childhood I was severely traumatized by debugging experience with Turbo Debugger 1.0. I mean, it was so nice, so perfect tool that I barely can use any other debugger with comfort since that. That's why I usually shrug on pushing different kind of "developer GUIs" - if it's good, it can be only worse on the large scale, as you won't be able to use more mediocre tools after that ;-).

GDB is one of the worst debugger UIs in this respect - debugging oftentimes requires thousands of repetitive simple actions, and if for step in/step over you need more then one keypress and need to press anything at all just to see the code/registers, it is a great chore. Nonetheless, having accepted that it's the baseline we have everywhere, and noone (including me) could write a decent frontend for it, I humbly condition me to use it, the same way as I did long ago for vi. And that's why I write - I still can't remember a command to dump registers. Maybe it's "show registers"? Or "dump registers"? Maybe "print registers" or - crazy - "data registers"? No, it's "info registers"! Whoa!

Smallscreen mod for GtkFileChooser

OpenEmbedded have had smallscreen patch for GtkFileSelection widget for quite some time now, but unfortunately it doesn't affect usability of the most software, simply because many programs now use GtkFileChooser widget instead. GTK+ 2.12 manual also following about the matter: "GtkFileSelection has been superseded by the newer GtkFileChooser family of widgets."

Let's look how standard GtkFileChooserDialog looks on QVGA portrait device (240x320):



Note that "Places" pane on left cannot be shrinked beyond the size shown, which doesn't leave room for any useful display of filenames, so the dialog is clearly unusable.

So, I've took time to patch GTK+ 2.10.14 (this is the version used by Angstrom 2007.12, and my primary focus is to improve its usability on the supported devices) to make the widget be more PDA-friendly. I started with "data-driven" changes (meaning changing numbers and strings, but note code constructs):

• Reduced Gnome Human Interface Guidelines mandated spacing and borders of 6 and 12 pixels to 2. It's nice to have standards (even though Gnome doesn't offer us opportunity to choose from ;-) ), but on small screens, there's simply not enough space to spend pixel-wealth on gaps.
• Removed labels from Places pane's buttons, leaving only icons.
• Made Places pane shrinkable.
  

Even these changes made big difference, but stopping there would be to leave the dialog in barely usable state, and I'm really hope for a Linux GUI environment which is comfortable to use.

So, adaptive relayout was required, based on "PDA" mode being active. I first started with defining PDA mode as being portrait screen orientation, but thinking further, the problem, at least for GtkFileChooser, can be defined as follows: there's just too little of horizontal space available, and there should be efforts applied to use it to show as much of user's filenames' length as possible. Based on this note, PDA mode was defined as having a screen width below some threshold. This threshold was set as absolute value, but is not really arbitrary, and tied to real-world available screen sizes. I found that standard dialog looks pretty well in VGA landscape orientation, but still leaves too little space for filenames
in portrait orientation. So, threshold was set to 490 (to account for fudge factor ;-) ).

Now, with the above note on horizontal space scarcity, and keeping in mind that screen area at all is scarce, for vertical space should be saved too, following dynamic layout changes are done to dialog when being in PDA mode (i.e. run on the screen <490 pixels width):

• Vertical split pane is used for Places vs Filelist
• Buttons are packed to the left instead of bottom of Places
• Actually, only "Add" button was left, as "Remove" action can be easily accessed from Places list context menu, and most importantly, intuitively can be expected there. ("Add to shortcuts" choice is available for context menu on Filelist items, but who'd look for it there, without knowing it is?). This allows for more visually pleasing layout when Places pane is minimized.
• Dialog itself is sized to take all available width (originally, GTK+ sizes it to take no more than 3/4 of screen width, if possible, or packed requested size otherwise).
  

All in all, that's how the dialog looks now:


A refreshing change, with pretty long filenames being easily visible.

I've tested the patch pretty well, plus code changes are pretty small, so I intend to commit it to OE soon, and RFC its addition to Angstrom stable branch after it gets more review and testing.

There're still few things to consider and do to make it even more usable on small, PDA-like screens:

• Catch and process screen geometry change events - I'm pretty sure this is not done by GTK+ currently, and on dynamic screen device like PDA could make parts of dialog go offscreen when switching from landscape to portrait and vice-versa.
• Possibly, adjust screen width threshold based on more testing (original value was based on review of big-gaps dialogs, maybe smaller gaps affect that).
• Alternatively, gaps can be calculated on the fly, so original Gnome HIG-mandated values would be used on big screens, and small values only in PDA mode.
• Default "File system" choice in Places is superflous, it can be accessed with the icon from the path buttons at the top of dialogs. Unfortunately, screenshots above have it scrolled away. And having "File system" is Places causes exactly same problem: it takes space and calls for scrolling, so we'd better skip it there altogether, letting user to access own choices easier.
• Think about dialog height. Currently, as seen from above screenshot, it leaves bunch of screen area unused, and (apparently) due to Matchbox window management constraints, it cannot be resized by user. We could fit 1-2 more filenames if sized the dialog near-fullscreen. But that would look OK for QVGA, but already artificial for VGA.
  

Finally, it would be fun to have a look at GTK+ 2.12. As they say, it has stuff contributed by Nokia based on N770/N800 work, so I keep my fingers crossed that I didn't do monkey's job! ;-) Nonetheless, the focus is current Angstrom release, as I wrote above.