Click or drag to resize

Screen Overlays

Screen Overlays are used to render objects in 2D screen-space on top of a 3D scene. For example, screen overlays can be used to display your company's logo, create a translucent heads-up display (HUD), or display a video feed from an Unmanned Aerial Vehicle (UAV). Screen overlays support pixel and fractional units, translation, scale, and rotation transformations, and a user defined z-order.

Basics

TextureScreenOverlay is used to render a texture on the screen. The following example renders a texture overlay in the bottom, left corner of the screen.

C#
TextureScreenOverlay overlay = new TextureScreenOverlay(0.0, 0.0, 128.0, 128.0)
{
    Texture = SceneManager.Textures.FromUri(textureUri)
};

SceneManager.ScreenOverlays.Add(overlay);
SceneManager.Render();
Screen Overlay

The screen overlay is initialized to be located at the origin (0, 0) with a width and height of 128 pixels. By default, the bottom, left corner is the origin for screen overlays. This can be changed and is discussed in the Origin section below. Next, a texture is loaded from a PNG file and assigned to the overlay's Texture property. Finally, the overlay is added to the SceneManagerScreenOverlays collection and all scenes are rendered by calling Render.

The texture used with a screen overlay need not be a simple static image loaded from a file. It can also be a Raster conditioned with Insight3D's extensive imaging capabilities or a video. By default, the texture's aspect ratio is not maintained. To maintain the aspect ratio of the texture during sizing of the overlay, set the MaintainAspectRatio property.

For best performance, Render should be called just once to render all scenes after a batch of Primitives, Globe Overlays, and Screen Overlays have been added. When animating, it is not necessary to explicitly render at all.

When a screen overlay should no longer be rendered, remove it from the overlay manager:

C#
SceneManager.ScreenOverlays.Remove(overlay);
Units

In previous examples, the screen overlay's position, width, and height were defined in pixels. If the window resizes, the position and size of the overlay will not change. An alternative to pixel units is fractional units. Using fractional units, an overlay's position or size is defined as a percentage of its parent's size. When its parent's size changes, the overlay adjusts itself accordingly.

When an overlay is added directly to the SceneManagerScreenOverlays collection (which is an instance of ScreenOverlayManager), its parent is the window itself. The details of adding a screen overlay as a child of another screen overlay are discussed in the Nesting Overlays section.

The percentage is in the range [0.0, 1.0], where 1.0 is 100%. Consider the following example:

C#
ScreenOverlayPoint position = new ScreenOverlayPoint(0.25, 0.25, ScreenOverlayUnit.Fraction, ScreenOverlayUnit.Fraction);
ScreenOverlaySize size = new ScreenOverlaySize(0.5, 0.5, ScreenOverlayUnit.Fraction, ScreenOverlayUnit.Fraction);
TextureScreenOverlay overlay = new TextureScreenOverlay(position, size);
Screen Overlay Fractional Unit Location

The overlay is constructed so that its left origin is 50% of the window width toward the right and its bottom origin is 25% of the window height toward the top. In addition, the overlay will consume 50% of the window in both directions.

A screen overlay's position and size can be changed after construction using its Position and Size properties. Individual components can be set using the X, Y, Width, and Height properties.

C#
overlay.Position = new ScreenOverlayPoint(0.5, 0.25, ScreenOverlayUnit.Fraction, ScreenOverlayUnit.Fraction);

Pixel and fractional units can be mixed. For example, an overlay's position can be defined using pixel units and its size defined using fractional units.

When resizing or transforming an overlay, you may want to set limits using the MinimumSize and MaximumSize properties. These limits will not be violated, regardless of how the overlay is sized.

Origin

A screen overlay's Origin property defines how the overlay is positioned relative to its parent, and the direction of its X and Y axes. The default is ScreenOverlayOrigin.BottomLeft. This indicates that the overlay's position is relative to its parent's bottom left corner. Positive X extends to the right and positive Y extends upwards. Several other origins are available, such as the ones shown in the example below:

C#
TextureScreenOverlay bottomLeft = new TextureScreenOverlay(0.0, 0.0, 120.0, 80.0)
{
    Texture = SceneManager.Textures.FromUri(bottomLeftTextureUri),
    Origin = ScreenOverlayOrigin.BottomLeft
};
SceneManager.ScreenOverlays.Add(bottomLeft);

TextureScreenOverlay bottomRight = new TextureScreenOverlay(0.0, 0.0, 120.0, 80.0)
{
    Texture = SceneManager.Textures.FromUri(bottomRightTextureUri),
    Origin = ScreenOverlayOrigin.BottomRight
};
SceneManager.ScreenOverlays.Add(bottomRight);

TextureScreenOverlay topRight = new TextureScreenOverlay(0.0, 0.0, 120.0, 80.0)
{
    Texture = SceneManager.Textures.FromUri(topRightTextureUri),
    Origin = ScreenOverlayOrigin.TopRight
};
SceneManager.ScreenOverlays.Add(topRight);

TextureScreenOverlay topLeft = new TextureScreenOverlay(0.0, 0.0, 120.0, 80.0)
{
    Texture = SceneManager.Textures.FromUri(topLeftTextureUri),
    Origin = ScreenOverlayOrigin.TopLeft
};
SceneManager.ScreenOverlays.Add(topLeft);

SceneManager.Render();
Screen Overlay Anchor Style
Pinning

A screen overlay's PinningPosition and PinningOrigin properties define the point on the overlay that will be "pinned" to the position defined by the Position property.

By default, the pinning position is (0, 0), and the pinning origin is set to ScreenOverlayPinningOrigin.Automatic, which means that the origin and placement of the pinning position will always be the same as the overlay's Origin. For example, if the overlay's origin is set to ScreenOverlayOrigin.TopRight, the point on the overlay that will correspond to its Position property will be its top right corner.

Below, the pinning position is specified to be 50 pixels inset from the top right corner of the overlay. The red dot represents the pinning position on the overlay, and the intersection of the white lines shows the value of the overlay's Position property.

C#
TextureScreenOverlay overlay = new TextureScreenOverlay(200.0, 200.0, 200.0, 200.0)
{
    Origin = ScreenOverlayOrigin.BottomLeft,
    Color = Color.LightBlue,
    Translucency = 0.4f,
    PinningPosition = new ScreenOverlayPoint(50.0, 50.0),
    PinningOrigin = ScreenOverlayPinningOrigin.TopRight
};
SceneManager.ScreenOverlays.Add(overlay);
Screen Overlay Pinning
Transformations

Screen overlays support a full set of affine transformations, including translation, scaling, and rotation.

TranslationX and TranslationY are used to define the translation transformation applied to the overlay. Translation is used to move the overlay relative to its Position property, respecting the X and Y axes defined by the overlay's origin. For example, when the origin is ScreenOverlayOrigin.BottomLeft, a translation of (50, 50) moves the overlay 50 pixels to the right and 50 pixels up. When the origin is ScreenOverlayOrigin.TopRight, the same translation moves the overlay 50 pixels to the left and 50 pixels down. This is shown in the following example:

C#
TextureScreenOverlay bottomLeft = new TextureScreenOverlay(0.0, 0.0, 101.0, 81.0)
{
    Texture = SceneManager.Textures.FromUri(textureUri),
    Origin = ScreenOverlayOrigin.BottomLeft,
    TranslationX = 50.0,
    TranslationY = 50.0,
    Translucency = 0.3f
};
SceneManager.ScreenOverlays.Add(bottomLeft);

TextureScreenOverlay topRight = new TextureScreenOverlay(0.0, 0.0, 101.0, 81.0)
{
    Texture = SceneManager.Textures.FromUri(textureUri),
    Origin = ScreenOverlayOrigin.TopRight,
    TranslationX = 50.0,
    TranslationY = 50.0,
    Translucency = 0.3f
};
SceneManager.ScreenOverlays.Add(topRight);

SceneManager.Render();
Screen Overlay Translation

The Scale property applies a scale transformation to the overlay. This can modify the size of an overlay relative to its Size property. A Scale less than 1.0 will shrink the overlay, while a Scale greater than 1.0 will enlarge it, as shown below:

C#
bottomLeft.Scale = 2.0;
topRight.Scale = 0.5;
Screen Overlay Scale

RotationAngle defines the rotation transformation applied to the overlay. The angle is defined in radians and positive angles rotate counter-clockwise. By default, the rotation point is the center of the overlay, and is specified with the RotationPoint property. The following example shows an overlay rotated counter-clockwise 60 degrees.

C#
TextureScreenOverlay bottomLeft = new TextureScreenOverlay(0.0, 0.0, 101.0, 81.0)
{
    Texture = SceneManager.Textures.FromUri(textureUri),
    Origin = ScreenOverlayOrigin.Center,
    RotationAngle = Trig.DegreesToRadians(60.0),
    Translucency = 0.3f
};
SceneManager.ScreenOverlays.Add(bottomLeft);
Screen Overlay Rotate

In addition to the transformations above, the FlipX and FlipY properties can be used to flip an overlay at its center along the X or Y axes, respectively.

Z-Order

When multiple overlays overlap each other, use the BringToFront and SendToBack methods to control the render order. The following example creates three overlays and ensures that the first one created is rendered on top of the other two:

C#
TextureScreenOverlay top = new TextureScreenOverlay(0.0, 0.0, 101.0, 81.0)
{
    Texture = SceneManager.Textures.FromUri(topTextureUri),
    Origin = ScreenOverlayOrigin.Center,
    Translucency = 0.3f
};
SceneManager.ScreenOverlays.Add(top);

TextureScreenOverlay left = new TextureScreenOverlay(0.0, 0.0, 128.0, 128.0)
{
    Texture = SceneManager.Textures.FromUri(leftTextureUri),
    Origin = ScreenOverlayOrigin.Center,
    TranslationX = -64.0,
    TranslationY = 0.0
};
SceneManager.ScreenOverlays.Add(left);

TextureScreenOverlay right = new TextureScreenOverlay(0.0, 0.0, 128.0, 128.0)
{
    Texture = SceneManager.Textures.FromUri(rightTextureUri),
    Origin = ScreenOverlayOrigin.Center,
    TranslationX = 64.0,
    TranslationY = 0.0
};
SceneManager.ScreenOverlays.Add(right);

top.BringToFront();
Screen Overlay Z-Order

The Z-order is defined relative to other overlays with the same parent.

Borders

A border can be rendered around a screen overlay by setting the BorderSize, BorderColor, and BorderTranslucency properties. BorderSize is defined in pixels and is 0 by default. When it is greater than 0, a border is rendered around the overlay's bounding rectangle using BorderColor and BorderTranslucency as shown below:

C#
TextureScreenOverlay overlay = new TextureScreenOverlay(0.0, 0.0, 101.0, 81.0)
{
    Texture = SceneManager.Textures.FromUri(textureUri),
    Origin = ScreenOverlayOrigin.Center,
    Translucency = 0.3f,
    BorderSize = 2,
    BorderColor = Color.Red,
    BorderTranslucency = 0.2f
};
SceneManager.ScreenOverlays.Add(overlay);
Screen Overlay Borders
Control Coordinates

When picking, it can be useful to know a screen overlay's bounds relative to the overall Insight3D control rather than relative to its parent. The ControlPosition, ControlSize, and ControlBounds properties provide this functionality. In the example below, a border is rendered around the bounding rectangle of the overlay. The OverlayToolbar type referenced below can be found in the picking section of the HowTo example application.

C#
OverlayToolbar overlayToolbar = new OverlayToolbar();
TextureScreenOverlay toolbarPanel = overlayToolbar.Overlay;
toolbarPanel.Scale = 1.5;
toolbarPanel.Origin = ScreenOverlayOrigin.BottomCenter;
toolbarPanel.RotationAngle = Trig.DegreesToRadians(-45.0);
toolbarPanel.TranslationY = 200.0;

ScreenOverlayPoint position = overlayToolbar.Overlay.ControlPosition;
ScreenOverlaySize size = overlayToolbar.Overlay.ControlSize;
ScreenOverlay controlBounds = new ScreenOverlay(position, size)
{
    BorderSize = 2,
    BorderColor = Color.Red,
    Translucency = 0.9f
};

SceneManager.ScreenOverlays.Add(controlBounds);
Screen Overlay Screen Bounds

A position defined relative to the overall control can be converted to a coordinate relative to an overlay, and vice-versa, using the ControlToOverlay and OverlayToControl methods. Below, a coordinate relative to an overlay is translated into its screen coordinate, and then back into the overlay's coordinates:

C#
ScreenOverlay overlay = new ScreenOverlay(100.0, 100.0, 200.0, 200.0);
SceneManager.ScreenOverlays.Add(overlay);

ScreenOverlayPoint screenPoint = overlay.OverlayToControl(100.0, 100.0);
Console.WriteLine(screenPoint.X + ", " + screenPoint.Y);
// => 200, 200

ScreenOverlayPoint overlayPoint = overlay.ControlToOverlay(screenPoint.X, screenPoint.Y);
Console.WriteLine(overlayPoint.X + ", " + overlayPoint.Y);
// => 100, 100
Nesting Overlays

Screen overlays can be nested within other screen overlays, forming a hierarchy of screen overlays. The following example adds an overlay to another overlay's Overlays collection. It then adds the first overlay to yet another overlay:

C#
ScreenOverlay screenOverlay = new ScreenOverlay(10.0, 10.0, 200.0, 200.0)
{
    Origin = ScreenOverlayOrigin.TopRight,
    Color = Color.LightSteelBlue,
    BorderSize = 1
};

ScreenOverlayPoint childPanelPosition = new ScreenOverlayPoint(0.0, 0.0);
ScreenOverlaySize childPanelSize = new ScreenOverlaySize(0.5, 0.5, ScreenOverlayUnit.Fraction, ScreenOverlayUnit.Fraction);
ScreenOverlay childPanel = new ScreenOverlay(childPanelPosition, childPanelSize)
{
    Origin = ScreenOverlayOrigin.Center,
    Color = Color.SteelBlue,
    BorderSize = 1
};

ScreenOverlayPoint childPanelChildPosition = new ScreenOverlayPoint(0.0, 0.0);
ScreenOverlaySize childPanelChildSize = new ScreenOverlaySize(0.5, 0.5, ScreenOverlayUnit.Fraction, ScreenOverlayUnit.Fraction);
ScreenOverlay childPanelChild = new ScreenOverlay(childPanelChildPosition, childPanelChildSize)
{
    Origin = ScreenOverlayOrigin.BottomRight,
    Color = Color.Green,
    BorderSize = 1
};

childPanel.Overlays.Add(childPanelChild);
screenOverlay.Overlays.Add(childPanel);
SceneManager.ScreenOverlays.Add(screenOverlay);

When a screen overlay is added to an overlay collection, its Parent property returns the overlay panel that contains it, or, if the overlay was added to the screen overlay manager, the manager is returned. The IScreenOverlayContainer interface is implemented by both the overlay manager and overlay panels, and can be cast to the more specific type, as seen below.

C#
ScreenOverlay screenOverlay = new ScreenOverlay(0.0, 0.0, 200.0, 200.0);

ScreenOverlayPoint position = new ScreenOverlayPoint(0.0, 0.0);
ScreenOverlaySize size = new ScreenOverlaySize(0.5, 0.5, ScreenOverlayUnit.Fraction, ScreenOverlayUnit.Fraction);
ScreenOverlay childOverlay = new ScreenOverlay(position, size);

screenOverlay.Overlays.Add(childOverlay);
SceneManager.ScreenOverlays.Add(screenOverlay);

ScreenOverlay panel = (ScreenOverlay)childOverlay.Parent;
ScreenOverlayManager manager = (ScreenOverlayManager)panel.Parent;

Screen overlays have a Padding property which specifies how their child overlays will be offset from the bounds of the parent when being positioned. In the example below, a 10 pixel padding is applied to each edge of the manager and an overlay.

C#
SceneManager.ScreenOverlays.Padding = new ScreenOverlayPadding(10.0, 10.0, 10.0, 10.0);

ScreenOverlay screenOverlay = new ScreenOverlay(0.0, 0.0, 200.0, 200.0)
{
    Padding = new ScreenOverlayPadding(10.0, 10.0, 10.0, 10.0),
    Color = Color.LightSteelBlue,
    BorderSize = 1
};

ScreenOverlayPoint overlayPanelChildPosition = new ScreenOverlayPoint(0.0, 0.0);
ScreenOverlaySize overlayPanelChildSize = new ScreenOverlaySize(1.0, 1.0, ScreenOverlayUnit.Fraction, ScreenOverlayUnit.Fraction);
ScreenOverlay overlayPanelChild = new ScreenOverlay(overlayPanelChildPosition, overlayPanelChildSize)
{
    Color = Color.Green,
    Origin = ScreenOverlayOrigin.TopRight,
    BorderSize = 1
};

screenOverlay.Overlays.Add(overlayPanelChild);
SceneManager.ScreenOverlays.Add(screenOverlay);
Screen Overlay Padding

If a parent overlay contains an overlay that is positioned and sized in such a way that it extends past the bounds of the parent, the protruding portions of the child overlay will be clipped during rendering.

C#
TextureScreenOverlay secondChildOverlay = new TextureScreenOverlay(0.0, 0.0, 128.0, 128.0)
{
    Origin = ScreenOverlayOrigin.TopRight,
    TranslationX = -36.0,
    TranslationY = -18.0,
    Texture = SceneManager.Textures.FromUri(textureUri)
};
Screen Overlay Clipping Enabled

To prevent clipping a child overlay, set the overlay's ClipToParent property to false.

C#
TextureScreenOverlay secondChildOverlay = new TextureScreenOverlay(0.0, 0.0, 128.0, 128.0)
{
    Origin = ScreenOverlayOrigin.TopRight,
    TranslationX = -36.0,
    TranslationY = -18.0,
    ClipToParent = false,
    Texture = SceneManager.Textures.FromUri(textureUri)
};
Screen Overlay Clipping Disabled
Picking

The PickScreenOverlays method returns information about the screen overlays that are at a specified pixel. The inputs are X and Y coordinates. The origin is the top, left corner of the control. In most cases, the input will be the location of the mouse cursor at the time of click or other event.

Because multiple overlapping screen overlays might exist at a specified pixel, PickScreenOverlays returns a collection of ScreenOverlayPickResults, each representing one picked overlay. The picked overlays are sorted by their Z-order, so the top-most overlay is first in the list. In addition to identifying the picked overlay, each ScreenOverlayPickResult also contains the picked Position within the overlay.

C#
Collection<ScreenOverlayPickResult> collection = Scene.PickScreenOverlays(x, y);
if (collection.Count != 0)
{
    ScreenOverlayPickResult pickResult = collection[0];
    ScreenOverlay overlay = pickResult.Overlay;
    ScreenOverlayPoint overlayLocation = pickResult.Position;
    ScreenOverlayPoint screenLocation = pickResult.ControlPosition;
}

It is sometimes useful when building UI elements with screen overlays to disable picking on a certain overlay. If an overlay's PickingEnabled property is set to false, PickScreenOverlays will ignore that overlay even if it exists at the specified location.

C#
Collection<ScreenOverlayPickResult> collection = Scene.PickScreenOverlays(x, y);
if (collection.Count != 0)
{
    ScreenOverlayPickResult pickResult = collection[0];
    ScreenOverlay overlay = pickResult.Overlay;
    overlay.PickingEnabled = false;
}
// Collection will not contain the overlay that was picked above
collection = Scene.PickScreenOverlays(x, y);