Supporting the multiple screen sizes of multiple devices in Adobe AIR

Whether you're adapting a game that runs in Flash Player in the browser to run on iOS (using Adobe AIR) or writing an Adobe AIR application for Android tablets, you'll need to support at least a few different screen resolutions. My post-apocalyptic strategy game Rebuild (for more background, read the Rebuild postmortem) was designed to be played in the browser with Flash Player at 800 x 600 pixels, so it took a few tricks to adapt it to run on the plethora of mobile devices out there.

In this article, I share some of those tricks (based on Adobe AIR 3.2) and sample code for:

• Detecting screen size
• Forcing orientation
• Calculating physical dimensions
• Scaling and centering an interface
• Converting vectors to scaled bitmaps
• Detecting and limiting Apple iOS devices
• Limiting Android devices

There are four different ways to check dimensions.

The stage.width and stage.height properties indicate the width and height of the contents of the stage in pixels. If your SWF file is 500 x 500 pixels and contains a 100 x 100 pixel square, these properties will return 100 x 100.

You can use stage.stageWidth and stage.stageHeight to access the current width and height, in pixels, of the size of your SWF file in either Flash Player or Adobe AIR. In the above scenario, they would return 500 and 500 . They may be set incorrectly during the first few frames. In StageScaleMode.NO_SCALE , a resize event is triggered when these change.

The stage.fullScreenWidth and stage.fullScreenHeight properties return the width and height of the screen when going to full size, including space taken up by toolbars. These properties only change when width and height are swapped because of a change in orientation.

Lastly, the Capabilities.screenResolutionX and Capabilities.screenResolutionY properties return the maximum horizontal and vertical resolutions of the screen. In other words, they tell you the size of the device's entire screen. If your game is running in a window (for example, in a simulator on your computer), these properties will still return the size of the entire monitor.

Ideally, your application should check stage.stageWidth and stage.stageHeight , then listen for resize events (which includes changes in orientation). Depending on the device, these values may be completely wrong at first, and then after a few seconds you'll see several resize events as the application becomes fullscreen, toolbars disappear, and orientation corrects itself. Here's how to check resolution on the fly:

For my game Rebuild, I wanted to get the dimensions a single time as soon as the game started, so I could initialize the GUI only once. The Stage.fullScreenWidth and Stage.fullScreenHeight properties provide a better approximation in this case, although they don't include any system toolbars that appear above your application (for example, those found on the Kindle Fire). The orientation may also be wrong, but because my game forces landscape orientation, I can assume that the wider dimension is always width, like this:

In your application.xml file, you can set the default aspectRatio to either landscape or portrait . For iOS this also determines which splash screen graphic you need— Default-Landscape.jpg or Default-Portrait.jpg . If you want to support both modes, set autoOrients to true , in which case a resize event will fire any time the user tilts the device to change orientation. Your application may briefly start in the wrong orientation even when autoOrients is set to false .

I use the following setup to force landscape orientation:

I change aspectRatio to force portrait orientation:

For games like Rebuild it's generally accepted to stick to one aspect ratio rather than switch back and forth, however most applications usually support both aspect ratios.

Although a small phone and a large tablet could have the same number of pixels, they would have very different physical sizes. For example, when you touch an iPhone 4's retina 960 x 640 display, your finger covers four times more pixels than when you touch an iPad 1's 1024 x 768 screen. This is important to consider for legibility of fonts and icons, and particularly for the size of buttons.

Looking at the dots-per-inch (more properly called PPI or pixels-per-inch), you can estimate how big your interface should be to avoid fat-finger mistakes. Apple suggests the minimum size for buttons and interactive objects should be 44 x 44 pixels for a 163 dpi screen (for example, an iPhone 3GS).

Android uses the concept of density-independent pixels (dp), which is a normalized pixel unit for defining resolution compared to a 160 dpi screen. A device's dp is calculated as pixels * 160 / DPI. To determine the dpi, dp, and size in inches you can use the following code:

Unfortunately devices often report the wrong dpi (notably for iOS displays). Capabilities.screenDPI is actually a best guess based on other information, but it may also be wrong. For comparison, you can get the original dpi reported by the operating system as follows:

Rebuild's iOS build has two static interface layouts: one for iPad and another with larger text and buttons for iPhone and iPod Touch. You can use the current device's dpi and physical size to pick which layout to use.

Adobe AIR has several built-in scaling modes, but I found that SHOW_ALL and EXACT_FIT behave oddly on devices. To have full control of scaling on devices (especially useful when resizing bitmaps), I found it's best to use NO_SCALE and handle scaling yourself.

Rebuild for Android uses a 1024 x 600 GUI that gets scaled up or down accordingly, then centered horizontally at the top of the screen. It's done when the game first loads, like this:

The relative sizes and positions of objects inside the base stay the same regardless of scaling. For example, items in my scrolling inventory list are always spaced 50 pixels (px) apart. But you will need to adjust for scale any time you use MouseEvent.stageX , MouseEvent.stageY , or DisplayObject.localToGlobal .

The browser version of Rebuild uses vector objects for buildings, icons, buttons, and backgrounds. They look great when scaled and keep file sizes low, but that scaling can be too complex to render efficiently on devices. They also use filters that aren't supported in GPU rendering mode in Adobe AIR and have jagged edges when stage.quality is lowered to increase performance. My solution is to replace them with bitmaps created at the scale I calculated earlier. I do this once when the game first loads.

If you don't use vectors, you can also use the code below to scale down large bitmaps to the needed size so they look smoother and take up less memory. However, bitmaps that include text or icons may become illegible if scaled down too far. You may get better results by having two or more sets of pre-rendered bitmaps and selecting one of them based on screen dpi.

If you need two or more of the same Bitmap object, you should save and reuse a single BitmapData object because it takes very little memory to create a second Bitmap object from it. Remember to call Bitmap.bitmapData.dispose() when you're done with it, to immediately remove it from memory rather than waiting for it to be garbage collected.

The iPhone, iPad, and iPod touch report their names in Capabilities.os , so it's possible to detect exactly which one the game is running on and adjust accordingly. For example, Rebuild has fewer animations and smaller maps on the slower iPad 1 and iPhone 3GS. The following code shows how to detect the iOS device and adjust the game accordingly:

Although I've listed all Apple mobile devices above, you'll never need to support the first or second generation iPhone and iPod Touch, because they lack the necessary architecture (armv7) and graphical libraries (opengles-2) to run AIR 3.2 applications.

There are a few ways to further limit your application to only run on a subset of compatible iOS devices.

You can set your application to only target iPads, or only target iPhone/iPod Touch via UIDeviceFamily in application.xml; for example:

You can get more specific by setting UIRequiredDeviceCapabilities in the same application.xml. For example requiring a still-camera means the device must have a camera. Requiring a gyroscope conveniently limits your application to the newer iPhone 4+, iPod Touch 4+, and iPad 2+. Wikipedia has a definitive list of iOS devices and their features.

To enable double-density displays in iPhone 4S+ (iPad 3 retina support isn't yet available in AIR 3.2), set requestedDisplayResolution to high . This changes the reported screen resolution in iPhones from 480 x 320 (163 dpi) to 960 x 640 (326 dpi). Make sure your application scales down appropriately for the iPhone 3GS and iPod Touch 3gen, which don't support retina display.

There are nearly 1000 different Android devices. They don't report their names via Capabilities.os , and there is no way to determine the CPU capabilities or RAM of the device. However, you can target specific Android devices (for example just tablets) in Google Play and other Android app stores by requiring a certain screen size and density in application.xml.

The screenSize attribute refers to how many inches wide the shorter size is:

• small (approximately 2 to 3 inches)
• normal (approximately 3 to 5 inches)
• large (approximately 5 to 7 inches)
• xlarge (approximately 7 inches or more)

The screenDensity attribute reflects the calculated pixels per inch:

• ldpi (from 100 to 120 dpi)
• mdpi (from 120 to 180 dpi)
• tvdpi (approximately 213 dpi)
• hdpi (from 180 to 260 dpi)
• xhdpi (more than 260 dpi)

The following excerpt from application.xml indicates that Rebuild does not support small or low-density screens:

As of early 2012, the most popular Android devices are the Samsung Galaxy phone series (800 x 480), the Motorola Droids (960 x 540), the HTC Evo and Desire (800 x 480), the Samsung Galaxy Tab (1280 x 800), and the Kindle Fire (1024 x 600). However, every country has different popular models and no Android device has a definitive lead on the others, so targeting specific devices is not recommended.

I tested locally using a Nexus One (800x480 released in Jan 2010) which was the low-end of phones I wanted to support, and a Kindle Fire which is an average tablet. As frustrating as slow devices may be, it's better to develop using older hardware so you get a good idea of your minimum performance. Services like TestDroid can help you test remotely on a wider range of devices.

I put off porting Rebuild to Android for months because I was afraid of handling so many devices, but in the end it was pretty simple to get the scaling in place and only took a few days to get going. I also ported to the BlackBerry PlayBook, which turned out to be well worth the relatively little effort it required.

Adobe AIR makes it easy to run the same code on a thousand different mobile devices. Adobe's done most of the hard work, so if you're planning to target one device, you might as well support all of them in all their different shapes and sizes.