This document discusses how to make Eclipse applications compatible with high-DPI or HiDPI displays. It covers autoscaling images and layouts, using high-resolution images, new image constructors that provide images at different zoom levels, and HiDPI-aware APIs. While SWT now handles scaling internally, developers need to provide high-res images and ensure images are retrieved at the correct zoom level. Dynamic resolution switching and scaling issues on Mac are also discussed.

1. HOW TO MAKE YOUR ECLIPSE
APPLICATION HI-DPI READY!
Lakshmi P Shanmugam
Eclipse Platform Committer & Co-lead
IBM India

2. AGENDA
• Introduction to HiDPI
• Autoscaling
• Steps to make the application Hi-DPI ready
• Using high resolution images
• Using new Image constructors
• Using HiDPI APIs
• Missing pieces

3. WHAT IS HI-DPI?
• DPI - Dots Per Inch / PPI - Pixels Per Inch
• Measure of pixel density
• Default DPI - Windows & Linux-GTK - 96, Mac - 72
• HiDPI Display - Display with higher pixel density

4. HAVE HIGH PIXEL DENSITY
HI-DPI DISPLAYS

5. INCREASES LEGIBILITY/CLARITY/SHARPNESS OF UI ELEMENTS
WHY HI-DPI DISPLAYS?

6. EXISTING CODE AND APPLICATIONS ARE NOT DPI AWARE.
CURRENT PROBLEM
• Increasing DPI makes UI elements appear smaller on Windows &
Linux/GTK
100% zoom 200% zoom

7. on Hi-DPI monitoron non-Hi-DPI monitor

8. • On Mac, increasing DPI scales the UI elements and make them
appear blur

9. on non-Retina on Retina

10. DPI AWARE APPLICATION
WHAT IS A HI-DPI READY APPLICATION?
• UI is resolution independent
• UI elements appear the same size and are sharp on both standard and
high resolution
• Hi-DPI support provided by SWT is platform independent
• SWT APIs now use point geometry - Display, Graphics API, events use
points - clients need to work only with points and don't have to deal
with pixels
• SWT internally uses pixels for OS calls

11. LEVERAGE THE SUPPORT PROVIDED BY ECLIPSE
HOW TO MAKE THE APPLICATION HI-DPI
READY?

12. AUTOMATIC SCALING OF IMAGES & LAYOUT
AUTOSCALING
• Required when high resolution images are not available
• Mac provides native autoscaling of Images on Retina displays
• Text is scaled automatically by the OS on all platforms
• SWT provides automatic scaling of Images & layout on Windows &
Linux based on the OS zoom factor
• Available in Eclipse since Neon (4.6)

13. AUTOSCALING IN ACTION

14. TWEAKING SWT’S AUTOSCALING
• On Windows and GTK, SWT's auto-scaling can be configured using
the swt.autoScale Java property.
• swt.autoscale options: default is integer200
• false: scale factor is set to 100% (no scaling)
• integer200: scale factor depends on the current display
resolution, but only uses integer multiples of 100%. The detected
native zoom is generally rounded down (e.g. at 150%, will use
100%), unless close to the next integer multiple (currently at
175%, will use 200%). Maximal zoom level is 200%.
• experimental options - integer, quarter, exact, <value>

15. USE HI-RESOLUTION IMAGES
STEP 1:

16. USING HIGH RESOLUTION IMAGES IN YOUR
APPLICATION
• Out of the box support for icon images created using
org.eclipse.jface.resource.ImageDescriptor.createFromURL(URL)
• Append "@2x" to the file name and place into the same folder as
the original icon
• For OSGi bundles, you can also put the icons into a fragment that
contains the same folder structure

17. 2x images in org.eclipse.jface
plugin
Example code

18. GENERATING HIGH RESOLUTION ICONS
• Create an SVG Image (Scalable Vector Graphics (SVG) is an XML-
based vector image format)
• Generate 1x and 2x png images
• eclipse.platform.images repo
• org.eclipse.images has platform images - svg, 1x, 2x png, gif
• org.eclipse.images.renderer has the generator
• Generator can be used to generate png images of different sizes
from SVG images

19. CREATE HI-DPI AWARE IMAGES
STEP 2:

20. USING NEW IMAGE CONSTRUCTORS
CREATE DPI AWARE IMAGES
• SWT provides two new Image constructors that accept image-
provider callbacks that allow clients to supply resolution-
dependent versions of images
• Depending on the user's monitor configuration, SWT will request
images with the corresponding zoom level.
• Available since Eclipse Mars (4.5)

21. REPLACE WITH NEW IMAGE CONSTRUCTOR FOR IMAGE DATA
• ImageDataProvider provides a callback mechanism to get
ImageData at the required zoom level to be rendered.
• ImageDataProvider.getImageData() will be called by SWT during
the image rendering. Returns the ImageData for the given zoom
level.

22. Example Code for ImageDataProvider

23. REPLACE WITH NEW IMAGE CONSTRUCTOR FOR FILE NAME
• ImageFileNameProvider provides a callback mechanism to get
image file path for the required zoom level.
• ImageFileNameProvider.getImagePath() will be called by SWT
during the image rendering. Returns the image filePath for the
given zoom level.

24. Example Code for ImageFileNameProvider

25. USE HI-DPI AWARE APIS TO
WORK WITH IMAGES
STEP 3:

26. GETTING THE IMAGE DATA
It is deprecated as it doesn’t make sense in an environment having
multiple monitors with different DPIs
• It returns an ImageData for the given zoom level
• It is mainly intended to be used by custom implementations of
ImageDataProvider that draw a composite image at the requested
zoom level based on other images.
It returns the ImageData at 100% zoom level

27. CODE TO DRAW ARROW IN BREADCRUMB VIEW
Replace Image.getImageData() with Image.getImageData(zoom)

28. USING ImageDescriptor
• ImageDescriptor and CompositeImageDescriptor classes in
org.eclipse.jface.resource are fully ready for HiDPI images.
• An ImageDescriptor is an object that knows how to create an
SWT image.
• Using ImageDescriptor abstract class involves defining a concrete
subclass and re-implementing the getImageData(int) method.
• Legacy subclasses that are not HiDPI-aware used to override the
deprecated getImageData() method.
• Subclasses must re-implement exactly one of the getImageData
methods and they should not re-implement both.

29. CREATES HI-DPI AWARE IMAGES
Using ImageDescriptor Class
subclasses must
implement
deprecated

30. USING CompositeImageDescriptor
• An Abstract base class for ImageDescriptor that synthesize
an image from other images in order to simulate the effect of
custom drawing.
• Subclasses must implement getSize() and
drawCompositeImage(int, int).
• Subclasses of CompositeImageDescriptor will have to update
their implementation of drawCompositeImage(int, int) to
use the new drawImage(ImageDataProvider, int, int)
method to draw the elements of the composite image.

31. CREATES HI-DPI AWARE COMPOSITE IMAGES
Using CompositeImageDescriptor Class
subclasses must
implement
deprecated
use

32. protected void drawCompositeImage(int width, int height) {
// draw overlay in top-right corner:
ImageData imageData = myImageDescriptor.getImageData();
drawImage(imageData, width - imageData.width, 0);
}
protected void drawCompositeImage(int width, int height) {
// draw overlay in top-right corner:
CachedImageDataProvider provider =
createCachedImageDataProvider(myImageDescriptor);
drawImage(provider, width - provider.getWidth(), 0);
}
Old Code:
New Code:

33. DecorationOverlayIcon
• A DecorationOverlayIcon is an ImageDescriptor that can be used
to overlay decoration images on to the 4 corner quadrants of a
base image.
• Clients that use DecorationOverlayIcon will get HiDPI support for
free.

34. MISSING PIECES!!

35. DYNAMIC RESOLUTION SWITCHING
• Moving the application from one monitor to another of different
DPI
• Works well on Mac due to native support
• Not supported by Eclipse on Windows & GTK
• Windows 7 & GTK - support same DPI on all monitors
• Windows 10 & Wayland - support different DPI on connected
monitors.

36. SCALING PROBLEM OF IMAGES DRAWN USING
GC ON MAC

37. PROPOSED APIs
• API to getDPI for each display/Monitor
• API to support DPI aware Image drawing in GC

38. DEMO

40. THANK YOU!

41. swt.autoscale arguments:
• false: scale factor is set to 100% (no scaling)
• integer: scale factor depends on the current display resolution, but only uses
integer multiples of 100%. The detected native zoom is generally rounded
down (e.g. at 150%, will use 100%), unless close to the next integer multiple
(currently at 175%, will use 200%).
• quarter: scale factor depends on the current display resolution, but only uses
integer multiples of 25%. The detected native zoom is rounded to the closest
permissible value. (This used to be the default in the last two pre-release
milestones.)
• exact: scale factor is set to the native zoom (with 1% as minimal step)
• <value>: scale factor uses the given integer value in percent as zoom level
default: integer

42. nearest
smooth
• The scaling method can be configured by setting the
swt.autoScale.method system property to:
• Default: nearest, except on GTK when the deviceZoom is not an integer
multiple of 100%.
• The smooth strategy currently doesn't work on Windows and Mac OS X.
nearest: nearest-
neighbor interpolation,
may look jagged
smooth: smooth edges,
may look blurry