Package	feathers.utils
Class	public class ScreenDensityScaleFactorManager
Inheritance	ScreenDensityScaleFactorManager Object

When using ScreenDensityScaleFactorManager, the Starling stage dimensions will not be exactly the same on all devices. When comparing two different phones, the stage dimensions will be similar, but may not be perfectly equal. For example, the stage dimensions on an Apple iPhone 5 in portrait orientation will be 320x568, but the stage dimensions on a Google Nexus 5 will be 360x640. With this in mind, be sure to use "fluid" layouts to account for the differences.

It's also important to understand that tablets will have much larger Starling stage dimensions than phones. ScreenDensityScaleFactorManager is designed to behave more like native apps where tablets often display extra navigation or data that wouldn't be able to fit on a smaller phone screen. For example, on an Apple iPad, the stage dimensions will be 768x1024. This is much larger than the two phones we compared previously.

The following example demonstrates how to instantiate ScreenDensityScaleFactorManager:

this._starling = new Starling( RootClass, this.stage, null, null, Context3DRenderMode.AUTO, Context3DProfile.BASELINE );
this._scaler = new ScreenDensityScaleFactorManager(this._starling);

The device's screen density (sometimes referred to as DPI or PPI) is used to calculate an appropriate contentScaleFactor value. The calculation is inspired by native apps on Google's Android operating system where "density-independent pixels" are used for layout. You might consider this an advanced form of the techniques described in Starling Multi-Resolution Development.

The following chart shows how different screen densities map to different contentScaleFactor values on both iOS and Android:

The density values in the table above are approximate. The screen density of an iPhone 5 is 326, so it uses the scale factor from the "xhdpi" bucket because 326 is closer to 320 than it is to 480.

Note: Special behavior has been implemented for iPads to give them scale factors of 1 and 2, just like native apps. Using Android's rules for DPI buckets, non-Retina iPads would have been "ldpi" devices (scale factor 0.75) and Retina iPads would have been "hdpi" devices (scale factor 1.5). However, because it makes more sense for Starling to use the same scale factor as native apps on iPad, this class makes a special exception just for them.

After creating ScreenDensityScaleFactorManager, you can use Starling's contentScaleFactor property to determine which set of assets to load:

if( Starling.current.contentScaleFactor > 1 )
{
    assetManager.scaleFactor = 2;
    var assets2x:File = File.applicationDirectory.resolvePath( "assets/2x" );
    assetManager.enqueue( assets2x );
}
else
{
    assetManager.scaleFactor = 1;
    var assets1x:File = File.applicationDirectory.resolvePath( "assets/1x" );
    assetManager.enqueue( assets1x );
}

Providing assets for every scale factor is optional because Starling will automatically resize any textures that have been given a different scale than the current contentScaleFactor when they are rendered to the screen.

For example, since "ldpi" devices with a low screen density typically aren't manufactured anymore, it might not be worth spending time designing a set of assets specifically for scale factor 0.75. Instead, you can probably load the higher quality "mdpi" textures when a legacy device is encountered where ScreenDensityScaleFactorManager chooses a contentScaleFactor of 0.75. As long as the "mdpi" textures are given a scale of 1 when they are created, Starling will know how to automatically resize them on a device where the calculated contentScaleFactor is lower than 1. Larger textures will be automatically scaled down, and the app will look the same as it would if you were using lower resolution textures. Your app will end up using a bit more memory at runtime than strictly necessary on these devices, but you won't need to include as many image files with your app, so its download size will be smaller.

Similarly, lower resolution textures can be scaled up on devices with a higher contentScaleFactor. It is said that the human eye starts to have difficulty perceiving every individual pixel when a device's screen density is higher than 300 DPI. Depending on your app's requirements, assets for scale factor 4 (and often, also scale factor 3) may not be strictly necessary. You can often load assets for scale factor 2 on these higher-density devices because the difference is so difficult to see with the naked eye.

See also