Using Multi-Resolution Bitmaps

From RAD Studio
Jump to: navigation, search

Go Up to FireMonkey Applications Guide

FireMonkey is a multi-platform framework (Windows, iOS, Mac OS X, and Android), and therefore FireMonkey applications work on devices having different screen densities and resolutions. Using FireMonkey multi-resolution bitmaps means that your images and icons in FireMonkey applications will appear correctly in different densities and resolutions (Windows, iOS, Mac OS X, and Android). A multi-resolution bitmap is a collection of bitmap items providing the same image but having different scales.

Here we use the following terms:

  • Screen density: The quantity of pixels within a physical area of the screen; usually referred to as dpi (dots per inch). For example, a "low" density screen has fewer pixels within a given physical area, compared to a "normal" or "high" density screen.
  • Screen resolution: The total number of physical pixels on a screen. Screen density and screen resolution are measured in physical units - pixels.
  • Scale: FireMonkey always uses logical coordinates and logical sizes. Working with multi-resolution bitmaps, FireMonkey estimates relations between logical units and physical units using the Scale property.

Let us discuss the Scale property. For example, Apple uses the Retina display (2880×1800 pixels), which doubles the density and resolution of non-Retina displays. As a result, to submit your application to the Mac App Store, the icon set file must include an icon with a resolution of 512×512 pixels, for non-Retina displays. Let us say that we use the Scale = 1 for this icon. For Retina displays, you should add an icon with a resolution of 1024×1024 pixels. If both these icons have the same logical size in FireMonkey, then for the 1024×1024 icon FireMonkey should use the Scale = 2. So we use different Scales to provide different numbers of physical pixels to images having the same logical sizes in FireMonkey tools.

For the Mac OS X and iOS platforms, it is reasonable to provide at least two scales: 1 and 2. Since a screen resolution is the hardware property of particular screens, platforms having a rich set of different type devices with different resolutions can require a more extended set of scales. For example, the Android platform can require scales 1, 1.33, 1.5, 2, and others.

The base class for multi-resolution bitmaps is TCustomMultiResBitmap. TCustomBitmapItem is the base class for bitmap items in TCustomMultiResBitmap collections. You can use TCustomMultiResBitmap multi-resolution bitmaps to show images in TImage controls.

TImage controls can handle a TFixedMultiResBitmap multi-resolution bitmap in the MultiResBitmap property. TFixedMultiResBitmap is the descendant of TCustomMultiResBitmap. A TFixedMultiResBitmap multi-resolution bitmap can contain any number of bitmap items having different scales. On each device, TImage retrieves the most appropriate bitmap to display from the bitmap collection in the TFixedMultiResBitmap multi-resolution bitmap and refers to the obtained bitmap with the Bitmap property. The obtained bitmap depends on the device resolution and scales of bitmap items kept in the TFixedMultiResBitmap multi-resolution bitmap. If a multi-resolution bitmap does not contain a bitmap item having exactly the scale required by some particular screen, then FireMonkey automatically stretches or zooms out the bitmap item having the most appropriate scale. For information about how this bitmap is obtained, see Bitmap. Keep in mind that each bitmap item takes resources of the application's executable on all platforms (even if some bitmap item is never used on a particular platform).

Use the MultiResBitmap Editor to create the TFixedMultiResBitmap multi-resolution bitmaps for TImage controls.

Bitmap items in TFixedMultiResBitmap multi-resolution bitmaps have the TFixedBitmapItem type. TFixedBitmapItem bitmap items have the Fixed property. Bitmap items with Fixed = True are mandatory items. By default, each multi-resolution bitmap contains at least one mandatory (default) bitmap item having the Scale = 1 and the name Normal. In the MultiResBitmap Editor you cannot delete mandatory bitmap items or change the Scale of mandatory bitmap items. You can extend the list of mandatory bitmap items (and scales) using the global RegisterScaleName method.

See Also