luciad::IIcon Class Reference

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

#include <luciad/drawing/IIcon.h>

Public Member Functions
virtual	~IIcon ()=default
virtual std::shared_ptr< IIconPainter >	createPainter (const IconPainterContext &context) const =0
	Creates an IIconPainter for a given context. More...
virtual size_t	getHash () const =0
	Returns the hash value for the current icon. More...
virtual bool	operator== (const std::shared_ptr< IIcon > &otherIcon) const =0
	Returns true if two IIcons represent exactly the same image. 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:

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

Constructor & Destructor Documentation

~IIcon()

virtual luciad::IIcon::~IIcon ( )

virtualdefault

Member Function Documentation

createPainter()

virtual std::shared_ptr< IIconPainter > luciad::IIcon::createPainter ( const IconPainterContext &  context ) const

pure virtual

Creates an IIconPainter for a given context.

Parameters

context

the painting context.

Returns

an icon painter for the current painter context, cannot be nullptr.

getHash()

virtual size_t luciad::IIcon::getHash ( ) const

pure virtual

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

operator==()

virtual bool luciad::IIcon::operator== ( const std::shared_ptr< IIcon > &  otherIcon ) const

pure virtual

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