C# Class Axiom.Overlays.Overlay

Represents a layer which is rendered on top of the 'normal' scene contents.
An overlay is a container for visual components (2D and 3D) which will be rendered after the main scene in order to composite heads-up-displays, menus or other layers on top of the contents of the scene.

An overlay always takes up the entire size of the viewport, although the components attached to it do not have to. An overlay has no visual element in itself, it it merely a container for visual elements.

Overlays are created by calling SceneManager.CreateOverlay, or by defining them in special text scripts (.overlay files). As many overlays as you like can be defined; after creation an overlay is hidden i.e. not visible until you specifically enable it by calling Show(). This allows you to have multiple overlays predefined (menus etc) which you make visible only when you want. It is possible to have multiple overlays enabled at once; in this case the relative ZOrder parameter of the overlays determine which one is displayed on top.

By default overlays are rendered into all viewports. This is fine when you only have fullscreen viewports, but if you have picture-in-picture views, you probably don't want the overlay displayed in the smaller viewports. You turn this off for a specific viewport by calling the Viewport.DisplayOverlays property.

Inheritance: Axiom.Core.Resource
Show file Open project: WolfgangSt/axiom Class Usage Examples

Protected Properties

Property Type Description
elementList List
elementLookup OverlayElementContainer>.Dictionary
isInitialised bool
isTransformOutOfDate bool
isTransformUpdated bool
isVisible bool
origin string
rootNode Axiom.Core.SceneNode
rotate float
scaleX float
scrollX float
transform Axiom.Math.Matrix4
xform Axiom.Math.Matrix4[]
zOrder int

Public Methods

Method Description
AddElement ( OverlayElementContainer element ) : void

Adds a 2d element to this overlay.

Containers are created and managed using the OverlayManager. A container could be as simple as a square panel, or something more complex like a grid or tree view. Containers group collections of other elements, giving them a relative coordinate space and a common z-order. If you want to attach a gui widget to an overlay, you have to do it via a container.

AddElement ( SceneNode node ) : void

Adds a node capable of holding 3D objects to the overlay.

Although overlays are traditionally associated with 2D elements, there are reasons why you might want to attach 3D elements to the overlay too. For example, if you wanted to have a 3D cockpit, which was overlaid with a HUD, then you would create 2 overlays, one with a 3D object attached for the cockpit, and one with the HUD elements attached (the zorder of the HUD overlay would be higher than the cockpit to ensure it was always on top).

A SceneNode can have any number of 3D objects attached to it. SceneNodes are created using SceneManager.CreateSceneNode, and are normally attached (directly or indirectly) to the root node of the scene. By attaching them to an overlay, you indicate that:

  1. You want the contents of this node to only appear when the overlay is active
  2. You want the node to inherit a coordinate space relative to the camera, rather than relative to the root scene node
  3. You want these objects to be rendered after the contents of the main scene to ensure they are rendered on top
One major consideration when using 3D objects in overlays is the behavior of the depth buffer. Overlays are rendered with depth checking off, to ensure that their contents are always displayed on top of the main scene (to do otherwise would result in objects 'poking through' the overlay). The problem with using 3D objects is that if they are concave, or self-overlap, then you can get artifacts because of the lack of depth buffer checking. So you should ensure that any 3D objects you us in the overlay are convex and don't overlap each other. If they must overlap, split them up and put them in 2 overlays.
Clear ( ) : void

Clears the overlay of all attached items.
FindElementAt ( float x, float y ) : OverlayElement

This returns a OverlayElement at position x,y.
FindVisibleObjects ( Camera camera, RenderQueue queue ) : void

Internal method to put the overlay contents onto the render queue.
GetChild ( string name ) : OverlayElementContainer

Gets a child container of this overlay by name.
GetWorldOrientation ( ) : Quaternion
GetWorldPosition ( ) : Vector3
GetWorldTransforms ( Matrix4 xform ) : void

Used to transform the overlay when scrolling, scaling etc.
Hide ( ) : void

Hides this overlay if it is currently being displayed.
RemoveElement ( OverlayElementContainer element ) : void

Removes a 2D container from the overlay.

Consider using Hide.

RemoveElement ( SceneNode node ) : void

Removes a 3D element from the overlay.
RemoveElement ( string name ) : void

Removes a 2D container from the overlay.

Consider using Hide.

Rotate ( float degrees ) : void

Adds the passed in angle to the rotation applied to this overlay.
Scroll ( float xOffset, float yOffset ) : void

Scrolls the overlay by the offsets provided.

This method moves the overlay by the amounts provided. As with other methods on this object, a full screen width / height is represented by the value 1.0.

SetScale ( float x, float y ) : void

Sets the scaling factor of this overlay.

You can use this to set an scale factor to be used to zoom an overlay.

SetScroll ( float x, float y ) : void

Sets the scrolling factor of this overlay.

You can use this to set an offset to be used to scroll an overlay around the screen.

Show ( ) : void

Shows this overlay if it is not already visible.

Protected Methods

Method Description
AssignZOrders ( ) : void

Updates container elements' Z-ordering
Initialize ( ) : void
UpdateTransforms ( ) : void

Internal lazy update method.
load ( ) : void

unload ( ) : void

Private Methods

Method Description
Overlay ( string name ) : System

Constructor: do not call direct, use SceneManager.CreateOverlay

Method Details

AddElement() public method

Adds a 2d element to this overlay.
Containers are created and managed using the OverlayManager. A container could be as simple as a square panel, or something more complex like a grid or tree view. Containers group collections of other elements, giving them a relative coordinate space and a common z-order. If you want to attach a gui widget to an overlay, you have to do it via a container.
public AddElement ( OverlayElementContainer element ) : void
element OverlayElementContainer
return void

AddElement() public method

Adds a node capable of holding 3D objects to the overlay.
Although overlays are traditionally associated with 2D elements, there are reasons why you might want to attach 3D elements to the overlay too. For example, if you wanted to have a 3D cockpit, which was overlaid with a HUD, then you would create 2 overlays, one with a 3D object attached for the cockpit, and one with the HUD elements attached (the zorder of the HUD overlay would be higher than the cockpit to ensure it was always on top).

A SceneNode can have any number of 3D objects attached to it. SceneNodes are created using SceneManager.CreateSceneNode, and are normally attached (directly or indirectly) to the root node of the scene. By attaching them to an overlay, you indicate that:

  1. You want the contents of this node to only appear when the overlay is active
  2. You want the node to inherit a coordinate space relative to the camera, rather than relative to the root scene node
  3. You want these objects to be rendered after the contents of the main scene to ensure they are rendered on top
One major consideration when using 3D objects in overlays is the behavior of the depth buffer. Overlays are rendered with depth checking off, to ensure that their contents are always displayed on top of the main scene (to do otherwise would result in objects 'poking through' the overlay). The problem with using 3D objects is that if they are concave, or self-overlap, then you can get artifacts because of the lack of depth buffer checking. So you should ensure that any 3D objects you us in the overlay are convex and don't overlap each other. If they must overlap, split them up and put them in 2 overlays.
public AddElement ( SceneNode node ) : void
node Axiom.Core.SceneNode
return void

AssignZOrders() protected method

Updates container elements' Z-ordering
protected AssignZOrders ( ) : void
return void

Clear() public method

Clears the overlay of all attached items.
public Clear ( ) : void
return void

FindElementAt() public method

This returns a OverlayElement at position x,y.
public FindElementAt ( float x, float y ) : OverlayElement
x float
y float
return OverlayElement

FindVisibleObjects() public method

Internal method to put the overlay contents onto the render queue.
public FindVisibleObjects ( Camera camera, RenderQueue queue ) : void
camera Axiom.Core.Camera Current camera being used in the render loop.
queue Axiom.Graphics.RenderQueue Current render queue.
return void

GetChild() public method

Gets a child container of this overlay by name.
public GetChild ( string name ) : OverlayElementContainer
name string
return OverlayElementContainer

GetWorldOrientation() public method

public GetWorldOrientation ( ) : Quaternion
return Axiom.Math.Quaternion

GetWorldPosition() public method

public GetWorldPosition ( ) : Vector3
return Vector3

GetWorldTransforms() public method

Used to transform the overlay when scrolling, scaling etc.
public GetWorldTransforms ( Matrix4 xform ) : void
xform Axiom.Math.Matrix4 Array of Matrix4s to populate with the world /// transforms of this overlay. ///
return void

Hide() public method

Hides this overlay if it is currently being displayed.
public Hide ( ) : void
return void

Initialize() protected method

protected Initialize ( ) : void
return void

RemoveElement() public method

Removes a 2D container from the overlay.
Consider using Hide.
public RemoveElement ( OverlayElementContainer element ) : void
element OverlayElementContainer
return void

RemoveElement() public method

Removes a 3D element from the overlay.
public RemoveElement ( SceneNode node ) : void
node Axiom.Core.SceneNode
return void

RemoveElement() public method

Removes a 2D container from the overlay.
Consider using Hide.
public RemoveElement ( string name ) : void
name string
return void

Rotate() public method

Adds the passed in angle to the rotation applied to this overlay.
public Rotate ( float degrees ) : void
degrees float
return void

Scroll() public method

Scrolls the overlay by the offsets provided.
This method moves the overlay by the amounts provided. As with other methods on this object, a full screen width / height is represented by the value 1.0.
public Scroll ( float xOffset, float yOffset ) : void
xOffset float
yOffset float
return void

SetScale() public method

Sets the scaling factor of this overlay.
You can use this to set an scale factor to be used to zoom an overlay.
public SetScale ( float x, float y ) : void
x float Horizontal scale value, where 1.0 = normal, 0.5 = half size etc
y float Vertical scale value, where 1.0 = normal, 0.5 = half size etc
return void

SetScroll() public method

Sets the scrolling factor of this overlay.
You can use this to set an offset to be used to scroll an overlay around the screen.
public SetScroll ( float x, float y ) : void
x float /// Horizontal scroll value, where 0 = normal, -0.5 = scroll so that only /// the right half the screen is visible etc ///
y float /// Vertical scroll value, where 0 = normal, 0.5 = scroll down by half /// a screen etc. ///
return void

Show() public method

Shows this overlay if it is not already visible.
public Show ( ) : void
return void

UpdateTransforms() protected method

Internal lazy update method.
protected UpdateTransforms ( ) : void
return void

load() protected method

protected load ( ) : void
return void

unload() protected method

protected unload ( ) : void
return void

Property Details

elementList protected property

2D element list.
protected List elementList
return List

elementLookup protected property

protected Dictionary elementLookup
return OverlayElementContainer>.Dictionary

isInitialised protected property

protected bool isInitialised
return bool

isTransformOutOfDate protected property

protected bool isTransformOutOfDate
return bool

isTransformUpdated protected property

protected bool isTransformUpdated
return bool

isVisible protected property

protected bool isVisible
return bool

origin protected property

protected string origin
return string

rootNode protected property

Internal root node, used as parent for 3D objects
protected SceneNode,Axiom.Core rootNode
return Axiom.Core.SceneNode

rotate protected property

Degrees of rotation around center.
protected float rotate
return float

scaleX protected property

Scale values.
protected float scaleX
return float

scrollX protected property

Scroll values, offsets.
protected float scrollX
return float

transform protected property

Camera relative transform.
protected Matrix4,Axiom.Math transform
return Axiom.Math.Matrix4

xform protected property

Used when passing transform to overlay elements.
protected Matrix4[],Axiom.Math xform
return Axiom.Math.Matrix4[]

zOrder protected property

protected int zOrder
return int