Learn what Felgo offers to help your business succeed. Start your free evaluation today! Felgo for Your Business


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

Import Statement: import Felgo 4.0


Inherited By:



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.

Note: If you only create an sd image version and no hd and hd2 versions, the sd version is used also on hd and hd2 screens. It will look blurry though, but this may be useful in quickly testing different images during development and prototyping. To reduce app size, you can decide to not provide hd2 image versions, or only provide hd2 detail of some images. The hd image will not be crisp on hd2 devices, but is still a good compromise between image quality and app size. This allows you to decide based on your requirements if app size or image quality is more important on a per-image basis.

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.

Note: During development and quick testing, start with placeholder graphics and use a normal Image element. Or a MutliResolutionImage and call vplayApplication.setContentScaleAndFileSelectors(1); in your main.cpp file to only need to provide a single image instead of three versions with three different sizes.

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

asynchronous : alias

cache : alias

fillMode : alias

horizontalAlignment : alias

mirrorX : alias

This property holds whether the image should be horizontally mirrored.

The default value is false.

mirrorY : bool

This property holds whether the image should be vertically mirrored.

Note: Mirroring on the verical axis is internally achieved by setting the Item::transform property. Thus if you set the transform property explicitly, you need to apply the y-scaling manually.

The default value is false.

paintedHeight : alias

paintedWidth : alias

progress : alias

smooth : alias

source : alias

The source of the MultiResolution image. Based on the content scale, an image in the +hd or +hd2 subfolders might be used.

sourceSize : alias

status : alias

verticalAlignment : alias

Qt_Technology_Partner_RGB_475 Qt_Service_Partner_RGB_475_padded