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.

The following topics are covered in this section:

Topic Description
Basics It takes only a few lines of code to display a basic static texture, such as a company logo, on the screen.
Units An overlay's position and size can be defined in absolute pixel units or in fractional units.
Origin The origin of a screen overlay defines how it is positioned relative to its parent, and the direction of its x and y axes.
Pinning An overlay can specify a pinning position, which defines the point on the overlay that will correspond to the overlay's position on its parent.
Transformations Screen overlays support translation, scale, rotation, and flip transformations.
Z-Order When multiple screen overlays overlap each other, the user can define the order in which they are rendered.
Borders A border can be rendered around a screen overlay.
Control Coordinates A screen overlay's position and size are defined relative to its parent but can be converted to the overall coordinate system of the globe control control.
Nesting Overlays Screen overlays can be nested inside other screen overlays.
Picking Picking allows users to select and interact with overlays on the screen, and can be used to create interactive UI elements.

Basics

The TextureScreenOverlay class 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#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsScreenOverlayCollectionBase overlayManager = (IAgStkGraphicsScreenOverlayCollectionBase)manager.ScreenOverlays.Overlays;

IAgStkGraphicsTextureScreenOverlay overlay = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 128, 128);
overlay.Texture = manager.Textures.LoadFromStringUri(imageFile);

overlayManager.Add((IAgStkGraphicsScreenOverlay)overlay);
scene.Render();

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. Next, a texture is loaded from a PNG file and assigned to the overlay's Texture property. Finally, the overlay is added to the SceneManager's ScreenOverlays collection and all scenes are rendered by calling SceneManager.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 STK Engine'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, SceneManager.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#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsScreenOverlayCollectionBase overlayManager = (IAgStkGraphicsScreenOverlayCollectionBase)manager.ScreenOverlays.Overlays;
overlayManager.Remove((IAgStkGraphicsScreenOverlay)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 SceneManager's ScreenOverlays collection (the 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#] Copy Code
Array position = new object[]
{
     0.25,
     0.25,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction
};

Array size = new object[]
{
     0.5,
     0.5,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction
};

manager.Initializers.TextureScreenOverlay.InitializeWithPositionSize(ref position, ref size);

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#] Copy Code
Array newPosition = new object[]
{
     0.5,
     0.25,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction
};
((IAgStkGraphicsOverlay)overlay).Position = newPosition;

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 MinimumSize or MaximumSize limits. 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#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsScreenOverlayCollectionBase overlayManager = (IAgStkGraphicsScreenOverlayCollectionBase)manager.ScreenOverlays.Overlays;

IAgStkGraphicsTextureScreenOverlay bottomLeft = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 120, 80);
bottomLeft.Texture = manager.Textures.LoadFromStringUri(bottomLeftImageFile);
((IAgStkGraphicsOverlay)bottomLeft).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginBottomLeft;
overlayManager.Add((IAgStkGraphicsScreenOverlay)bottomLeft);

IAgStkGraphicsTextureScreenOverlay bottomRight = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 120, 80);
bottomRight.Texture = manager.Textures.LoadFromStringUri(bottomRightImageFile);
((IAgStkGraphicsOverlay)bottomRight).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginBottomRight;
overlayManager.Add((IAgStkGraphicsScreenOverlay)bottomRight);

IAgStkGraphicsTextureScreenOverlay topRight = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 120, 80);
topRight.Texture = manager.Textures.LoadFromStringUri(topRightImageFile);
((IAgStkGraphicsOverlay)topRight).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginTopRight;
overlayManager.Add((IAgStkGraphicsScreenOverlay)topRight);

IAgStkGraphicsTextureScreenOverlay topLeft = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 120, 80);
topLeft.Texture = manager.Textures.LoadFromStringUri(topLeftImageFile);
((IAgStkGraphicsOverlay)topLeft).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginTopLeft;
overlayManager.Add((IAgStkGraphicsScreenOverlay)topLeft);

scene.Render();

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 property 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#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsScreenOverlayCollectionBase overlayManager = (IAgStkGraphicsScreenOverlayCollectionBase)manager.ScreenOverlays.Overlays;

IAgStkGraphicsTextureScreenOverlay overlay = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(200, 200, 200, 200);
((IAgStkGraphicsOverlay)overlay).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginBottomLeft;
((IAgStkGraphicsOverlay)overlay).Color = Color.LightBlue;
((IAgStkGraphicsOverlay)overlay).Translucency = .4f;

Array position = new object[]
{
     50,
     50,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitPixels,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitPixels
};

((IAgStkGraphicsOverlay)overlay).PinningPosition = position;
((IAgStkGraphicsOverlay)overlay).PinningOrigin = AgEStkGraphicsScreenOverlayPinningOrigin.eStkGraphicsScreenOverlayPinningOriginTopRight;
overlayManager.Add((IAgStkGraphicsScreenOverlay)overlay);

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#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsScreenOverlayCollectionBase overlayManager = (IAgStkGraphicsScreenOverlayCollectionBase)manager.ScreenOverlays.Overlays;

IAgStkGraphicsTextureScreenOverlay bottomLeft = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 101, 81);
bottomLeft.Texture = manager.Textures.LoadFromStringUri(imageFile);
((IAgStkGraphicsOverlay)bottomLeft).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginBottomLeft;
((IAgStkGraphicsOverlay)bottomLeft).TranslationX = 50;
((IAgStkGraphicsOverlay)bottomLeft).TranslationY = 50;
((IAgStkGraphicsOverlay)bottomLeft).Translucency = 0.3f;
overlayManager.Add((IAgStkGraphicsScreenOverlay)bottomLeft);

IAgStkGraphicsTextureScreenOverlay topRight = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 101, 81);
topRight.Texture = manager.Textures.LoadFromStringUri(imageFile);
((IAgStkGraphicsOverlay)topRight).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginTopRight;
((IAgStkGraphicsOverlay)topRight).TranslationX = 50;
((IAgStkGraphicsOverlay)topRight).TranslationY = 50;
((IAgStkGraphicsOverlay)topRight).Translucency = 0.3f;
overlayManager.Add((IAgStkGraphicsScreenOverlay)topRight);

scene.Render();

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 of less than 1.0 will shrink the overlay, while a Scale greater than 1.0 will enlarge it, as shown below.

[C#] Copy Code
((IAgStkGraphicsOverlay)bottomLeft).Scale = 2.0;
((IAgStkGraphicsOverlay)topRight).Scale = 0.5;

RotationAngle defines the rotation transformation applied to the overlay. The angle is defined in radians; 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#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsScreenOverlayCollectionBase overlayManager = (IAgStkGraphicsScreenOverlayCollectionBase)manager.ScreenOverlays.Overlays;

IAgStkGraphicsTextureScreenOverlay bottomLeft = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 101, 81);
bottomLeft.Texture = manager.Textures.LoadFromStringUri(imageFile);
((IAgStkGraphicsOverlay)bottomLeft).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginCenter;
((IAgStkGraphicsOverlay)bottomLeft).RotationAngle = 60.0;
((IAgStkGraphicsOverlay)bottomLeft).Translucency = 0.3f;
overlayManager.Add((IAgStkGraphicsScreenOverlay)bottomLeft);

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 BringToFront and SendToBack 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#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsScreenOverlayCollectionBase overlayManager = (IAgStkGraphicsScreenOverlayCollectionBase)manager.ScreenOverlays.Overlays;

IAgStkGraphicsTextureScreenOverlay top = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 101, 81);
top.Texture = manager.Textures.LoadFromStringUri(topImageFile);
((IAgStkGraphicsOverlay)top).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginCenter;
((IAgStkGraphicsOverlay)top).Translucency = 0.3f;
overlayManager.Add((IAgStkGraphicsScreenOverlay)top);

IAgStkGraphicsTextureScreenOverlay left = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 128, 128);
left.Texture = manager.Textures.LoadFromStringUri(leftImageFile);
((IAgStkGraphicsOverlay)left).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginCenter;
((IAgStkGraphicsOverlay)left).TranslationX = -64;
((IAgStkGraphicsOverlay)left).TranslationY = 0;
overlayManager.Add((IAgStkGraphicsScreenOverlay)left);

IAgStkGraphicsTextureScreenOverlay right = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 128, 128);
right.Texture = manager.Textures.LoadFromStringUri(rightImageFile);
((IAgStkGraphicsOverlay)right).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginCenter;
((IAgStkGraphicsOverlay)left).TranslationX = 64;
((IAgStkGraphicsOverlay)left).TranslationY = 0;
overlayManager.Add((IAgStkGraphicsScreenOverlay)right);

((IAgStkGraphicsOverlay)top).BringToFront();

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#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsScreenOverlayCollectionBase overlayManager = (IAgStkGraphicsScreenOverlayCollectionBase)manager.ScreenOverlays.Overlays;

IAgStkGraphicsTextureScreenOverlay overlay = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 101, 81);
overlay.Texture = manager.Textures.LoadFromStringUri(imageFile);
((IAgStkGraphicsOverlay)overlay).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginCenter;
((IAgStkGraphicsOverlay)overlay).Translucency = 0.3f;
((IAgStkGraphicsOverlay)overlay).BorderSize = 2;
((IAgStkGraphicsOverlay)overlay).BorderColor = Color.Red;
((IAgStkGraphicsOverlay)overlay).BorderTranslucency = 0.2f;
overlayManager.Add((IAgStkGraphicsScreenOverlay)overlay);

Control Coordinates

When picking, it can be useful to know a screen overlay's bounds relative to the overall globe control rather than relative to its parent. The ControlPosition, ControlSize, and ControlBounds properties provide this functionality.

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#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsScreenOverlayCollectionBase overlayManager = (IAgStkGraphicsScreenOverlayCollectionBase)manager.ScreenOverlays.Overlays;

IAgStkGraphicsTextureScreenOverlay overlay = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(100, 100, 200, 200);
overlayManager.Add((IAgStkGraphicsScreenOverlay)overlay);

Array controlPosition = ((IAgStkGraphicsOverlay)overlay).OverlayToControl(100, 100);
Console.WriteLine(controlPosition.GetValue(0) + ", " + controlPosition.GetValue(1));
// => 200, 200

Array overlayPosition = ((IAgStkGraphicsOverlay)overlay).ControlToOverlay(controlPosition.GetValue(0), controlPosition.GetValue(1));
Console.WriteLine(overlayPosition.GetValue(0) + ", " + overlayPosition.GetValue(1));
// => 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#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsScreenOverlayCollectionBase overlayManager = (IAgStkGraphicsScreenOverlayCollectionBase)manager.ScreenOverlays.Overlays;

IAgStkGraphicsTextureScreenOverlay overlay = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(10, 10, 200, 200);
((IAgStkGraphicsOverlay)overlay).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginTopRight;
((IAgStkGraphicsOverlay)overlay).Color = Color.LightSteelBlue;
((IAgStkGraphicsOverlay)overlay).BorderSize = 1;

Array position = new object[]
{
     0,
     0,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitPixels,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitPixels
};
Array size = new object[]
{
     .5,
     .5,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction
};
IAgStkGraphicsTextureScreenOverlay childPanel = manager.Initializers.TextureScreenOverlay.InitializeWithPositionSize(ref position, ref size);
((IAgStkGraphicsOverlay)childPanel).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginCenter;
((IAgStkGraphicsOverlay)childPanel).Color = Color.SteelBlue;
((IAgStkGraphicsOverlay)childPanel).BorderSize = 1;

position = new object[]
{
     0,
     0,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitPixels,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitPixels
};
size = new object[]
{
     .5,
     .5,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction
};
IAgStkGraphicsTextureScreenOverlay childPanelChild = manager.Initializers.TextureScreenOverlay.InitializeWithPositionSize(ref position, ref size);
((IAgStkGraphicsOverlay)childPanelChild).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginBottomRight;
((IAgStkGraphicsOverlay)childPanelChild).Color = Color.Green;
((IAgStkGraphicsOverlay)childPanelChild).BorderSize = 1;

((IAgStkGraphicsScreenOverlayCollectionBase)((IAgStkGraphicsOverlay)childPanel).Overlays).Add((IAgStkGraphicsScreenOverlay)childPanelChild);
((IAgStkGraphicsScreenOverlayCollectionBase)((IAgStkGraphicsOverlay)overlay).Overlays).Add((IAgStkGraphicsScreenOverlay)childPanel);
overlayManager.Add((IAgStkGraphicsScreenOverlay)overlay);

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 by the Parent property. The ScreenOverlayContainer interface is implemented by both the overlay manager and overlay panels, and can be cast to the appropriate interface, as seen below.

[C#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsScreenOverlayCollectionBase overlayManager = (IAgStkGraphicsScreenOverlayCollectionBase)manager.ScreenOverlays.Overlays;

IAgStkGraphicsTextureScreenOverlay overlay = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 200, 200);

Array position = new object[]
{
     0,
     0,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitPixels,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitPixels
};
Array size = new object[]
{
     .5,
     .5,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction
};
IAgStkGraphicsTextureScreenOverlay childOverlay = manager.Initializers.TextureScreenOverlay.InitializeWithPositionSize(ref position, ref size);

((IAgStkGraphicsScreenOverlayCollectionBase)((IAgStkGraphicsOverlay)overlay).Overlays).Add((IAgStkGraphicsScreenOverlay)childOverlay);
overlayManager.Add((IAgStkGraphicsScreenOverlay)overlay);

IAgStkGraphicsScreenOverlayContainer panel = ((IAgStkGraphicsOverlay)childOverlay).Parent;
overlayManager = ((IAgStkGraphicsOverlay)((IAgStkGraphicsScreenOverlayCollectionBase)((IAgStkGraphicsOverlay)panel).Overlays)[0]).Parent as IAgStkGraphicsScreenOverlayCollectionBase;

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#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsScreenOverlayManager ScreenOverlayManager = manager.ScreenOverlays;
IAgStkGraphicsScreenOverlayCollectionBase overlayManager = (IAgStkGraphicsScreenOverlayCollectionBase)manager.ScreenOverlays.Overlays;

Array padding = new object[]
{
     10,
     10,
     10,
     10
};
ScreenOverlayManager.Padding = padding;
IAgStkGraphicsTextureScreenOverlay overlay = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 200, 200);

((IAgStkGraphicsOverlay)overlay).Padding = padding;
((IAgStkGraphicsOverlay)overlay).Color = Color.LightSteelBlue;
((IAgStkGraphicsOverlay)overlay).BorderSize = 1;

Array position = new object[]
{
     0,
     0,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitPixels,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitPixels
};
Array size = new object[]
{
     1,
     1,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction,
     AgEStkGraphicsScreenOverlayUnit.eStkGraphicsScreenOverlayUnitFraction
};
IAgStkGraphicsTextureScreenOverlay overlayPanelChild = manager.Initializers.TextureScreenOverlay.InitializeWithPositionSize(ref position, ref size);
((IAgStkGraphicsOverlay)overlayPanelChild).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginTopRight;
((IAgStkGraphicsOverlay)overlayPanelChild).Color = Color.Green;
((IAgStkGraphicsOverlay)overlayPanelChild).BorderSize = 1;

((IAgStkGraphicsScreenOverlayCollectionBase)((IAgStkGraphicsOverlay)overlay).Overlays).Add((IAgStkGraphicsScreenOverlay)overlayPanelChild);
overlayManager.Add((IAgStkGraphicsScreenOverlay)overlay);

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#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;

IAgStkGraphicsTextureScreenOverlay overlay = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 128, 128);
overlay.Texture = manager.Textures.LoadFromStringUri(imageFile);
((IAgStkGraphicsOverlay)overlay).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginTopRight;
((IAgStkGraphicsOverlay)overlay).TranslationX = -36;
((IAgStkGraphicsOverlay)overlay).TranslationY = -18;

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

[C#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;

IAgStkGraphicsTextureScreenOverlay overlay = manager.Initializers.TextureScreenOverlay.InitializeWithXYWidthHeight(0, 0, 128, 128);
overlay.Texture = manager.Textures.LoadFromStringUri(imageFile);
((IAgStkGraphicsOverlay)overlay).Origin = AgEStkGraphicsScreenOverlayOrigin.eStkGraphicsScreenOverlayOriginTopRight;
((IAgStkGraphicsOverlay)overlay).TranslationX = -36;
((IAgStkGraphicsOverlay)overlay).TranslationY = -18;
((IAgStkGraphicsOverlay)overlay).ClipToParent = false;

Picking

The Scene.PickScreenOverlays method returns information about the screen overlays that are at a specified pixel. The input is an x and y coordinate. The origin is the top, left corner of the 3D 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, Scene.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#] Copy Code
IAgStkGraphicsScreenOverlayPickResultCollection picked = null;
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
if (manager.Scenes.Count > 0)
{
     picked = manager.Scenes[0].PickScreenOverlays(x, y);
     if (picked.Count != 0)
     {
          IAgStkGraphicsScreenOverlayPickResult result = picked[0];
          IAgStkGraphicsOverlay overlay = result.Overlay as IAgStkGraphicsOverlay;
          Array position = result.Position;
          Array.controlPosition = result.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, Scene.PickScreenOverlays will not return the overlay even if it exists at the specified location.

[C#] Copy Code
IAgStkGraphicsScreenOverlayPickResultCollection picked = null;
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
if (manager.Scenes.Count > 0)
{
     picked = manager.Scenes[0].PickScreenOverlays(x, y);
     if (picked.Count != 0)
     {
          IAgStkGraphicsScreenOverlayPickResult result = picked[0];
          IAgStkGraphicsOverlay overlay = result.Overlay as IAgStkGraphicsOverlay;
          overlay.PickingEnabled = false;
     }
}
// Collection will not contain the overlay that was picked above
picked = manager.Scenes[0].PickScreenOverlays(x, y);

STK Engine for UNIX 11.2