• Home
• Felgo
• MultiResolutionImage

MultiResolutionImage

The MultiResolutionImage changes the used image based on the display size to improve performance and memory usage. More...

• List of all members, including inherited members

Properties

• asynchronous : alias
• cache : alias
• fillMode : alias
• horizontalAlignment : alias
• mirrorX : alias
• mirrorY : bool
• paintedHeight : alias
• paintedWidth : alias
• progress : alias
• smooth : alias
• source : alias
• sourceSize : alias
• status : alias
• verticalAlignment : alias

Detailed Description

A MultiResolutionImage changes automatically with different screen sizes: This concept is called dynamic image switching.

Dynamic Image Switching

Felgo adds support for dynamic image switching based on the screen size, on top of Qt 5. This allows you to:

• Save graphics memory: based on the screen size, the best matching image is selected to avoid upscaled and blurry images, and to save memory compared to an approach where always the highest resolution images are used.
• Improve loading times: as the best-sized image is selected, you get an ideal loading time of the used image.
• Work with the logical size of the image in your GameWindow and Scene to use Content Scaling.

This concept is used by iOS and Android too, with the disadvantage the respective approaches are not cross-platform. For example, on iOS you provide multiple images with increased resolution with an added file prefix like @2x or @4x. Android uses a folder approach, where resources can be moved into the best-matching folder like hdpi or xhdpi.

Felgo adds cross-platform support based on Qt 5 File Selectors, which is similar to the Android folder approach but with the added benefit that it works across all platforms.

Felgo File Selectors

To take advantage of dynamic image switching in Felgo, create 3 versions of your images:

• One original sized version of your image, the default version, based on a Scene size of 480x320. E.g. your button could be 100x50 px.
• One double-sized version of your image, the hd version, based on a Scene size of 960x640. E.g. your button would then be 200x100 px.
• One quadruple-sized version of your image, the hd2 version, based on a Scene size of 1920x1080. E.g. your button would then be 400x200 px.

Then move the hd image version to a +hd subfolder and your hd2 version to a +hd2 subfolder. Felgo will then use the best image version automatically.

Felgo Script for Multi-Resolution Asset Generation

To save your time of manually downscaling hd2 resolution images, we have prepared a shell script doing that for you automatically.

The script has two use cases:

1. Create a scaled version of an input image which is scaled by a factor of 0.5 (i.e. half the size) and 0.25 (i.e. a quarter of the original image). The resulting images, for example named output.png are stored in +hd2/output.png, +hd/output.png and output.png ready to be used with MultiResolutionImage or any of the Felgo Multiresolution Sprite Components GameAnimatedSprite or GameSpriteSequence.
2. Create a sprite sheet from single images, needed for GameAnimatedSprite and GameSpriteSequence components.

Download the Felgo Sprite Script here.

The zip archive contains shell script for Windows, Mac and Linux and requires the ImageMagick command-line tools to be installed.

You can then create a sprite sheet from your sprite frames starting for example with "bird_" with the following command:

 vplayspritecreator "bird_*.png" birdSprite 2048

By default the script creates downscaled +hd an +sd versions of the birdSprite in the correct folder structure. You can avoid this auto-scaling by adding the -noscale parameter:

 vplayspritecreator "bird_*.png" birdSprite 2048 -noscale

Testing File Selectors

To simulate different file selectors call vplayApplication.setContentScaleAndFileSelectors(x); in your main.cpp file, with x being the content scale factor you want to test. The +hd file selector is used at a scale >= 2, and the +hd2 is used at a scale >= 2.8.

MultiResolutionImage Example

Suppose you have an image of a button, which should have the size 100x50 px on a screen with 480x320 pixels (this is called sd, single-definition, in Felgo). When you are running your app on a hd screen like the iPhone 4, your normal Image element would be scaled up twice the size and will look blurry. To avoid that, you can create an image that is 200x100 px and thus exactly matches the display size. Now save the low resolution image as button.png and the hd image as button.png in a +hd subfolder. The same applies for a full-hd, or hd2 image with the size of 400x200, and save it as button.png in a +hd2 subfolder.

We recommend to create your images in a high resolution initially. Thus you do not loose quality when scaling it up, but instead can just scale them down in your preferred imaging program like Adobe Photoshop or Gimp. For crisp images on all currently available devices, including iPad Retina devices for example, use the hd2 scene size of 1920x1080 as a reference. And 2280x1440 for your background image. See the guide How to create mobile games for different screen sizes and resolutions for more information about this topic.

With the MultiResolutionImage, you can now access these 3 images with a single element:

 import Felgo

 GameWindow {

   Scene {

     MultiResolutionImage {
       // position based on the logical scene size
       x: 30
       y: 10

       // the logical size (i.e. this width & height) will always be 100 x 50
       // you can also set it explicitly to a logical size which then scales the button
       // based on the used contentScaleFactor, one of these files will be used:
       // button.png, +hd/button.png or +hd2/button.png
       source: Qt.resolvedUrl("button.png")
     }
   }
 }

You can position the image based on your logical scene size, and the correctly sized image is automatically loaded.

Property Documentation