Display

When starting an AGK project one of the first choices to make relates to the positioning of your sprites and other entities. You can either choose to go with a virtual resolution or a percentage based system. Each method has its advantages and disadvantages, and which route you choose is purely down to personal preference.

What is a virtual resolution?

A virtual resolution provides you with an option to specify a fixed resolution e.g. 320 x 480. Once this resolution has been set 0, 0 becomes the top left corner of the screen, while 320, 480 becomes the bottom right corner. When setting a virtual resolution, the base resolution is then scaled up or down dependant on the platform.

If you had artwork designed for a 320 x 480 resolution you might find it very convenient to set a virtual resolution to match this, then within your code it's a case of matching sprite positions to those provided by the artist.

Virtual resolutions are not tied into the device resolution, so in some cases your application may have black borders applied when it's not possible to scale without affecting proportion.

Some advantages of using a virtual resolution include:

• Traditional approach - many developers are already used to dealing with screen coordinates
• Easy to understand and use
• Quick to set up

Disadvantages include:

• Locked into a specific aspect ratio. Imagine in the future if your original 320 x 480 size were redone at 768 x 1024. In this instance you would have to adjust code to deal with updated positions, sizes, etc.

What is the percentage based system?

The percentage based system provides an alternative approach to dealing with positioning sprites. With this approach, instead of specifying your coordinates in pixels, you deal with percentages, therefore 0, 0 is the top left corner of the screen, while 100, 100 becomes the bottom right corner.

In this instance positioning a sprite at 50, 50 will place it in the centre of the screen.

In reality the percentage system is just a virtual resolution of 100 x 100 with a distorted aspect ratio, you choose which aspect ratio with the SetDisplayAspect command. For example 320 x 480 is an aspect ratio of 0.66 so using this value would stretch the 100x100 square into a rectangle that would be full screen on a 320 x 480 device. AGK will automatically scale up the app on devices that support higher resolutions using black borders where necessary to maintain your desired aspect ratio.

One disadvantage of this is that creating a sprite of size 10 x 10 would not produce a square as expected, since the 100 units in the X direction cover less space than the 100 units in the Y direction. To combat this AGK allows you to specify a size of -1 for one axis to mean don't stretch the sprite, using a square image on a sprite with size 10 x -1 would make sure it appears square on screen by choosing an appropriate Y size.

Some advantages of using a percentage based system include:

• More flexibility for the future. If you decide you want to work in a different aspect ratio you only need to change SetDisplayAspect

Disadvantages include:

• Slightly harder to use initially. It is somewhat different from the typical approach of placing sprites using screen coordinates,
• More work involved in the initial set up. You always need to specify the size of sprites, for example, a sprite may have dimensions of 10% by 15%.

Which method should I choose?

It's probably easier and quicker to use a virtual resolution, however, using the percentage based system is more future proof and flexible, but at the drawback of being slightly more complicated and needing more code initially. The important point here is that it's advisable to make this decision at the start of your development in order to avoid complications later by swapping halfway through.

How do I specify a virtual resolution?

To specify a virtual resolution you need to call the command SetVirtualResolution and pass in the width and height e.g.

SetVirtualResolution ( 1024, 768 )

agk::SetVirtualResolution ( 1024, 768 );

A game that runs on a device supporting this resolution will fill the screen completely. In cases where the resolution is different the game will show black borders.

It's advisable to call this line at the beginning of your program code.

How do I use the percentage system?

In order to use the pecentage based system you will need to specify an aspect ratio, which is responsible for controlling the way your graphics will scale. Which aspect ratio is used will be dependent on your base starting point, for example, if your graphics are designed for a screen with a resolution of 320 * 480 then your aspect ratio will be 320 / 480 which is roughly 0.66 e.g.

SetDisplayAspect ( 320.0/480.0 )

agk::SetDisplayAspect ( 320.0f/480.0f );

A game that runs on a device supporting this aspect ratio will fill the screen completely. In cases where the aspect ratio is different the game will have black borders.

The percentage system is more flexible than using a virtual resolution. Here's an example scenario: a game is developed with graphics set up for an aspect ratio of 1024 / 768 (1.33). Some time later a new device comes along that has a resolution of 1280 x 800. This device's aspect ratio is also 1.6. In this instance your app will work but it will have black borders to fill in the extra space around your 1024 x 768 app. Using the virtual resolution system would require redoing all the positions and sizes of all sprites, whereas the percentage system is more flexible and an aspect ratio change will automatically move sprites closer together to compensate.

Specifying orientations

An AGK game will automatically rotate to the current orientation of the device. On platforms like Windows and Mac the orientation is unlikely to change, but on mobile platforms it's possible that different landscape and portrait orientations are available. By default AGK will automatically update for all orientations. To control this use the command SetOrientationAllowed, it takes four parameters - portrait, portrait2, landscape and landscape2 controlling the default device orientation, the upside down portrait orientation, the landscape orienation when the device is rotated left from its default position and finally the landscape orientation when the device is rotated right from its default position. This command allows you to specify which orientations are supported, for example, an iPad game designed for 1024 x 768 may only support landscape modes and this would be handled with:

SetOrientationAllowed ( 0, 0, 1, 1 )

agk::SetOrientationAllowed ( 0, 0, 1, 1 );

To support only portrait:

SetOrientationAllowed ( 1, 1, 0, 0 )

agk::SetOrientationAllowed ( 1, 1, 0, 0 );