Selecting a resolution policy

Choosing a resolution policy can be a sensitive topic, especially since we're dealing with a platform which currently runs on devices ranging from 3-inch displays up to 10.1-inch for the most part. Generally developers and users alike prefer that a game takes up the full width and height of the device's display, but in some cases our resolution policy may need to be carefully selected in order to properly display our scenes as we—the developer—see fit. In this recipe, we're going to discuss the various resolution policies included in AndEngine, which will help us decide which policy might best fit our application's needs.

How to do it…

The resolution policy that we choose to adhere to must be included as a parameter in the EngineOptions constructor which is created in the onCreateEngineOptions() method of AndEngine's life cycle. The following code creates our EngineOptions object using the FillResolutionPolicy class, which will be explained later in the chapter:

EngineOptions engineOptions = new EngineOptions(true,
    ScreenOrientation.LANDSCAPE_FIXED, new FillResolutionPolicy(),
    mCamera); 

We can select a different resolution policy by simply passing another variation of the resolution policy classes to this constructor.

How it works…

The following is an overview of AndEngine's BaseResolutionPolicy subtypes. These policies are used to specify how AndEngine will handle our application's display width and height based on various factors:

• FillResolutionPolicy: The FillResolutionPolicy class is the typical resolution policy if we simply want our application to take up the full width and height of the display. While this policy allows our application to run in true full screen mode, it may cause some noticeable stretching in order for our scene to take up the full available dimensions of the display. We can select this resolution policy by simply including new FillResolutionPolicy() as our resolution policy parameter in the EngineOptions constructor.

• FixedResolutionPolicy: The FixedResolutionPolicy class allows us to apply a fixed display size for our application, regardless of the size of the device's display or Camera object dimensions. This policy can be passed to EngineOptions via new FixedResolutionPolicy(pWidth, pHeight), where pWidth defines the final width that the application's view will cover, and pHeight defines the final height that the application's view will cover. For example, if we pass a width of 800 and a height of 480 to this policy-types constructor, on a tablet with a resolution of 1280 x 752, we'd be left with an empty black area since there will be no compensation between the resolution policy and the actual display size.

• RatioResolutionPolicy: The RatioResolutionPolicy class is the best choice for resolution policies if we need to obtain the maximum display size without causing any distortion of sprites. On the other hand, due to the wide range of Android devices spanning many display sizes, it is possible that some devices may see "black bars" either on the top and bottom, or left and right sides of the display. This resolution policy's constructor can be passed either a float value, which defines a preferred ratio value for the display dimensions, or a width and a height parameter from which a ratio value will be extracted by dividing the width by the height. For example, new RatioResolutionPolicy(1.6f) to define a ratio, or new RatioResolutionPolicy(mCameraWidth, mCameraHeight), assuming mCameraWidth and mCameraHeight are the defined Camera object dimensions.

• RelativeResolutionPolicy: This is the final resolution policy. This policy allows us to apply scaling, either larger or smaller, to the overall application view based on a scaling factor with 1f being the default value. We can apply general scaling to the view with the constructor—new RelativeResolutionPolicy(1.5f)—which will increase the scale of both the width and height by 1.5 times, or we can specify individual width and height scales, for example, new RelativeResolutionPolicy(1.5f, 0.5f). One thing to note with this policy is that we must be careful with the scaling factors, as scaling too large will cause an application to close without warning. Try to keep the scaling factor to less than 1.8f; otherwise make sure to do extensive testing on various devices.