Dynamic drawing APIs to create dynamic content


Summary This topic describes how to use dynamic display drawing application programming interfaces (APIs) to draw dynamic content.

In this topic


About dynamic drawing APIs to create dynamic content

Dynamic content can be drawn on a dynamic map using the following dynamic draw callbacks:
When invoking dynamic draw callbacks, the dynamic display (DD) framework creates an active OpenGL rendering context internally and passes a reference to an active DynamicDisplay object; therefore, in the dynamic draw callbacks, the DynamicDisplay drawing APIs and OpenGL APIs can be utilized to draw any dynamic content on the underlying map.
Any usage of the DynamicDisplay drawing API (or OpenGL API) in any other method results in an unknown behavior.

Drawing dynamic symbols

The DynamicDisplay object has the following four active dynamic symbols to draw dynamic objects:
  • Dynamic marker symbol (esriDSymbolMarker)
  • Dynamic line symbol (esriDSymbolLine)
  • Dynamic text symbol (esriDSymbolText)
  • Dynamic fill symbol (esriDSymbolFill)
When the drawing APIs are invoked, the dynamic drawing is determined by the properties of these four dynamic symbols. The combination of dynamic symbols are used by the DD framework to render marker, multiple markers, line, multiple lines, polyline, polygon, rectangle, text, and compound items (that include a marker and text strings around it). The following table shows the correlation of the specified geometries to each dynamic symbol:
Draw method
Dynamic marker
symbol
Dynamic text
symbol
Dynamic line
symbol
Dynamic fill
symbol
Marker
+
 
 
 
MultipleMarkers
+
 
 
 
Line
 
 
+
 
MultipleLines
 
 
+
 
Polyline
 
 
+
 
Polygon
 
 
+
(polygon's outline)
+
polygon's fill
Rectangle
 
 
+
(rectangle's outline)
+
(rectangle's fill)
Text
 
+
+
(text box outline)
+
(text box fill)
CompoundMarker*
+
+
+
(text box outline)
+
(text box fill)
ArrayMarker
+
+
+
(text box outline)
+
(text box fill)
Dynamic symbol properties, such as color, size, and so on, can be altered using methods and properties on IDynamicSymbolProperties2. The following table shows the dynamic symbol properties that can be modified using IDynamicSymbolProperties2:
 
Property
Description
G/S*
Text
symbol
Marker
symbol
Line
symbol
Fill
symbol
DynamicGlyph
Dynamic glyph for the specified dynamic symbol
G
+
+
+
+
Color
Color for the specified dynamic symbol
G
+
+
+
+
Scale(x,y)
Scales the dynamic symbol.
G
+
+
+
+
Smooth
Indicates if the specified dynamic symbol is smooth;  
only valid for text, line, and marker
G
+
+
+
+
Offset(x,y)
Offsets the dynamic symbol
G
+
+
+
+
UseReferenceScale
Indicates if the specified dynamic symbol conforms to the map reference scale
G
+
+
+
+
Heading
Heading for the specified dynamic symbol; only valid if dynamic symbol rotation alignment is a heading, and for
text and marker
G
+
+
 
+
RotationAlignment
Rotation alignment
for the specified dynamic symbol;
only valid for text
and marker
G
+
+
 
+
TextVerticalAlignment
Indicates vertical alignment for the
text dynamic
symbol
S
+
 
 
 
TextHorizontalAlignment
Indicates the horizontal alignment for the text
dynamic symbol
S
+
 
 
 
TextLeading
Indicates the text leading for the dynamic text
symbol
S
+
 
 
 
TextCharacterSpacing
Indicates an
additional space
added to each character beyond what is defined by
its character box
in the TextGlyph
S
+
 
 
 
TextWordSpacing
Indicates an
additional space
added between words in the
text string
S
+
 
 
 
TextRightToLeft
Indicates if the
text is drawn
from right-to-left
for the dynamic
text symbol
S
+
 
 
 
TextBoxHorizontalAlignment
Text box horizontal alignment for the dynamic text symbol
S
+
 
 
 
TextBoxUseDynamicFillSymbol
Indicates whether
to use the dynamic
fill symbol when drawing the text
S
+
 
 
 
TextBoxUseDynamicLineSymbol
Indicates whether
to use the dynamic line symbol when drawing the text
S
+
 
 
 
TextBoxMargins
Text box margins
for the dynamic
text symbol
S
+
 
 
 
LineContinuePattern
Indicates if the line pattern is continued
or restarted for multipart line drawings
S
 
 
+
 
*IDynamicSymbolProperties2 has two types of methods and properties—Generic (G) and Specific (S). Generic takes an extra parameter, type of dynamic symbol, and changes the state of the passed in dynamic symbol type. Specific are distinct to a dynamic symbol type; therefore, their names start with the type of dynamic symbol; for example, text leading is specific to a dynamic text symbol.
 
When drawing dynamic symbols, declare IDynamicGlyphFactory, and  IDynamicSymbolProperties2 as class variables considering the repetition of their drawing sequences.
[Java]
//This method creates and draws a marker glyph on a dynamic layer.

private void drawDynamicSymbols(IDynamicDisplay dynamicDisplay, IPoint point)throws
    AutomationException, IOException{
    // Step 1: Create glyphs from IDynamicGlyphFactory.

    if (!dynamicGlyphsCreated){
        dynamicSymbolProps = (IDynamicSymbolProperties2)dynamicDisplay;
        dynamicGlyphFactory = dynamicDisplay.getDynamicGlyphFactory();

        //Implement a method to create a glyph as specified in the next section.
        this.createMarkerGlyph();
        dynamicGlyphsCreated = true;
    }

    //Step 2: Modify dynamic symbol properties using IDynamicSymbolProperties2.
    dynamicSymbolProps.setRotationAlignment(esriDynamicSymbolType.esriDSymbolMarker,
        esriDynamicSymbolRotationAlignment.esriDSRAScreen);
    dynamicSymbolProps.setScale(esriDynamicSymbolType.esriDSymbolMarker, 0.8f, 0.8F);
    dynamicSymbolProps.setColor(esriDynamicSymbolType.esriDSymbolMarker, 0.0f, 1.0f,
        0.0f, 1.0f);


    //Step 3: Assign the glyph to the dynamic symbol.
    dynamicSymbolProps.setDynamicGlyphByRef(esriDynamicSymbolType.esriDSymbolMarker,
        markerGlyph);

    //Step 4: Draw the dynamic symbol using the DynamicDisplay object.
    dynamicDisplay.drawMarker(point);

}

Dynamic glyphs

A Dynamic glyph is a handle to a graphic resource that is rendered as a dynamic symbol. Dynamic glyphs can be created using the IDynamicGlyphFactory from file, a symbol, a glyphs group, or a handle to a bitmap. The following are the four types of dynamic glyphs:
  • Dynamic marker glyph (esriDGlyphMarker)
  • Dynamic line glyph (esriDGlyphLine)
  • Dynamic text glyph (esriDGlyphText)
  • Dynamic fill glyph (esriDGlyphFill)
It is important to correctly manage dynamic glyphs to minimize the application memory usage. Incorrect management of dynamic glyphs lead to over consumption of resources and can result in poor performance and application crashes. Minimize the dynamic glyphs creation and reuse created dynamic glyphs as much as possible. For example, create a dynamic glyph from a white symbol, set the dynamic symbol’s glyph property to use the created dynamic glyph, and use the dynamic symbol’s color and scale properties to render the dynamic symbol (that uses one created dynamic glyph) in different colors and sizes.
When a dynamic glyph is no longer in use, use the IDynamicGlyphFactory.deleteDynamicGlyph() method to release the dynamic glyph’s resources.
The dynamic glyphs factory is a singleton object; therefore, you can always cocreate and use it to create and delete dynamic glyphs. Performance wise, create dynamic glyphs in the context of IDynamicLayer.drawDynamicLayer in the esriDDPImmediate draw phase, in the context of the IDynamicMapEvents.beforeDynamicDraw, or in the IDynamicMapEvents.afterDynamicDraw methods, while casting the passed in IDynamicDisplay interface to IDynamicGlyphFactory.
See the following code example:
[Java]
//This method creates a simple marker glyph from a CharacterMarkerSymbol.

private void createDynamicGlyphs(){
    try{

        // Step 1: Create a character marker symbol.

        CharacterMarkerSymbol characterMarkerSymbol = new CharacterMarkerSymbol();
        RgbColor color = new RgbColor();
        color.setRGB(0xFFFFFF);
        characterMarkerSymbol.setColor(color);
        characterMarkerSymbol.setSize(40);
        characterMarkerSymbol.setCharacterIndex(72);

        // Step 2: Create a glyph from a character marker symbol using IDynamicGlyphFactory.
        markerGlyph = dynamicGlyphFactory.createDynamicGlyph((ISymbol)
            characterMarkerSymbol);

    }
    catch (Exception e){
        e.printStackTrace();
    }
}

Dynamic glyphs group

A dynamic glyphs group is a container that holds multiple glyphs. It is composed of a bitmap and database that keeps information about the group and elements (glyphs and glyphs items) in the group. The image is a mosaic of subimages of icons (marker glyphs), lines (line glyphs), and groups of characters (each group composes a text glyph).
The bitmap keeps color information (red, green, and blue [RGB], and alpha values) for each pixel. The bitmap can be loaded from the following two image files:
  • One that holds the RGB values
  • One that holds the alpha values or from a single image file that holds RGB and alpha (RGBA) values
The glyphs group database is loaded from an Extensible Markup Language (XML) file. This XML file holds general information about the group, specific location, and size for each item and element of the group.

A new glyphs group can be loaded using IDynamicGlyphFactory.loadDynamicGlyphsGroup. The method creates a glyphs group and returns an allocated glyphs group ID. The returned ID is a positive integer. See the following:
  • Group ID 0—Refers to rendering without using a graphical resource, which means simple lines, simple points, and so on.
  • Group ID 1—Reserved as the default glyphs group (there is a default one that exists with the dynamic display) and supplies a default set of dynamic glyphs.
To replace the preloaded default group, delete group ID 1, and immediately create a group. The dynamic map assigns the new group ID 1 and uses it as the new default glyphs group.
Performance wise, it is preferable to create a glyph group with multiple glyphs and use the glyphs from the group, rather than creating glyphs from individual image files.

Compound and array markers

It is frequently required to draw a marker with text strings around it. For ease of use, use the IDynamicCompoundMarker2 interface, which provides helper methods that draw a marker with text strings around it. You can also control the text distance from the marker, spacing between the text strings, and so on, using the methods and properties of IDynamicCompoundMarker2. The following are the two most significant methods of  IDynamicCompoundMarker2:
  • IDynamicCompoundMarker2.drawCompoundMarkerN()
  • IDynamicCompoundMarker2.drawArrayMarker()
DrawCompoundMarkerN method
DrawCompoundMarkerN methods draw a marker where the n value is  1, 2, 4, 8, or 10. The n value specifies the number of text strings around the marker. These methods use map coordinates to draw text and its corresponding marker.
The following illustration shows the layout of the drawCompoundMarker10() method:

See the following code example:
[Java]
// This method creates and draws a marker glyph, two text labels, and 
// the x,y location on the top and bottom of the marker. 

private void drawDynamicSymbols(IDynamicDisplay dynamicDisplay, IPoint point)throws
    AutomationException, IOException{
    // Step 1: Create glyphs from IDynamicGlyphFactory.

    //Create glyphs only once since they are expensive.
    if (!dynamicGlyphsCreated){
        dynamicSymbolProps = (IDynamicSymbolProperties2)dynamicDisplay;
        dynamicGlyphFactory = dynamicDisplay.getDynamicGlyphFactory();

        dynamicCompoundMarker = (IDynamicCompoundMarker2)dynamicDisplay;

        // Write a method to create glyphs as specified in the preceding section.
        this.createMarkerGlyph();
        dynamicGlyphsCreated = true;
    }

    // Step 2: Modify symbol properties using IDynamicSymbolProperties2.
    dynamicSymbolProps.setRotationAlignment(esriDynamicSymbolType.esriDSymbolMarker,
        esriDynamicSymbolRotationAlignment.esriDSRAScreen);
    dynamicSymbolProps.setScale(esriDynamicSymbolType.esriDSymbolMarker, 0.8f, 0.8F);
    dynamicSymbolProps.setColor(esriDynamicSymbolType.esriDSymbolMarker, 0.0f, 1.0f,
        0.0f, 1.0f);

    // Step 3: Assign the glyph to the dynamic symbol.
    dynamicSymbolProps.setDynamicGlyphByRef(esriDynamicSymbolType.esriDSymbolMarker,
        markerGlyph);


    // Step 4: Draw the item as a compund marker, which means you do not have to draw 
    // the items and its accompanying labels separately; thus allowing you to write less code 
    // and get better performance.
    dynamicCompoundMarker.drawCompoundMarker2(point, String.valueOf(point.getX()),
        String.valueOf(point.getY()));


}
DrawArrayMarker method
DrawArrayMarker methods draw markers with arrays of text strings in each of the five regions around the marker. The regions are center, left, right, top, and bottom. This method can draw a marker on a location in map coordinates, whereas to draw a marker on a location in screen (pixel) coordinates uses the drawScreenArrayMarker() method.
The following illustration shows the layout of the drawArrayMarker method with the input of arrays of sizes—Center[4], Left[5], Right[5], Top[2], and Bottom[3]:


See Also:

About dynamic display
How to draw a bitmap element using OpenGL
How to create a dynamic glyph from a marker symbol
Sample:Dynamic Layer WalkThrough




Development licensing Deployment licensing
Engine Developer Kit Engine Runtime