ExternalDrawable Class
A drawable that can render map images onto an external drawing surface provided by the application.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECore assembly)
Syntax
public class ExternalDrawable : DrawableRemarks
An ExternalDrawable renders maps onto a "drawing surface" provided by the application. Currently this is only supported for C# and C++ in combination with OpenGL; the drawing surface consists of an OpenGL context and an HDC (Windows), GLXDrawble (Linux, OpenGL) or EGLDrawble (Linux, OpenGL ES) that is set up by the application. In some cases, this allows for a much better integration with other third-party libraries and frameworks using OpenGL, such as Qt (www.qt.io).
In contrast, the WindowDrawable and BitmapDrawable always create their own, private OpenGL or DirectX contexts, which sometimes can make them difficult to integrate efficiently into an application with other third-party libraries.
Using an ExternalDrawable changes the behavior of the View and MapControl in certain ways:
A map update by Carmenta Engine is in this case only a part of an application window update. Therefore Carmenta Engine does not swap the OpenGL buffers when the map is drawn. Also, clearing the background before drawing the map is optional.
The C++ MapControl class normally replaces the drawable on the view with its own WindowDrawable that attaches to the control window. This is not done if the original drawable is an ExternalDrawable.
The C++ MapControl ignores any paint or resize events when an ExternalDrawable is used. It is up the application to handle repainting and resizing of the drawable.
The methods Save, GetImage, GetRaster, CreateSnapshot and DrawSnapshot are not supported and will throw an exception if called.
The QtQuick MapControl uses the ExternalDrawable.
When using the ExternalDrawable and Qt on Linux, the Qt libraries have some requirements regarding the use of OpenGL or OpenGL ES, see the Graphics renderers supported by Carmenta Engine page for more information.
The OpenGL handles can be created explicitly by the application, or by some other third-party component. For instance, if the Qt QGLWidget is used, the following code may be used inside its initalizeGL() method to pick up the OpenGL context and device created by the widget, and create the ExternalDrawable:
void initializeGL()
{
ExternalDrawablePtr d = new ExternalDrawable();
d->attach(d->currentContext(), d->currentSurface());
myView->drawable(d);
}
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
ResourceObject
Drawable
ExternalDrawable
Platforms
Windows, Linux, Android
ExternalDrawable Members
The ExternalDrawable type has the following members.
Constructors
| Name | Description |
|---|---|
| ExternalDrawable | Initializes a new instance of the ExternalDrawable class. |
Properties
| Name | Description |
|---|---|
| Background | Gets or sets the background color of the drawable. Inherited from Drawable |
| CurrentContext | Gets the current OpenGL rendering context for the calling thread. |
| CurrentSurface | Gets the draw surface for the current OpenGL rendering context. |
| FlipY | Flips the y-axis when Carmenta Engine draws a map in the ExternalDrawable. |
| FogColor | Gets or sets the color of the fog in a 3D view. Inherited from Drawable |
| FogDensity | Gets or sets the density of the fog in a 3D view. Inherited from Drawable |
| Height | Gets or sets the height of the drawable in pixels. Inherited from Drawable |
| IsAttached | Gets a value that tells whether the drawable is attached to a drawing surface or not. |
| IsDisposed | Gets a value that tells whether the current ExternalDrawable has been disposed. Inherited from EngineObject |
| Name | Gets or sets the name of the ExternalDrawable. Inherited from ResourceObject |
| NativeHandle | Gets the native Carmenta Engine kernel object the current ExternalDrawable represents. Inherited from EngineObject |
| PixelSize | Gets or sets a drawable-specific pixel size. Inherited from Drawable |
| PixelSizeAdjustments | Gets or sets a number of parameters that adjusts rendering to the DPI of the display. Inherited from Drawable |
| Renderer | Gets the type of graphics renderer used by the drawable. Inherited from Drawable |
| RendererSettings | Gets or sets a number of parameters that adjusts renderer settings. Inherited from Drawable |
 ScreenPixelSize | Gets or sets the size of a screen pixel. Inherited from Drawable |
| Swap | Gets or sets a flag indicating if the front and back buffers of the drawable are swapped automatically. Inherited from Drawable |
| Transform | Gets or sets the current 2D affine transform. Inherited from Drawable |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
| Viewport | Gets or sets the viewport that OpenGL will draw into. |
| Width | Gets or sets the width of the drawable in pixels. Inherited from Drawable |
| Wireframe | Gets or sets a flag indicating that meshes in 3D should be drawn as wireframes. Inherited from Drawable |
Methods
| Name | Description |
|---|---|
| AdjustSize | Adjusts the drawable to the specified width and height. Inherited from Drawable |
| Attach | Overloaded. Attaches the drawable to a drawing surface, possibly with a secondary OpenGL context. |
| Clone | Creates a copy of an object. Inherited from EngineObject |
| CreateSnapshot | Creates a bitmap copy of the drawable, a "snapshot". Inherited from Drawable |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| DrawArc | Draws an elliptic arc. Inherited from Drawable |
| DrawLine | Draws a line with the specified geometry and pen. Inherited from Drawable |
| DrawPolygon | Draws a polygon with the specified brush and pen. Inherited from Drawable |
| DrawRaster | Draws a raster. Inherited from Drawable |
| DrawSnapshot | Draws a snapshot created by CreateSnapshot. Inherited from Drawable |
| DrawString | Draws a text string. Inherited from Drawable |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |
| GetImage | Overloaded. Saves the contents of the drawable to a memory buffer, possibly with georeferencing information. Inherited from Drawable |
| GetNativeRendererInfo | Retrieves information necessary to perform custom native rendering. Inherited from Drawable |
| GetRaster | Copies all pixels in the drawable into a new Raster and returns it. Inherited from Drawable |
| Save | Overloaded. Saves the contents of the drawable to a file, possibly with georeferencing information. Inherited from Drawable |
| SetPropertiesFrom | Reserved for internal use. Inherited from Drawable |
| SwapBuffers | Swaps the front and back buffers of the drawable. Inherited from Drawable |
| TextBounds | Calculates the bounding box of a text string if drawn with DrawString. Inherited from Drawable |
Events
| Name | Description |
|---|---|
| FrameCompleted | Reserved for internal use. Inherited from Drawable |