ICustomNativeVisualizer Interface
Interface for a custom visualizer using native drawing.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECustomObjects assembly)
Syntax
public interface ICustomNativeVisualizerRemarks
Custom visualizers is a feature in Carmenta Engine that lets you write your own code for visualizing features, when the standard visualizers are not sufficient. Please see ICustomVisualizer for a general description of custom visualizers in Carmenta Engine.
A normal custom visualizer 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 visualizer is limited to the drawing primitives available on the drawable. When these primitives are not sufficient for a custom visualizer, it may implement this interface instead of ICustomVisualizer, 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.
Custom native visualizers are not supported with the DirectX and Software drawables, and only in 2D views.
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
See Also
Reference
CustomObjects Module
CustomVisualizerProxy
ICustomVisualizer
IMinimizeGarbageCollection
ICustomNativeVisualizer Members
The ICustomNativeVisualizer 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 specified feature. |
| HitTest | Tests if a feature is "hit" by a selection rectangle. |
| InitNew | Called when the custom visualizer is created by or connected to a CustomVisualizerProxy. |