ICustomSymbol Interface
Interface for a custom symbol.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECustomObjects assembly)
Syntax
public interface ICustomSymbolRemarks
A custom symbol is a feature in Carmenta Engine that lets you write your own code for visualizing features, when the standard visualizers and symbols are not sufficient. Custom symbols are very similar to custom visualizers, please see ICustomVisualizer for a general description of custom visualization.
But while custom visualizers are responsible for drawing complete features, custom symbols only need to draw two-dimensional symbols at given points. A standard SymbolVisualizer is used to position, rotate and scale the symbols, repeat them along lines and so on. Like other symbols, they can be used with label organization, in PointVisualizerSet and so on.
Custom symbols have limited support for 3D visualization; custom visualizers can not be used in 3D. In 3D, custom symbols are drawn onto a temporary 2D bitmap. The bitmap is then drawn in the 3D view the same way as a raster symbol.
Similar to custom visualizers, there are three types of custom symbols, depending on which interfaces the symbol implements. A normal custom symbol only implements this interface. If you need better control over hit-testing, you can also implement ICustomSymbolHitTest. If the drawing capabilities of the drawable is not sufficient, you may instead implement ICustomNativeSymbol, and draw directly to the underlying graphics object, typically a Windows DC or an OpenGL context.
Custom symbols support an advanced caching mechanism based on the attributes from the feature. The visualization for a symbol may be cached and reused for the same or another feature, as long as the relevant attributes have the same values. This caching mechanism works even if the symbols are used in a non-caching layer. For this to work, the custom symbol must inform its proxy which attributes are relevant, this is done in the GetAttributeUsage method.
The custom symbol can be used directly in a map configuration using a CustomSymbolProxy object. The proxy works as regular Carmenta Engine symbol, but delegates most calls to the custom object. Please see CustomSymbolProxy for more information how to configure and load the custom object.
Optimizing the performance of .NET and Java custom objects
Custom objects that are implemented in .NET or Java, both of which use a garbage collector to manage memory, can generate a lot of temporary object instances that must be collected and finalized by the garbage collector. These temporary objects can, depending on how many times a custom object is called during a typical update cycle, generate so much extra work for the garbage collector that it has a significant impact on performance.
In many cases you can improve the performance by adding the IMinimizeGarbageCollection interface to the custom symbol implementation. This tells Carmenta Engine that reference objects passed to, and returned from, the custom object should be disposed automatically which decreases the work that must be performed by the garbage collector.
Platforms
Windows, Linux, Android
See Also
Reference
CustomObjects Module
CustomSymbolProxy
ICustomDataSet
ICustomVisualizer
ICustomOperator
ICustomPropagation
IMinimizeGarbageCollection
ICustomSymbol Members
The ICustomSymbol type has the following members.
Methods
| Name | Description |
|---|---|
| Clone | Called to create a copy of the custom object. |
| Draw | Draws the specified feature. |
| GetAttributeUsage | Called by the proxy to find out which attributes the custom symbol. |
| InitNew | Called when the custom symbol is created by or connected to a CustomSymbolProxy. |