Polylines render lines on the ground or in space. Polylines are used to visualize many things including satellite orbits, country borders, and range rings. Polylines accept interpolators that allow them to render great arc or rhumb lines. Every line segment in a polyline can have the same color or each can have a different color. The polyline can be translucent and has a width, defined in pixels.

The polyline provides 10 Initialize methods. The easiest polyline to initialize is a line between two points; perhaps a line that indicates visibility between two objects. This is done with InitializeFromEndPoints or InitializeFromCartographicEndPoints as shown in the following example from the HowTo:

IAgGxCentralBody earth = sceneManager.CentralBodies("Earth");
IAgGxPrimitivePolyline line = new AgGxPrimitivePolyline();
line.InitializeFromCartographicEndPoints(earth,
    AgGxVertexUpdate.VertexUpdateNone,
    Trig.DegreesToRadians(39.88),       // Philadelphia
    Trig.DegreesToRadians(-75.25),      
    3000.0,
    Trig.DegreesToRadians(38.85),       // Washington, D.C.
    Trig.DegreesToRadians(-77.04),
    3000.0,
    null);                              // No interpolator
sceneManager.Primitives.Add(line);

An equally useful use-case is rendering several line segments with one polyline primitive. Line segments can be connected, as they would be for a country border, or independent, as they would be for individual aircraft routes. For a polyline if a single color, Initialize or InitializeCartographic is used to initialize a polyline with several line segments. Both methods take an array of doubles that define the vertices, or points, of the line segments. When Initialize is used, every three doubles in the array define one vertex as shown below.

InitializeCartographic is similar; every three doubles define the latitude, longitude, and altitude, respectively for a vertex.

The type of line also needs to be specified. When PolylineTypeLineStrip is used, the vertices define a connected line strip. After the first vertex, each additional vertex connects to the previous. When PolylineTypeLines is used, every two vertices define an individual line segment. The difference is shown in the image below.

Line Strip	Lines

The following example initializes a polyline with 3 line segments.

double[] positions = new double[18]  // 3 Line segments
{ 
    Trig.DegreesToRadians(1), 0,                        0,
    Trig.DegreesToRadians(3), 0,                        0,
    0,                        Trig.DegreesToRadians(1), 0,
    0,                        Trig.DegreesToRadians(3), 0,
    0,                        0,                        0, 
    Trig.DegreesToRadians(3), Trig.DegreesToRadians(3), 0
};
Array aryPositions = positions;

IAgGxCentralBody earth = sceneManager.CentralBodies("Earth");
IAgGxPrimitivePolyline line = new AgGxPrimitivePolyline();
line.InitializeCartographic(earth,
    AgGxVertexUpdate.VertexUpdateNone,
    AgGxPolylineType.PolylineTypeLines,
    ref aryPositions,
    null);
sceneManager.Primitives.Add(line);

Polylines support the standard color properties and methods: Color, Translucency, and SetRGBA, which affect every line segment. To initialize a polyline with per-line segment colors, use InitializeWithColors or InitializeCartographicWithColors. These methods take a separate array of colors, one color per vertex. Every 4 bytes in the array defines the red, green, blue and alpha components for color as shown below:

Each color in the array corresponds to a vertex in the vertex array, so the number of colors must match the number of vertices. Currently, flat shading is used; of the two vertices that define a line segment, the color of the second one is used for the color of the line segment.

The following example uses a polyline to render 3 lines, each with a different color.

double[] vertices = new double[18]  // 3 Line segments
{ 
    1000000, 0,       0,
    7000000, 0,       0,
    0,       1000000, 0,
    0,       7000000, 0,
    0,       0,       1000000, 
    0,       0,       7000000 
};

byte[] colors = new byte[24]
{
    255, 0,   0,   255,
    255, 0,   0,   255,
    255, 255, 0,   255,
    255, 255, 0,   255,
    255, 255, 255, 255,
    255, 255, 255, 255
};

Array aryVertices = vertices;
Array aryColors = colors;
IAgGxCentralBody earth = sceneManager.CentralBodies("Earth");
IAgGxPrimitivePolyline line = new AgGxPrimitivePolyline();
line.InitializeWithColors(earth,
    AgGxReferenceFrame.ReferenceFrameInertial,
    AgGxVertexUpdate.VertexUpdateNone,
    AgGxPolylineType.PolylineTypeLines,
    ref aryVertices,
    ref aryColors,
    AgGxRenderPassHint.RenderPassHintOpaque);

sceneManager.Primitives.Add(line);

To facilitate dynamic updates, polylines provide 10 Set methods corresponding to the Initialize methods. See the Dynamic Updates Overview.

A theme throughout primitives is to decouple computation from rendering. For the polyline, this means that an interpolator can be provided as input along with vertices to the polyline. The interpolator computes the actual vertices rendered. When a polyline is dynamically changed via a Set method, the interpolator is atomically called. This makes the polyline useful for rendering a wide range of line-based objects: lines, great arcs, rhumb lines, splines, etc.

Great arcs are paths on the surface that represent the shortest distance between 2 points. They are rendered by passing a great arc interpolator to a polyline as shown below.

IAgGxPrimitivePolyline line = new AgGxPrimitivePolyline();
line.InitializeFromCartographicEndPoints(earth,
    AgGxVertexUpdate.VertexUpdateNone,
    Trig.DegreesToRadians(61.22),
    Trig.DegreesToRadians(-149.85),  
    0,
    Trig.DegreesToRadians(-22.54),
    Trig.DegreesToRadians(-43.14),
    0,
    new AgGxInterpolatorRhumbLine());

sceneManager.Primitives.Add(line);

This results in the following image:

Rhumb lines are lines of constant bearing. They appear as straight lines on a Mercator 2D map projection and are well suited to navigation. Replace AgGxInterpolatorGreatArc in the above code example with AgGxInterpolatorRhumbLine to render a rhumb line. The result is shown below:

To maintain a constant bearing, the rhumb line appears to spiral, unlike the great arc which is the shortest distance between the points.

When null is passed to the interpolator argument, no interpolator is used. This is always faster then using an interpolator since no interpolated vertices need to be computed and no extra memory will be allocated. It is common to not use an interpolator when the vertices are not on the surface or are already close enough together that the line doesn't appear to cut through the globe.

Both the great arc and rhumb line interpolators provide a Granularity property that is used to control the number of interpolated vertices. The default is 1 degree. Decrease the granularity to add more vertices or increase it to add fewer vertices. Though making the granularity too high will result in lines cutting through the globe as the following example demonstrates.

IAgGxInterpolatorRhumbLine rhumbLine = new AgGxInterpolatorRhumbLine();
rhumbLine.Granularity = Trig.DegreesToRadians(30);

IAgGxPrimitivePolyline line = new AgGxPrimitivePolyline();
line.InitializeFromCartographicEndPoints(earth,
    AgGxVertexUpdate.VertexUpdateNone,
    Trig.DegreesToRadians(61.22),
    Trig.DegreesToRadians(-149.85),
    0,
    Trig.DegreesToRadians(-22.54),
    Trig.DegreesToRadians(-43.14),
    0,
    rhumbLine);

sceneManager.Primitives.Add(line);