Texture overlays are used to render textures in 2D screen-space on top of a 3D scene. Common use cases include displaying a company logo, a UI button, or a video. In addition to introducing the texture overlay, this topic introduces major concepts applicable to all overlays.

To display an overlay, first create and initialize it, then add it to the overlay manager, and finally explicitly redraw the scene or all scenes. This process is similar to adding a primitive to the primitive manager. The following example renders a texture overlay in the bottom, left corner of the screen.

CopyC#

IAgGxOverlayTexture overlay = new AgGxOverlayTexture();
overlay.Initialize(128, AgGxUnit.UnitPixels, 128, AgGxUnit.UnitPixels);
overlay.Texture = sceneManager.Textures.LoadFromURI("file:///C:/Insight3D.png");

sceneManager.Overlays.Add(overlay);
sceneManager.DrawAllScenes();

Once the overlay is created, it is initialized with a width and height of 128 pixels (the above screen shot was resized smaller). By default, the overlay's Position is (0, 0) and its Anchor is AnchorStyleBottomLeft, so the overlay is located in the bottom, left corner of the screen.

Next, the overlay is assigned a texture loaded from a .png file. As with all textures, the texture can also be created from an image conditioned with the imaging framework or a dynamic image to render a video using the texture overlay.

Finally, the overlay is added to the overlay manager so it will be rendered next time the scene is redrawn. This is done explicitly with the call to DrawAllScenes. For best performance, add all your overlays, primitives, and globe inlays then only explicitly redraw the scene once.

When an overlay no longer be rendered, remove it from the overlay manager or set its translucency to 100:

CopyC#

sceneManager.Overlays.Remove(overlay);

In the above example, the overlay's width and height are defined in pixels. If the window resizes, the 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 changes size, the overlay adjusts itself accordingly.

When an overlay is added directly to the overlay manager, its parent is the window itself. See the panel overlay overview for how to make a panel an overlay's parent.

The percentage is a double in the range [0.0, 1.0], where 1.0 is 100%. If the texture overlay in the above example was initialized with the fractional units shown in the following Initialize call, the overlay would consume 50% of the window in both the x and y directions.

CopyC#

overlay.Initialize(0.5, AgGxUnit.UnitFraction, 0.5, AgGxUnit.UnitFraction);

In addition to size, an overlay's Position can also be defined in fractional units. The following SetWithUnits example moves the overlay so its left origin is 50% along the x direction and its bottom origin is 25% along the y direction.

CopyC#

overlay.Position.SetWithUnits(0.5, AgGxUnit.UnitFraction, 0.25, AgGxUnit.UnitFraction);

An overlay's size can be changed after initialization using its Size property. A minimum and maximum size can also be set using the MinimumSize and MaximumSize properties, which is useful during transformations. The following example shrinks the overlay from 50% in each direction down to 25%.

CopyC#

overlay.Size.SetWithUnits(0.25, AgGxUnit.UnitFraction, 0.25, AgGxUnit.UnitFraction);

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.

An overlay's Anchor property defines how the overlay is positioned relative to its parent, and the direction of its x and y axes. The default is AnchorStyleBottomLeft. 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 anchor styles are available, such as the ones shown in the example below.

CopyC#

IAgGxOverlayTexture bottomLeft = new AgGxOverlayTexture();
bottomLeft.Initialize(120, AgGxUnit.UnitPixels, 80, AgGxUnit.UnitPixels);
bottomLeft.Texture = sceneManager.Textures.LoadFromURI("file:///C:/BottomLeft.png");
bottomLeft.Anchor = AgGxAnchorStyle.AnchorStyleBottomLeft;
sceneManager.Overlays.Add(bottomLeft);

IAgGxOverlayTexture bottomRight = new AgGxOverlayTexture();
bottomRight.Initialize(120, AgGxUnit.UnitPixels, 80, AgGxUnit.UnitPixels);
bottomRight.Texture = sceneManager.Textures.LoadFromURI("file:///C:/BottomRight.png");
bottomRight.Anchor = AgGxAnchorStyle.AnchorStyleBottomRight;
sceneManager.Overlays.Add(bottomRight);

IAgGxOverlayTexture topRight = new AgGxOverlayTexture();
topRight.Initialize(120, AgGxUnit.UnitPixels, 80, AgGxUnit.UnitPixels);
topRight.Texture = sceneManager.Textures.LoadFromURI("file:///C:/TopRight.png");
topRight.Anchor = AgGxAnchorStyle.AnchorStyleTopRight;
sceneManager.Overlays.Add(topRight);

IAgGxOverlayTexture topLeft = new AgGxOverlayTexture();
topLeft.Initialize(120, AgGxUnit.UnitPixels, 80, AgGxUnit.UnitPixels);
topLeft.Texture = sceneManager.Textures.LoadFromURI("file:///C:/TopLeft.png");
topLeft.Anchor = AgGxAnchorStyle.AnchorStyleTopLeft;
sceneManager.Overlays.Add(topLeft);

sceneManager.DrawAllScenes();

In addition to positioning and sizing an overlay with its Position and Size properties, you can apply transformations to an overlay to modify its position, size, or orientation.

SetTranslation is 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 anchor style. For example, when the anchor style is AnchorStyleBottomLeft, a translation of (50, 50) moves the overlay 50 pixels to the right and 50 pixels up. When the anchor style is AnchorStyleTopRight, the same translation moves the overlay 50 pixels to the left and 50 pixels down. This is shown in the following example.

CopyC#

IAgGxOverlayTexture bottomLeft = new AgGxOverlayTexture();
bottomLeft.Initialize(101, AgGxUnit.UnitPixels, 81, AgGxUnit.UnitPixels);
bottomLeft.Texture = sceneManager.Textures.LoadFromURI("file:///C:/logo.png");
bottomLeft.Anchor = AgGxAnchorStyle.AnchorStyleBottomLeft;
bottomLeft.SetTranslation(50, 50);
bottomLeft.Translucency = 30;
sceneManager.Overlays.Add(bottomLeft);

IAgGxOverlayTexture topRight = new AgGxOverlayTexture();
topRight.Initialize(101, AgGxUnit.UnitPixels, 81, AgGxUnit.UnitPixels);
topRight.Texture = sceneManager.Textures.LoadFromURI("file:///C:/logo.png");
topRight.Anchor = AgGxAnchorStyle.AnchorStyleTopRight;
topRight.SetTranslation(50, 50);
topRight.Translucency = 30;
sceneManager.Overlays.Add(topRight);

sceneManager.DrawAllScenes();

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

CopyC#

bottomLeft.Scale = 2.0;
topRight.Scale = 0.5;

RotationXY defines the rotation transformation applied to the overlay. The angle is defined in radians. Positive angles rotate counter-clockwise. The following example shows an overlay rotated counter-clockwise 60 degrees.

CopyC#

IAgGxOverlayTexture bottomLeft = new AgGxOverlayTexture();
bottomLeft.Initialize(101, AgGxUnit.UnitPixels, 81, AgGxUnit.UnitPixels);
bottomLeft.Texture = sceneManager.Textures.LoadFromURI("file:///C:/logo.png");
bottomLeft.Anchor = AgGxAnchorStyle.AnchorStyleCenter;
bottomLeft.RotationXY = Trig.DegreesToRadians(60.0);
bottomLeft.Translucency = 30;
sceneManager.Overlays.Add(bottomLeft);

When multiple overlays overlap each order, use BringToFront and SendToBack to control which overlays are rendered in which order. If several overlays are in the overlay manager, use BringToFront to make sure an overlay is rendered on top of the others. The following example creates three overlays and ensures that the first one created is rendered on top of the other two.

CopyC#

IAgGxOverlayTexture top = new AgGxOverlayTexture();
top.Initialize(101, AgGxUnit.UnitPixels, 81, AgGxUnit.UnitPixels);
top.Texture = sceneManager.Textures.LoadFromURI("file:///C:/logo.png");
top.Anchor = AgGxAnchorStyle.AnchorStyleCenter;
top.Translucency = 30;
sceneManager.Overlays.Add(top);

IAgGxOverlayTexture left = new AgGxOverlayTexture();
left.Initialize(128, AgGxUnit.UnitPixels, 128, AgGxUnit.UnitPixels);
left.Texture = sceneManager.Textures.LoadFromURI("file:///C:/Insight3D.png");
left.Anchor = AgGxAnchorStyle.AnchorStyleCenter;
left.SetTranslation(-64, 0);
sceneManager.Overlays.Add(left);

IAgGxOverlayTexture right = new AgGxOverlayTexture();
right.Initialize(128, AgGxUnit.UnitPixels, 128, AgGxUnit.UnitPixels);
right.Texture = sceneManager.Textures.LoadFromURI("file:///C:/Insight3D.png");
right.Anchor = AgGxAnchorStyle.AnchorStyleCenter;
right.SetTranslation(64, 0);
sceneManager.Overlays.Add(right);

top.BringToFront();

Z-order is defined per parent, which is important when panel overlays are used.

A border can be rendered around an overlay's bounds using 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.

CopyC#

IAgGxOverlayTexture overlay = new AgGxOverlayTexture();
overlay.Initialize(101, AgGxUnit.UnitPixels, 81, AgGxUnit.UnitPixels);
overlay.Texture = sceneManager.Textures.LoadFromURI("file:///C:/logo.png");
overlay.Anchor = AgGxAnchorStyle.AnchorStyleCenter;
overlay.Translucency = 30;
overlay.BorderSize = 2;
overlay.BorderColor = (uint)ColorTranslator.ToOle(Color.Red);
overlay.BorderTranslucency = 20;
sceneManager.Overlays.Add(overlay);

When picking, it can be useful to know an overlay's bounds in screen coordinates. The ScreenPosition, ScreenSize, and ScreenBounds properties provide this functionality. In the example below, a border is rendered around the bounding rectangle of the panel overlay. The OverlayToolbar type referenced below can be found in the picking section of the HowTo example application.

CopyC#

OverlayToolbar overlayToolbar = new OverlayToolbar();
IAgGxOverlayPanel toolbarPanel = overlayToolbar.Overlay;
toolbarPanel.Scale = 1.5;
toolbarPanel.Anchor = AGI.Graphics.Overlays.AgGxAnchorStyle.AnchorStyleBottomCenter;
toolbarPanel.RotationXY = Trig.DegreesToRadians(-45);
toolbarPanel.YTranslation = 200;

IAgGxOverlayTexture screenBounds = new AgGxOverlayTexture();
screenBounds.BorderSize = 2;
screenBounds.BorderColor = (uint)System.Drawing.ColorTranslator.ToOle(
    System.Drawing.Color.Red);
screenBounds.Translucency = 90;
screenBounds.Size.Set(overlayToolbar.Overlay.ScreenSize.Width,
    overlayToolbar.Overlay.ScreenSize.Height);
screenBounds.Position.Set(overlayToolbar.Overlay.ScreenPosition.X,
    overlayToolbar.Overlay.ScreenPosition.Y);

sceneManager.Overlays.Add(screenBounds);

It is also possible to convert between a screen coordinate and an overlays coordinate, and vice versa, using the PointToOverlay and PointToScreen methods. Below, a coordinate relative to an overlay is translated into its screen coordinate, and then back into the overlays coordinates.

CopyC#

IAgGxOverlayTexture overlay = new AgGxOverlayTexture();
overlay.Initialize(200, AgGxUnit.UnitPixels, 200, AgGxUnit.UnitPixels);
overlay.Position.Set(100, 100);
sceneManager.Overlays.Add(overlay);

IAgGxOverlayConstantPoint screenPoint = overlay.PointToScreen(100, 100);
// 200, 200
Console.WriteLine(screenPoint.X.ToString() + ", " + screenPoint.Y.ToString());
IAgGxOverlayConstantPoint overlayPoint = overlay.PointToOverlay(
    (int)screenPoint.X, (int)screenPoint.Y);
// 100, 100
Console.WriteLine(overlayPoint.X.ToString() + ", " + overlayPoint.Y.ToString());