ICustomNativeSymbol Interface
Interface for a custom symbol using native drawing.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECustomObjects assembly)
Syntax
public interface ICustomNativeSymbolRemarks
Custom symbols 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.
A normal custom symbol creates its visualization by calling drawing methods on the drawable. This is simple to implement, works with all types of drawables and also supports automatic hit-testing and caching. But it also means that the symbol is limited to the drawing primitives available on the drawable. When these primitives are not sufficient for a custom symbol, it may implement this interface instead of ICustomSymbol, to get access to the underlying drawing surface, typically an OpenGL context. See Custom Native Rendering for more information.
Exceptions that are thrown by custom object implementations will be logged and then propagated by Carmenta Engine as an EngineException to the application. Also, the only way a C++ custom object implementation can include a relevant error message to an application is by throwing an EngineException.
Native drawing is not supported with the DirectX and Software drawables. Also, custom native symbols are currently not supported in 3D.
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 object 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
ICustomNativeSymbol Members
The ICustomNativeSymbol type has the following members.
Methods
| Name | Description |
|---|---|
| BoundsPolygon | Calculates the bounding rectangle of the visualization of the feature. |
| Clone | Called to create a copy of the custom object. |
| Draw | Draws the symbol for specified feature. |
| HitTest | Tests if a feature is "hit" by a selection rectangle. |
| InitNew | Called when the custom symbol is created by or connected to a CustomSymbolProxy. |