Interface IIcon
How to create your own icon implementation
Implement IIcon
Implementations of this class typically contain a description of what the Icon should look like. For example: a path to a file, or a shape, color and size. The createPainter
method then makes it possible for the rendering backend to actually convert the icon to an Image
.
The main method to implement is the createPainter
method. This method is typically called once by the rendering backend. It should return an IIconPainter
implementation that is capable of rasterizing the icon, i.e. creating an Image
.
Other methods to implement are the IIcon#getHash
method and the == operator.
There are a few considerations for an implementation that are important:
IIcon
implementations must be immutable. The LuciadCPillar rendering engine makes this assumption, and produces unpredictable results whenIIcon
implementations change at runtime. When you want to modify the icon that is used to render a feature, you must create a newIIcon
instance with a different description.IIcon
implementations must correctly implement the IIcon's hash and equality. These allow the rendering engine to perform better optimizations, and to avoid unneeded CPU-intensive work.- Because
IIcon
implementations are immutable, it implies that theIIcon#getHash
method must always return the same value, and the == operator must always return the same result.
Implement IIconPainter
The main responsibility of the IIconPainter
is to convert an icon into an Image
. The IIconPainter
documentation provides a few performance considerations.
An other consideration is support for different display scales (HiDPI)
HiDPI
The createPainter
method allows you to generate multiple versions of the same icon, each scaled differently but representing the same content. Each version of the icon is a version that is optimized for a certain display scale. This is particularly useful when an icon is painted on a screen with a high DPI
, and also a display scale
> 1.0. If that is the case, this interface allows the Map
's renderer to choose which icon to paint at a particular display scale. This results in higher quality rendering of icons on a high DPI screen.
Implementations of the createPainter
can choose which icon to return. For example:
- the BasicIcon implementation in the samples can generate an
icon painter
for any possible display scale. - an icon that uses a path to a file on disk can search for additional files with a higher resolution (if available).
When an implementation doesn't have an icon available for a given display scale, it can choose which version of the icon to return. For example, when the IIcon#createPainter
method is called with a display scale of 1.75, but the implementation only has a non-scaled version or a double-sized icon available, it can choose which one to return. In this case that would preferable be the icon version with a display scale of 2.
The returned IIconPainter
must contain the display scale that was eventually chosen:
- It can choose to return the unscaled icon, so
IIconPainter#getDisplayScale
must return a value of 1.0. - It can choose to return the 2x larger icon, so
IIconPainter#getDisplayScale
must return a value of 2.0.
Related article: Support high-resolution (HiDPI) displays
Threading
This class and the IIconPainter
class can be used on any thread, so their implementations must be thread-safe.
Example implementation
The samples contain a sample icon implementation: BasicIcon. This code demonstrates how you could implement your own IIcon
and IIconPainter
.
-
Method Summary
Modifier and TypeMethodDescriptioncreatePainter
(IconPainterContext context) Creates anIIconPainter
for a given context.boolean
int
hashCode()
Returns the hash value for the current icon.
-
Method Details
-
createPainter
Creates anIIconPainter
for a given context.- Parameters:
context
- the painting context.- Returns:
- an icon painter for the current painter context, cannot be
null
.
-
hashCode
int hashCode()Returns the hash value for the current icon.This helps the rendering framework to identify if two different
IIcon
represent the same image.- Remarks
- This method may be invoked from different threads.
-
equals
-