Text Batch Primitive

The text batch primitive renders a group of strings with the same font. Each string can have a different position, color, horizontal origin, vertical origin, pixel offset, and eye offset. Using the text batch is similar to using the point batch, only strings are rendered instead of points.

Note
Technical Details: The text batch uses a GPU-based rendering algorithm described in our blog post: Rendering Text Fast.

Basic Example

The following example renders two strings with the MS Sans Serif font. An collection containing the strings and a parallel collection containing positions corresponding to each string are used to define the primitive.

Copy

GraphicsFont font = new GraphicsFont("MS Sans Serif", 12);

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(-75.25), Trig.DegreesToRadians(39.88), 0.0),
    new Cartographic(Trig.DegreesToRadians(-77.04), Trig.DegreesToRadians(38.85), 0.0)
};

List<string> strings = new List<string>
{
    "Philadelphia",
    "Washington, D.C."
};

TextBatchPrimitive textBatch = new TextBatchPrimitive(font, SetHint.Infrequent);
textBatch.SetCartographic(earth, positions, strings);

SceneManager.Primitives.Add(textBatch);

Fonts

GraphicsFont defines the font used to render a text batch. The constructor defines the font based on name, size, style, and outline. When a font is created with an outline, text is rendered with a colored outline as shown below.

Copy

// Bold and outline font
GraphicsFont font = new GraphicsFont("MS Sans Serif", 12, FontStyle.Bold, true);

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(-75.25), Trig.DegreesToRadians(39.88), 0.0),
    new Cartographic(Trig.DegreesToRadians(-77.04), Trig.DegreesToRadians(38.85), 0.0)
};

List<string> strings = new List<string>
{
    "Philadelphia",
    "Washington, D.C."
};

TextBatchPrimitive textBatch = new TextBatchPrimitive(font, SetHint.Infrequent)
{
    OutlineColor = Color.Red
};
textBatch.SetCartographic(earth, positions, strings);

Per-String Color

By default, text is white. The standard color and translucency properties are used to change the color of every string in the batch. For more flexibility, each string can have a unique color. This is done by creating a collection of colors, where each color corresponds to one string. The collection of colors is an optional parameter, so it is added to a TextBatchPrimitiveOptionalParameters object, which is then passed to the primitive, as shown below:

Copy

GraphicsFont font = new GraphicsFont("MS Sans Serif", 12, FontStyle.Regular, false);

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(-75.25), Trig.DegreesToRadians(39.88), 3000.0),
    new Cartographic(Trig.DegreesToRadians(-77.04), Trig.DegreesToRadians(38.85), 0.0)
};

List<string> strings = new List<string>
{
    "Philadelphia",
    "Washington, D.C."
};

List<Color> colors = new List<Color>
{
    Color.FromArgb(255, 255, 0, 255),
    Color.FromArgb(127, 255, 0, 255)
};

TextBatchPrimitiveOptionalParameters parameters = new TextBatchPrimitiveOptionalParameters();
parameters.SetColors(colors);

TextBatchPrimitive textBatch = new TextBatchPrimitive(font, SetHint.Infrequent);
textBatch.SetCartographic(earth, positions, strings, parameters);

SceneManager.Primitives.Add(textBatch);

Origins

In many cases, text should be aligned be next to another primitive, such as a point, marker, or model. By default, a string's position defines the bottom left corner of the text. Using TextBatchPrimitiveOptionalParameters, the horizontal origin can be configured as left, center, or right, and the vertical origin as bottom, center, or top. Use the Origin property to set the origin for every string in a batch, or use the SetOrigins method to define origins per-string. The following code creates a text batch with several strings to demonstrate different origins:

Copy

GraphicsFont font = new GraphicsFont("MS Sans Serif", 12, FontStyle.Regular, false);

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(-75.25), Trig.DegreesToRadians(39.88), 0.0),
    new Cartographic(Trig.DegreesToRadians(-75.25), Trig.DegreesToRadians(39.88), 0.0),
    new Cartographic(Trig.DegreesToRadians(-75.25), Trig.DegreesToRadians(39.88), 90000.0),
    new Cartographic(Trig.DegreesToRadians(-75.25), Trig.DegreesToRadians(39.88), 90000.0)
};

List<string> strings = new List<string>
{
    "Top Left Origin",
    "Bottom Right Origin",
    "Top Center Origin",
    "Bottom Center Origin"
};

List<Origin> origins = new List<Origin>
{
    Origin.TopLeft,
    Origin.BottomRight,
    Origin.TopCenter,
    Origin.BottomCenter
};

TextBatchPrimitiveOptionalParameters parameters = new TextBatchPrimitiveOptionalParameters();
parameters.SetOrigins(origins);

TextBatchPrimitive textBatch = new TextBatchPrimitive(font, SetHint.Infrequent);
textBatch.SetCartographic(earth, positions, strings, parameters);

PointBatchPrimitive pointBatch = new PointBatchPrimitive(SetHint.Infrequent)
{
    PixelSize = 8.0f
};
pointBatch.SetCartographic(earth, positions);

SceneManager.Primitives.Add(textBatch);
SceneManager.Primitives.Add(pointBatch);

Text Batch Horizontal and Vertical Origins

Pixel and Eye Offsets

Using TextBatchPrimitiveOptionalParameters, text can be offset from its position in either pixel or eye coordinates. In pixel coordinates, increasing X moves from the left toward the right side of the window, and increasing Y moves from the bottom to the top. To move "Philadelphia" to the right so the "P" and the point do not overlap, the following code example applies a pixel offset of 10:

Copy

List<PointF> pixelOffsets = new List<PointF>
{
    new PointF(10.0f, 0.0f),
    new PointF(0.0f, 0.0f)
};

TextBatchPrimitiveOptionalParameters parameters = new TextBatchPrimitiveOptionalParameters();
parameters.SetPixelOffsets(pixelOffsets);

In the above example, "Washington, D.C." has an offset of (0, 0) so it is not moved from its position. If every string in a batch will have the same offset, use the PixelOffset property instead of the SetPixelOffsets method.

In addition to pixel offsets, an eye space offset can be applied to each string using EyeOffset or SetEyeOffsets. Each unit in eye space is 1 meter. Positive X points towards the camera's right, positive Y points up, and negative Z points along the view vector. For example, a positive Y offset may be applied to translate a string so it is always "on top" of a model primitive.

The following images demonstrate how applying an eye offset of (0, 100000, 0) affects the position of a string from different view points. Note that an eye offset is different than a pixel offset or a world translation (e.g. offset the altitude by ten meters).

From this view, the eye offset moves the strings approximately north.

From a different view, the offset moves the strings approximately along their surface normals.

Unicode Support

TextBatchPrimitive has support for Unicode text. To use Unicode strings, initialize the TextBatchPrimitive with a GraphicsFont where the font family name is one that supports the Unicode characters used. If the file is formatted with a Unicode encoding, the string can be the actual Unicode glyphs. Otherwise, the Unicode characters can be encoded with a '\u' followed by the hexadecimal encoding, as seen in the code example below:

Copy

List<string> text = new List<string>
{
    "Wilkommen",
    "Bienvenue",
    "Bem-vindo",
    "Welcome",
    "\u0623\u0647\u0644\u0627\u064B\u0020\u0648\u0020\u0633\u0647\u0644\u0627\u064B",
    "\u0414\u043E\u0431\u0440\u043E\u0020\u043F\u043E\u0436\u0430\u043B\u043E\u0432\u0430\u0442\u044A"
};

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(9.0), Trig.DegreesToRadians(51.0), 0.0),
    new Cartographic(Trig.DegreesToRadians(2.0), Trig.DegreesToRadians(46.0), 0.0),
    new Cartographic(Trig.DegreesToRadians(-8.0), Trig.DegreesToRadians(39.5), 0.0),
    new Cartographic(Trig.DegreesToRadians(-97.0), Trig.DegreesToRadians(38.0), 0.0),
    new Cartographic(Trig.DegreesToRadians(45.0), Trig.DegreesToRadians(25.0), 0.0),
    new Cartographic(Trig.DegreesToRadians(100.0), Trig.DegreesToRadians(60.0), 0.0)
};

GraphicsFont font = new GraphicsFont(new Font("Arial", 12), true);
TextBatchPrimitive textBatch = new TextBatchPrimitive(font, SetHint.Infrequent);
textBatch.SetCartographic(earth, positions, text);

Dynamic Updates

As explained in the Dynamic Updates topic, the text batch provides Set and SetPartial methods for efficient dynamic updates of positions, strings, and optional parameters, such as colors. Use Set to completely redefine the text batch. If this is done frequently (e.g. every few frames), initialize the text batch with SetHint.Frequent.

Use SetPartial to update a subset of strings in the text batch. Make sure to initialize the text batch with SetHint.Partial. The following example updates the position of the second string in the text batch:

Copy

// textBatch was initialized with SetHint.Partial.

List<Cartesian> newPosition = new List<Cartesian>
{
    new Cartesian(p1.X, p1.Y, p1.Z)
};
List<int> indices = new List<int>
{
    1
};

textBatch.SetPartial(newPosition, null, indices);

Due to the text batch's vertex data layout, SetPartial has a few limitations:

If the length of a string increases (e.g. changes from "0.1" to "0.12"), the new length cannot be longer than the length defined by MaximumStringLength. It is recommended to set this property to the anticipated length of the longest string when initializing a text batch.
The string's text must also be passed in order to modify the string's horizontal or vertical origin.