How to use Canvas graphics scaling
Starting from S60 3rd Ed. devices there has been platform support for automatic Canvas graphics scaling. It is usable for two use cases:
- Automatically scale Java 2D graphics content designed for specific resolution to the device resolution
- Improve performance of performance hungry Java content with smaller effective resolution but scaling it to full display resolution.
The scaling is effective only in full screen mode Canvas. Normal mode Canvas and other displayables (high-level components like List, Alert & Form) won't be affected.
Via this mechanism old non-scalable 2D content can be easily made available to new display resolutions. For example, having old 178x208 resolution designed games to work properly in Double resolution devices like E70 is just one line addition to the JAD or JAR manifest of the application:
Specifying the above line, any S60 3rd Edition will assume that the application was designed for 176 x 208 resolution and then depending on actual device resolution scale the content accordingly. The scaling won't distort image aspect ratio. If the device display resolution aspect ratio is different to the resolution defined in Nokia-MIDlet-Original-Display-Size the content is scaled to fit the display and then centering the content. Black color is used to fill the areas of the Canvas that don't show the content.
For Java application all the values returned from the Canvas indicate as if the display resolution would be the resolution stated in the attribute.
There's also another attribute available called Nokia-MIDlet-Target-Display-Size. That can be used together with the Original Size attribute. There's less uses for it and the most common case would be to only use Original Size attribute. With Target Display Size attribute application for certain scaled resolution. Application may even force distortion of aspect ratio. The use case for this attribute is to slightly scale content bigger than the actual screen resolution. This may be useful e.g. scaling 128x160 resolution content to QVGA devices.
It should be noted that down scaling is not currently implemented. If down scaling would happen the attribute is completely ignored and no scaling happens in full screen Canvas.
In 3rd edition FP 2 devices there's a third attribute Nokia-MIDlet-Canvas-Scaling-Orientation-Switch. This is used together with Nokia-MIDlet-Original-Display-Size if the application in question supports a single resolution but is able to do that in both in portrait and landscape orientations.