com.esri.arcgis.carto
Class IDynamicLayerProxy

java.lang.Object
  com.esri.arcgis.interop.Dispatch
      com.esri.arcgis.carto.IDynamicLayerProxy

All Implemented Interfaces:

IDynamicLayer, Externalizable, Serializable

public class IDynamicLayerProxy
extends com.esri.arcgis.interop.Dispatch
implements IDynamicLayer, Serializable

Provides access to members that work with dynamic display.

Description

IDynamicLayer is the interface that designates a custom layer to be a dynamic layer

Remarks

A dynamic layer is a custom layer. At minimum, each dynamic layer must implement the interfaces ILayer, IDynamicLayer and IGeoDataset.

Since a dynamic layer is a custom layer, the implementer needs to implement the underlying data structure of the layer as well as the drawing, selection, identification etc. Since a dynamic layer is implementing both IDynamicLayer and ILayer, it actually has two drawing methods. The IDynamicLayer.DrawDynamicLayer method will get called when the dynamic map is enabled and ILayer.Draw method will get called when the dynamic map is disabled. That way, if your layer must draw both in standard drawing mode and in dynamic mode, you can implement both methods. When implementing the IDynamicLayer.DrawDynamicLayer method, use the Dynamic Display API and/or the OpenGL API. When implementing the ILayer.Draw method, use the standard drawing commands (e.g. ISymbol.Draw) and/or GDI/GDI+ API.

Dynamic layers can be drawn in two different ways, and therefore have two drawing phases – immediate and compiled. In each of them, when a new set of draw commands needs to be generated, the DrawDynamicLayer method needs to iterate through the layer’s underlying data-structure and generate the corresponding draw commands for each item. In the compiled phase the draw commands are being compiled into an internal dedicated Display List of the Dynamic Layer.

Every dynamic cycle, the Dynamic Map checks each Dynamic Layer’s state. If there is a Dynamic Layer that needs to be redrawn, meaning the dynamic layer needs to regenerate a new set of draw commands, the Dynamic Map will call the Dynamic Layer’s DrawDynamicLayer method, with the corresponding draw phase, and the dynamic layer will generate a new set of draw commands. If there is at least one Dynamic Layer that needs to regenerate its drawing commands, the entire Dynamic Display needs to get repainted.

A Dynamic layer needs to regenerate its drawing commands (get redrawn), according to the draw phase it is drawing in:

1. With the Immediate Phase, if it reports that its immediate phase is dirty.
2. In that case the draw commands will be executed immediately.
3. With the Compiled Phase, if it reports that its Compiled phase is dirty, and its Recompile Rate interval had elapsed.
   In that case the display list has expired, and the dynamic layer’s draw commands will be recompiled into the display list. This display list will be reused for rendering, every dynamic cycle that the dynamic display needs to get repainted, that is if the dynamic layer is not reporting that the display list has expired (and therefore the display list doesn’t need to get recompiled).

Every dynamic cycle that the Dynamic Display needs to get repainted, the Dynamic Map will call all of the Dynamic Layers DrawDynamicLayer with the Immediate Phase, but will reuse the display lists of the Dynamic Layers with the Compiled Phase.

The difference between the phases is that when the dynamic display needs to be repainted, the Dynamic Map can reuse the display lists that were generated by the Dynamic Layers that draw in the Compiled phase, but has to regenerate the drawing commands for the Dynamic Layers that draw in the immediate phase. In other words, the immediate draw phase will be called every cycle the display needs to be repainted, but the compiled draw phase will be called only when the Dynamic Map is signaled that the display list has expired (when the DynamicRecompileRate interval has elapsed and the DynamicLayerDirty dirty flag for the esriDDCompiled phase is true).

As a good practice, it is recommended for the Dynamic Layer to draw in one of the draw phases, but not in both of them.

As a rule of thumb, it is preferable to use the Compiled Phase, since using it will minimize the CPU usage and the bus traffic to the graphic card, by minimizing the frequency in which the dynamic layer draw commands are being regenerated (the layer items are being iterated and the draw commands are being called). As an example, please refer to the RSSWeatherLayer sample. If the layer items are being updated very frequently, and therefore the compiled phase display list needs to be recompiled very frequently, it is preferable to render the layer items in the Immediate Phase, instead of in the Compiled Phase. For an example, please refer to the MyDynamicLayer sample.

Another advantage of the Compiled Phase over the Immediate Phase is that when using the Immediate Phase, every change in any of the layers (or any other reason that causes a repaint of the display), will cause all of the other layers that are using the Immediate phase to regenerate their drawing code, even when there was no real reason (no change) for them to do so.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

See Also:

Serialized Form

Field Summary

boolean

noncastable

Fields inherited from class com.esri.arcgis.interop.Dispatch

DISPATCH_METHOD, DISPATCH_PROPERTYGET, DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF, objRef

Constructor Summary

	IDynamicLayerProxy()
	IDynamicLayerProxy(Object obj)
protected	IDynamicLayerProxy(Object obj, String iid)

Method Summary

void	addListener(String iidStr, Object theListener, Object theSource)
void	drawDynamicLayer(int dynamicDrawPhase, IDisplay display, IDynamicDisplay dynamicDisplay) Draws the layer to the specified display for the given draw phase.
int	getDynamicRecompileRate() Recompile Rate is the interval in milliseconds by which the dynamic layer draw method will be called, with the compiled draw phase.
boolean	isDynamicLayerDirty(int dynamicDrawPhase) Indicates if the dynamic layer has changed since last drawn for the specified draw phase.
void	removeListener(String iidStr, Object theListener)
void	setDynamicLayerDirty(int dynamicDrawPhase, boolean dirty) Indicates if the dynamic layer has changed since last drawn for the specified draw phase.

Methods inherited from class com.esri.arcgis.interop.Dispatch

bindUsingMoniker, constructVtblPosTable, convertToNative, cookieForListener, createDispatch, createObjrefMonikerDisplayName, equals, getActiveObject, getActiveObject, getDefaultProperty, getDispatchIdOfName, getLastErrorCode, getMtsObjectContext, getObjRef, getPropertyByName, getPropertyByName, getVtblPos, hashCode, initDispatch, invoke, invokeMethodByName, invokeMethodByName, invokeMethodByName, invokePropertyGetByName, invokePropertyPutByName, invokePropertyPutByRefByName, isNativeMode, isObjRef, optimizedVtblInvoke, queryInterface, readExternal, release, setNativeMode, setPropertyByName, toString, vtblInvoke, writeExternal

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

noncastable

public boolean noncastable

Constructor Detail

IDynamicLayerProxy

public IDynamicLayerProxy()

IDynamicLayerProxy

public IDynamicLayerProxy(Object obj)
                   throws IOException

Throws:

IOException

IDynamicLayerProxy

protected IDynamicLayerProxy(Object obj,
                             String iid)
                      throws IOException

Throws:

IOException

Method Detail

addListener

public void addListener(String iidStr,
                        Object theListener,
                        Object theSource)
                 throws IOException

Overrides:

addListener in class com.esri.arcgis.interop.Dispatch

Throws:

IOException

removeListener

public void removeListener(String iidStr,
                           Object theListener)
                    throws IOException

Overrides:

removeListener in class com.esri.arcgis.interop.Dispatch

Throws:

IOException

isDynamicLayerDirty

public boolean isDynamicLayerDirty(int dynamicDrawPhase)
                            throws IOException,
                                   AutomationException

Indicates if the dynamic layer has changed since last drawn for the specified draw phase.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Specified by:

isDynamicLayerDirty in interface IDynamicLayer

Parameters:

dynamicDrawPhase - A com.esri.arcgis.display.esriDynamicDrawPhase constant (in)

Returns:

The dirty

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setDynamicLayerDirty

public void setDynamicLayerDirty(int dynamicDrawPhase,
                                 boolean dirty)
                          throws IOException,
                                 AutomationException

Indicates if the dynamic layer has changed since last drawn for the specified draw phase.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Specified by:

setDynamicLayerDirty in interface IDynamicLayer

Parameters:

dynamicDrawPhase - A com.esri.arcgis.display.esriDynamicDrawPhase constant (in)

dirty - The dirty (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getDynamicRecompileRate

public int getDynamicRecompileRate()
                            throws IOException,
                                   AutomationException

Recompile Rate is the interval in milliseconds by which the dynamic layer draw method will be called, with the compiled draw phase.

Description

The DynamicRecompileRate is an interval in milliseconds that is used by the Dynamic Map in order to determine whether the Dynamic Layer’s DrawDynamicLayer method needs to be called with the Compiled Phase, in order to recompile the layer’s drawing commands into the layer’s display list.

Remarks

The DynamicLayer’s DrawDynamicLayer method of the Compiled Phase will be called, when the DynamicLayerDirty of the Compiled Phase is true, and only after the DynamicRecompileRate interval had elapsed. The underlying data-structure of the layer may already been updated, however the display would reflect these changes only after the time interval set by DynamicRecompileRate has elapsed.

Using the compiled rate is very efficient for layers that manage large amount of items where every item gets updated in a relatively low rate. This way, due to the large number of items, there are constant updates streaming in, however the changes will get accumulated and will be applied to the display, according to the DynamicRecompileRate interval. That is good, performance wise, since this method minimizes CPU usage, of iterating through the layer items and generating the draw commands, and minimizes bus traffic of the drawing commands to the graphic card.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Specified by:

getDynamicRecompileRate in interface IDynamicLayer

Returns:

The dynamicRecompileRateTimeMS

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

drawDynamicLayer

public void drawDynamicLayer(int dynamicDrawPhase,
                             IDisplay display,
                             IDynamicDisplay dynamicDisplay)
                      throws IOException,
                             AutomationException

Draws the layer to the specified display for the given draw phase.

Remarks

Use this method to generate the Layer’s draw commands that correspond to the Dynamic Draw Phase.

Make sure to generate the draw commands at the desired Draw Phase. It is recommended for a Dynamic Layer to generate draw commands (and therefore be drawn) in one of the Dynamic Draw Phases, but not both. For example, if the layer is to be drawn only in the Immediate Phase, the method should inspect the drawing phase and only generate draw commands if enum esriDynamicDrawPhase is set to esriDDPImmediate.

Use the Dynamic Display API, and/or OpenGL API in order to generate the draw commands. In the context of the DrawDynamicLayer method, the OpenGL Rendering Context is active and is setup by the Dynamic Map.

Note: The Dynamic Display and OpenGL API's can safely be used only in the context of the IDynamicLayer.DrawDynamicLayer method and IDynamicMapEvents BeforeDynamicDraw\AfterDynamicDraw events. Any attempt to use them in any other context will result in unexpected behavior.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Specified by:

drawDynamicLayer in interface IDynamicLayer

Parameters:

dynamicDrawPhase - A com.esri.arcgis.display.esriDynamicDrawPhase constant (in)

display - A reference to a com.esri.arcgis.display.IDisplay (in)

dynamicDisplay - A reference to a com.esri.arcgis.display.IDynamicDisplay (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.