STK ESRI Display Library

Object Model Overview

The following figure describes the main interfaces made available by the STK ESRI Display Library, and their relationships.

The IAgEsri3dRendererFactory interface and associated class provide access to the renderer (IAgEsri3dRenderer interface) for a specific 3D view via the GetRenderer method.

Once you get to the IAgEsri3dRenderer interface, you can:

configure the renderer (Config property),
open/close map documents (OpenMapDocument, CloseMapDocument methods),
access the opened map document for manipulation using ArcObjects (MapDocument property),
manage the GIS selection (ClearSelection, SelectFeature, Select Features methods),
manage the display (Refresh, Pause/Resume, ZoomToLayer, FlashFeature, FlashIdentifyObj methods),
identify GIS features by using a specialized helper function on top of the regular Arc engine's Identify capability (Identify method),
promote GIS features to STK objects (Promote method),
optimize cross-thread communication (DrawPause/DrawResume methods), and
make changes to the map document on the fly (StartMapEditing/StopMapEditing methods).

The AgEsri3dRenderer class also provides the following events:

Map document operations:
- OnMapDocumentOpened - this event is triggered after a map document has been successfully opened.
- OnMapDocumentClosed - this event is triggered just before closing a map document. You need to release all the ArcObjects and STKesriDisplay resources that you are holding at that point.
- OnMapDocumentOpenFailed - this event is triggered after a map document fails to open.
- OnMapDocumentEdited - this event is triggered after a map document has been edited (i.e. when the StopMapEditing method is called).
Rendering:
- OnDrawBegin - this event is raised when starting to render all the feature layers in the map document.
- OnDrawProgress - this event is raised when starting to render a specific feature layer in the map document.
- OnDrawEnd - this event is raised when rendering of all the feature layers in the map document is done.

In addition to the renderer the following classes and interfaces are available:

The IAgEsri3dRendererConfig interface provides miscellaneous rendering options.
The IAgEsri3dRendererContext interface exposes the GIS apartment context and enables you to instantiate objects and envelopes in the GIS thread, and also serialize objects to/from the GIS thread.

The threading architecture has several implications for how to interact with the Library programmatically:

All the components in the library are apartment-threaded.
- All the components except for the context live in the main user interface thread/apartment.
- The context (IAgEsri3dRendererContext interface) lives in the GIS thread/apartment.
The ArcObjects components are apartment-threaded as well. It is recommended that you instantiate new ArcObjects in the GIS thread. This can be achieved by using the CreateObject method of the IAgEsri3dRendererContext interface (this is conceptually similar to the IServerContext interface when working with ArcGIS server).
It is recommended that you avoid chatty calls between the 2 threads, and instead use coarse grained interfaces to limit the number of marshalling round trips.
In case chatty programming style cannot be avoided, use the DrawPause and DrawResume methods of the IAgEsri3dRenderer interface to speed up round trips between the 2 threads. These methods basically suspend the draw processing temporarily in the GIS thread, so that it is only listening to incoming calls.
Alternatively you can serialize components in order to perform all the processing in a different thread. The LoadObject and SaveObject methods of the IAgEsri3dRendererContext interface serve that purpose (similarly to the LoadObject and SaveObject methods of the IServerContext interface when working with ArcGIS server).