Marker Batch Primitive

Using the marker batch can be as simple as creating an instance of MarkerBatchPrimitive, providing the instance with a texture and collection of positions, and then adding the instance to the primitive manager. This is shown in the following example:

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), 3000.0),
    new Cartographic(Trig.DegreesToRadians(-77.04), Trig.DegreesToRadians(38.85), 0.0),
    new Cartographic(Trig.DegreesToRadians(-90.25), Trig.DegreesToRadians(29.98), 0.0),
    new Cartographic(Trig.DegreesToRadians(-121.92), Trig.DegreesToRadians(37.37), 0.0)
};

MarkerBatchPrimitive markerBatch = new MarkerBatchPrimitive
{
    Texture = SceneManager.Textures.FromUri(texturePath)
};
markerBatch.SetCartographic(earth, positions);

SceneManager.Primitives.Add(markerBatch);

Each marker is rendered with the same texture. Since the marker batch's SizeSource is MarkerBatchSizeSource.FromTexture by default, the size of each marker is the size of the texture in pixels.

The Texture, Color, Size, and Rotation properties define the appearance of markers. When Texture is null, markers are rendered as a solid color, as shown below.

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

MarkerBatchPrimitive markerBatch = new MarkerBatchPrimitive();
markerBatch.SetCartographic(earth, positions);
markerBatch.Color = Color.Yellow;

SceneManager.Primitives.Add(markerBatch);

If instead of setting Color in the above example, we instead set the marker batch's Texture, the result would be:

markerBatch.Texture = SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/logo64.png"));

A marker batch's color and texture can be used together. The Color property is multiplied with the texture color at each pixel. By default, Color is white, so just the texture color is shown. Setting Color to yellow in the above example produces the following:

By default, when a texture is assigned to a marker batch, the size of each marker is the same size as the texture in pixels. This is because the marker batch's SizeSource defaults to MarkerBatchSizeSource.FromTexture. To use a custom marker size, the marker batch can be initialized with a SizeSource of MarkerBatchSizeSource.UserDefined and then the Size property can be set. For example:

MarkerBatchPrimitive markerBatch = new MarkerBatchPrimitive(MarkerBatchSizeSource.UserDefined)
{
    Size = new SizeF(128.0f, 64.0f)
};

The marker batch's Rotation property is used to apply a screen-space rotation. The following example rotates each marker 30 degrees counter-clockwise.

markerBatch.Rotation = Trig.DegreesToRadians(30.0);

Properties, such as Texture and Color, apply to every marker in a marker batch. In many cases, it is useful to assign different properties to each marker in a marker batch. This allows one marker batch to represent several markers, which is drastically more efficient than creating one marker batch per marker. See the Batching topic for additional performance tips.

To assign per-marker properties to a marker batch, create an instance of MarkerBatchPrimitiveOptionalParameters, provide it with collections for per-marker properties, then pass it to a marker batch's Set method, along with the positions for the markers. The following example creates a marker batch with three markers, each with a unique texture.

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(-73.58), Trig.DegreesToRadians(40.47), 0.0),
    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<Texture2D> textures = new List<Texture2D>
{
    SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/logo64.png")),
    SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/oldLogo.png")),
    SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/agiLogo.png"))
};

MarkerBatchPrimitiveOptionalParameters parameters = new MarkerBatchPrimitiveOptionalParameters();
parameters.SetTextures(textures);

MarkerBatchPrimitive markerBatch = new MarkerBatchPrimitive();
markerBatch.SetCartographic(earth, positions, parameters);

SceneManager.Primitives.Add(markerBatch);

When per-marker properties are used, the corresponding per-batch property is ignored. In the above example, the marker batch's Texture property is ignored, since per-batch textures were provided. You can mix and match per-batch and per-marker properties. For example, the above code can be modified to also include per-marker rotations and a per-batch color.

List<double> rotations = new List<double>
{
    Trig.DegreesToRadians(25.0),
    Trig.DegreesToRadians(50.0),
    Trig.DegreesToRadians(75.0)
};
parameters.SetRotations(rotations);

markerBatch.SetCartographic(earth, positions, parameters);
markerBatch.Color = Color.LightGreen;

Besides enabling a lot of flexibility, per-batch and per-marker properties allow the marker batch to automatically optimize for the specified mix of per-batch and per-marker properties. The marker batch generates source code for an optimized shader program that runs on the video card based on the specified properties. No extra memory is used nor is any extra computation performed for properties that are not used.

The size of markers can be defined in either pixels or meters. By default, the size is in pixels. No matter how far away the camera is from a marker, it will take up the same number of pixels on the screen as shown below.

To set the size to meters, set the marker batch's SizeUnit property to MarkerBatchUnit.Meters. When the units are meters, a marker's size depends on the camera's position, similar to the Model Primitive, as shown below.

Sizing markers in meters has several uses including a quick and dirty way to implement imposters to improve performance, and image-based rendering effects such as clouds, smoke, fire, and vapor trails.

Most textures used for markers have texels that are either completely opaque or completely transparent, like all of the markers shown thus far. Some textures have translucent texels, that is, texels that are neither completely opaque nor completely transparent. An example of three such textures is shown below:

The marker batch's RenderPass and SortOrder properties are used to support translucent textures. By default, these properties are initialized to efficiently support opaque textures, which includes textures with completely transparent texels.

If the above translucent textures were assigned to a default initialized marker batch, the translucency will not be shown, and the result would be similar to the image on the left below.

Opaque render pass, default sort order

Translucent render pass, default sort order

Translucent render pass, back-to-front sort order

In order to show the texture's translucency, the marker batch's RenderPass must be set to MarkerBatchRenderPass.Translucent. This will result in the middle image above. In most cases, this is all that is necessary to support translucent textures.

When translucent markers overlap each other, initialize the marker batch with a SortOrder of MarkerBatchSortOrder.BackToFront. This ensures the correct blending of translucent markers, which makes it clear which marker is in front of which marker. Compare the above middle and right images. In the middle image, it looks like the triangle is behind the purple marker. On the right, when MarkerBatchSortOrder.BackToFront is used, it is clear that the triangle is really in front. Example code to create the image on the right is shown below:

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(-73.58), Trig.DegreesToRadians(40.47), 0.0),
    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<Texture2D> textures = new List<Texture2D>
{
    SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/TranslucentCircle64.png")),
    SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/TranslucentHoles64.png")),
    SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/TranslucentTriangle64.png"))
};

MarkerBatchPrimitiveOptionalParameters parameters = new MarkerBatchPrimitiveOptionalParameters();
parameters.SetTextures(textures);

MarkerBatchPrimitive markerBatch =
    new MarkerBatchPrimitive(MarkerBatchSizeSource.FromTexture, MarkerBatchSortOrder.BackToFront)
    {
        RenderPass = MarkerBatchRenderPass.Translucent
    };
markerBatch.SetCartographic(earth, positions, parameters);

SceneManager.Primitives.Add(markerBatch);

Using MarkerBatchSortOrder.BackToFront is not as efficient as the default, MarkerBatchSortOrder.ByTexture. MarkerBatchSortOrder.BackToFront requires the CPU to sort the markers before rendering and can increase the number of costly textures changes (unless a texture atlas is used). Therefore, it is recommended to only use MarkerBatchSortOrder.BackToFront when it is visually noticeable.

Tip
An opaque marker can be made translucent by setting the marker batch's Translucency property and its RenderPass to MarkerBatchRenderPass.BasedOnTranslucency, which is the default.

Similar to the Text Batch Primitive, the marker batch supports per-batch or per-marker horizontal and vertical origins. Origins are commonly used when two primitives are at the same position and need to be separated. By default, a marker's position defines where its center is. Use the Origin property or the SetOrigins method to change the origin.

The following example creates a point batch with three points and a marker batch with three markers. Per-marker origins are defined so the markers and points are not rendered on top of each other.

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(-73.58), Trig.DegreesToRadians(40.47), 0.0),
    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<Texture2D> textures = new List<Texture2D>
{
    SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/logo64.png")),
    SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/oldLogo.png")),
    SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/agiLogo.png"))
};

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

MarkerBatchPrimitiveOptionalParameters parameters = new MarkerBatchPrimitiveOptionalParameters();
parameters.SetTextures(textures);
parameters.SetOrigins(origins);

MarkerBatchPrimitive markerBatch = new MarkerBatchPrimitive();
markerBatch.SetCartographic(earth, positions, parameters);
SceneManager.Primitives.Add(markerBatch);

PointBatchPrimitive pointBatch = new PointBatchPrimitive
{
    Color = Color.Red,
    PixelSize = 5.0f
};
pointBatch.SetCartographic(earth, positions);
SceneManager.Primitives.Add(pointBatch);

Similar to the Text Batch Primitive, the marker batch supports per-batch or per-marker pixel and eye offsets.

Pixel offsets are set using the PixelOffset property or the SetPixelOffsets method. The pixel offset defines a translation to apply from the marker's origin. 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. The following example applies a pixel offset of 80 pixels in the X direction and 40 in the Y direction.

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

MarkerBatchPrimitive markerBatch = new MarkerBatchPrimitive
{
    Texture = SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/logo64.png")),
    Origin = Origin.BottomLeft,
    PixelOffset = new PointF(80.0f, 40.0f)
};
markerBatch.SetCartographic(earth, positions);
SceneManager.Primitives.Add(markerBatch);

PointBatchPrimitive pointBatch = new PointBatchPrimitive
{
    Color = Color.Red,
    PixelSize = 5.0f
};
pointBatch.SetCartographic(earth, positions);
SceneManager.Primitives.Add(pointBatch);

In addition to pixel offsets, an eye space offset can be applied per-batch or per-marker using the EyeOffset property or the SetEyeOffsets method. 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 direction. For example, a positive Y offset may be applied to translate a marker so it is always "on top" of a model primitive.

The following example demonstrates how applying an eye offset of (0, 100000, 0) affects the position of a marker 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 10 meters).

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

MarkerBatchPrimitive markerBatch = new MarkerBatchPrimitive
{
    Texture = SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/oldLogo.png")),
    EyeOffset = new Cartesian(0.0, 100000.0, 0.0)
};
markerBatch.SetCartographic(earth, positions);
SceneManager.Primitives.Add(markerBatch);

PointBatchPrimitive pointBatch = new PointBatchPrimitive
{
    Color = Color.Red,
    PixelSize = 5.0f
};
pointBatch.SetCartographic(earth, positions);
SceneManager.Primitives.Add(pointBatch);

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

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

The marker batch supports per batch alignment options. The AlignToNorth method will orient each marker so that its up vector is pointing towards a central body's north axis. Similarly, the AlignToAxis method will orient each marker so that its up vector is pointing towards an arbitrary axis. The default behavior for a marker batch is to align each marker's up vector to the up vector of the camera, which can be set with the AlignToScreen method. The following image shows markers aligned to the Earth's north axis:

As explained in the Dynamic Updates topic, the marker batch provides Set and SetPartial methods for efficient dynamic updates of positions and per-marker properties such as color or rotation. Use the Set method to completely redefine the marker batch. If this is done frequently (e.g. every few frames), initialize the marker batch with SetHint.Frequent.

Use the SetPartial method to update a subset of positions and/or per-marker properties in the marker batch. Make sure to initialize the marker batch with SetHint.SetPartial. The following example creates a marker batch with three markers with per-marker sizes. SetPartialCartographic is used to modify the position and size of two markers.

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(-73.58), Trig.DegreesToRadians(40.47), 0.0),
    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<SizeF> sizes = new List<SizeF>
{
    new SizeF(32.0f, 32.0f),
    new SizeF(64.0f, 64.0f),
    new SizeF(128.0f, 128.0f)
};

MarkerBatchPrimitiveOptionalParameters parameters = new MarkerBatchPrimitiveOptionalParameters();
parameters.SetSizes(sizes);

MarkerBatchPrimitive markerBatch = new MarkerBatchPrimitive(MarkerBatchSizeSource.UserDefined,
                                                            MarkerBatchSortOrder.ByTexture,
                                                            SetHint.Partial);
markerBatch.SetCartographic(earth, positions, parameters);
SceneManager.Primitives.Add(markerBatch);

// Modify 2 markers in the batch
List<Cartographic> newPositions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(-73.58), Trig.DegreesToRadians(40.47), 100000),
    new Cartographic(Trig.DegreesToRadians(-77.04), Trig.DegreesToRadians(38.85), 100000)
};

List<SizeF> newSizes = new List<SizeF>
{
    new SizeF(256.0f, 256.0f),
    new SizeF(512.0f, 512.0f)
};

MarkerBatchPrimitiveOptionalParameters newParameters = new MarkerBatchPrimitiveOptionalParameters();
newParameters.SetSizes(newSizes);

markerBatch.SetPartialCartographic(earth, newPositions, newParameters, new[] { 0, 2 });

When a marker batch uses a significant number of textures, changing textures during rendering can become a performance problem even when using the default SortOrder, which is MarkerBatchSortOrder.ByTexture. The problem can become worse when using MarkerBatchSortOrder.BackToFront is used, as described in the Translucency section above.

A texture atlas is a technique that improves rendering performance by combining many small textures into one large texture; texture coordinates are used to index to each small texture in the large texture. If your marker batch uses many small textures, you should consider combining them. For example, text is commonly rendered with a texture atlas that contains all of the font's characters. However, note that in Insight3D, you should use the Text Batch Primitive to render text.

In the per-marker properties section above, a marker batch with three markers and three textures was created:

The same results can be achieved with a single texture atlas. First, combine the three textures into a single texture:

Tip
You may find NVIDIA's Texture Atlas Tools helpful for creating texture atlases.

Instead of assigning per-marker textures, a per-batch texture is used along with per-marker texture coordinates and sizes. In this case, each sub-texture is the same height so the t and q texture coordinates are 0 and 1. The s and p texture coordinates are based on the x position and width of the sub-texture in the texture.

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(-73.58), Trig.DegreesToRadians(40.47), 0.0),
    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<TextureCoordinate4DF> textureCoordinates = new List<TextureCoordinate4DF>
{
    new TextureCoordinate4DF(0.0f, 0.0f, 93.0f / 235.0f, 1.0f),
    new TextureCoordinate4DF(95.0f / 235.0f, 0.0f, 155.0f / 235.0f, 1.0f),
    new TextureCoordinate4DF(157.0f / 235.0f, 0.0f, 1.0f, 1.0f)
};

List<SizeF> sizes = new List<SizeF>
{
    new SizeF(93.0f, 64.0f),
    new SizeF(60.0f, 64.0f),
    new SizeF(78.0f, 64.0f)
};

MarkerBatchPrimitiveOptionalParameters parameters = new MarkerBatchPrimitiveOptionalParameters();
parameters.SetTextureCoordinates(textureCoordinates);
parameters.SetSizes(sizes);

MarkerBatchPrimitive markerBatch = new MarkerBatchPrimitive(MarkerBatchSizeSource.UserDefined)
{
    Texture = SceneManager.Textures.FromUri(new Uri(baseUri, "Textures/logoTextureAtlas.png"))
};
markerBatch.SetCartographic(earth, positions, parameters);

SceneManager.Primitives.Add(markerBatch);