Overlays

The term “overlays” in HOOPS Communicator refers to rectangular areas with an associated camera that is layered on top of the main 3D scene. While overlays can contain any kind of data they are not meant to display large amounts of geometry and should not be used for example to create multiple views of a model. Instead, they are useful for displaying light-weight geometry like navigation widgets (e.g. NavCube, AxisTriad) or data associated with the main model like a legend bar.

Currently, overlays can only be created via the HOOPS Web Viewer API. They cannot be authored when creating a SC model.

Creating a new overlay

All overlays are managed by the OverlayManager. Depending on the hardware, there is a fixed amount of overlays available which are referenced by a 0-based index. To find out the number of available overlays you can use the maxIndex() function.

Result: 7

Setting the viewport

You don’t need to do anything special to create a new overlay. Instead, you can just start using any of the available overlays by setting a viewport and then attaching geometry and a camera to it.

The setViewport() function above sets overlay #0 to the new viewport.

There are various options to define the size and location of the viewport using the aforementioned function: its second parameter specifies the “anchor” position of the Overlay which specifies what its position is relative to. The Unit parameter then lets you define the Units of the size and position values.

In the above example, we have created the overlay with a viewport that is 10 pixels offset horizontally and vertically from the upper right corner of the screen and has a width and height of 100 pixels.

For more information on the various parameters of setViewport() navigate to the following page.

../../../_images/overlays_microengine_viewport.png

A simple overlay inserted with the Viewport specified above.

Assigning geometry

To make an overlay useful, you need to assign it geometry to render. Call the addNodes() function with an array of NodeIds containing the geometry you want to place into the overlay:

The code above places all geometry into a single node inside overlay #0.

Assigning a camera

Just like the main scene each active overlay needs to have a camera which defines from where the geometry it contains will be rendered. To assign a camera to an overlay simple create a new Camera object and use the setCamera() function.

The above code creates an orthographic camera pointing to the origin and assigns it to overlay #0.

Complete example

Below is a complete example that demonstrates how to create an overlay with a simple X/Y/Z AxisTriad at the top right of the screen.

Selection

You can determine if a selection occurred inside an overlay and act based on that information by retrieving the overlayIndex() value of the selectionItem.

Hiding and destroying an overlay

You can either choose to temporarily hide an overlay or destroy it. To hide it use the setVisibility() function:

Other considerations

In the case of a navigation widget (like the NavCube or AxisTriad built into the HOOPS Web Viewer), you might want to ensure that the camera orientation of the main camera is reflected in the overlay. This can be achieved by using the camera callback and updating the modeling matrix (not necessarily the camera) of the node inside the overlay.

In the above code, we are first setting the camera callback (usually at the start of the application). Inside the callback, we retrieve the view matrix of the camera and remove any translate and scale components from that matrix before setting it on the top level node of the overlay. By doing that any camera changes in the main scene are reflected in the overlay.