LuciadCPillar C# 2024.0.08
|
Represents an icon, that can for example be used when painting point data or labels. More...
Public Member Functions | |
IIconPainter | CreatePainter (IconPainterContext context) |
Creates an IIconPainter for a given context. More... | |
bool | Equals (object other) |
Returns true if two IIcons represent exactly the same image. More... | |
int | GetHashCode () |
Returns the hash value for the current icon. More... | |
Represents an icon, that can for example be used when painting point data or labels.
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 when IIcon
implementations change at runtime. When you want to modify the icon that is used to render a feature, you must create a new IIcon
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. IIcon
implementations are immutable, it implies that the IIcon.getHash
method must always return the same value, and the == operator must always return the same result. 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)
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:
icon painter
for any possible display scale. 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:
IIconPainter.GetDisplayScale
must return a value of 1.0. IIconPainter.GetDisplayScale
must return a value of 2.0. Related article: Support high-resolution (HiDPI) displays
This class and the IIconPainter
class can be used on any thread, so their implementations must be thread-safe.
The samples contain a sample icon implementation: BasicIcon. This code demonstrates how you could implement your own IIcon
and IIconPainter
.
IIconPainter Luciad.Drawing.IIcon.CreatePainter | ( | IconPainterContext | context | ) |
Creates an IIconPainter
for a given context.
context | the painting context. |
null
. bool Luciad.Drawing.IIcon.Equals | ( | object | other | ) |
Returns true
if two IIcons represent exactly the same image.
They might be different objects but they produce the same image and the system should not consider them as different. This method and getHash help the rendering framework to identify similar IIcons without having to go through the heavy processing of invoking IIconPainter.Paint
.
true
if two IIcons represent exactly the same image. int Luciad.Drawing.IIcon.GetHashCode | ( | ) |
Returns the hash value for the current icon.
This helps the rendering framework to identify if two different IIcon
represent the same image.