LuciadCPillar C# 2024.0.08
Luciad.Drawing.IIcon Interface Reference

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...
 

Detailed Description

Represents an icon, that can for example be used when painting point data or labels.

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 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.
  • Because 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.

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:

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.

Member Function Documentation

◆ CreatePainter()

IIconPainter Luciad.Drawing.IIcon.CreatePainter ( IconPainterContext  context)

Creates an IIconPainter for a given context.

Parameters
contextthe painting context.
Returns
an icon painter for the current painter context, cannot be null.

◆ Equals()

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.

Returns
true if two IIcons represent exactly the same image.
Since
2020.2

◆ GetHashCode()

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.

Remarks
This method may be invoked from different threads.
Returns
the hash value for the current icon.
Since
2020.2