HOOPS Visualize Documentation

< Table of Contents

PROGRAMMING GUIDE

3.4 Subwindows

Subwindows are either used to divide the main window into sections, or they are used in an overlapping manner to create "picture-in-picture" displays. While windows are traditionally thought of as a discrete, top-level component, in HOOPS Visualize, a subwindow is actually an attribute of a segment. When set, the segment (and all subsegments) are rendered into the subwindow. When specifying the subwindow, use window coordinates to define the rectangle:

[snippet 3.4.a]
SubwindowKit subwindowKit;
subwindowKit.SetSubwindow(Rectangle(0.4f, 0.95f, -0.5f, 0), Subwindow::Type::Standard);
SegmentKey anotherSegmentKey = mySegmentKey.Down("subwindow", true);
anotherSegmentKey.SetSubwindow(subwindowKit);
// insert geometry and set attrubutes on 'anotherSegmentKey' as you normally would
SubwindowKit subwindowKit = new SubwindowKit();
subwindowKit.SetSubwindow(new Rectangle(0.4f, 0.95f, -0.5f, 0), Subwindow.Type.Standard);
SegmentKey anotherSegmentKey = mySegmentKey.Down("subwindow", true);
anotherSegmentKey.SetSubwindow(subwindowKit);
// insert geometry and set attrubutes on 'subwindowKey' segment as you normally would

[figure 3.4.a] A standard subwindow within a top-level window

Unlike other attributes, subwindows inherit in an unorthodox fashion. When you set a subwindow attribute on a segment, its child segments appear in the subwindow. However, unlike the traditional inheritance paradigm, the child segments have no net subwindow attribute of their own. This exception is made to prevent unwanted recursive nested subwindows. For this reason, many subwindow settings don't have an effect if called from arbitrary segments where there is no explicitly defined subwindow. If you require a nested subwindow, set it on the particular subsegment where it is needed.

IMPORTANT: It should be noted that all Visualize windows have an implicit standard subwindow that is the size of the main window, even if no subwindow is explicitly defined. There is an important distinction to be made here regarding window coordinate systems. The implicit subwindow uses the Coordinate::Space::Window system which varies between -1 and 1 in both the x and y directions. The point 0, 0 marks the center of the screen. These coordinates never change. Coordinate::Space::InnerWindow is the coordinate system of any other subwindow.

[figure 3.4.b] The Coordinate::Space::Window coordinate system

Visualize offers two types of subwindows: standard and lightweight. Both types specify a section of the main window to render into. Unlike a regular window, subwindows have no top-level controls such as minimize or maximize.

A standard subwindow has the same characteristics of a top-level Visualize rendering context while the lightweight version has a few features and limitations:

Lightweight subwindow features and limitations:

Lightweight subwindows are created in almost the same way as standard subwindows. The only difference is in the call to SetSubwindow, the Lightweight enum is specified:

[snippet 3.4.b]
subwindowKit.SetSubwindow(Rectangle(0.4f, 0.95f, -0.5f, 0), Subwindow::Type::Lightweight);
subwindowKit.SetSubwindow(new Rectangle(0.4f, 0.95f, -0.5f, 0), Subwindow.Type.Lightweight);

Subwindow usage

A typical use for a lightweight subwindow would be for an axis triad, where you want the triad to be rendered in the window, but not actually be part of the scene.

When a subwindow is created, a new coordinate system relative to that window is also created. For example, to divide the screen equally between two subwindows, simply specify their bounding rectangle accordingly. Remember that the rectangles are always specified in window coordinates:

[snippet 3.4.c]
// dividing the main window into two subwindows
subwindowKit.SetSubwindow(Rectangle(-1, 0, -1, 1), Subwindow::Type::Standard);
SegmentKey leftSubwindowSeg = mySegmentKey.Down("left", true);
leftSubwindowSeg.SetSubwindow(subwindowKit);
subwindowKit.SetSubwindow(Rectangle(0, 1, -1, 1), Subwindow::Type::Standard);
SegmentKey rightSubwindowSeg = mySegmentKey.Down("right", true);
rightSubwindowSeg.SetSubwindow(subwindowKit);
// dividing the main window into two subwindows
subwindowKit.SetSubwindow(new Rectangle(-1, 0, -1, 1), Subwindow.Type.Standard);
SegmentKey leftSubwindowSeg = mySegmentKey.Down("left", true);
leftSubwindowSeg.SetSubwindow(subwindowKit);
subwindowKit.SetSubwindow(new Rectangle(0, 1, -1, 1), Subwindow.Type.Standard);
SegmentKey rightSubwindowSeg = mySegmentKey.Down("right", true);
rightSubwindowSeg.SetSubwindow(subwindowKit);

A common use case for a subwindow is incorporating an axis triad or other navigation entity in a corner of the screen:

[figure 3.4.c] This engine model is in the main window, and the axis triad is in a subwindow.

Windows are normally opaque and cover up the scene underneath, but transparent windows are available via SetBackground. Borders are also supported:

[snippet 3.4.d]
subwindowKit.SetBorder(Subwindow.Border.InsetBold);
subwindowKit.SetBackground(Subwindow.Background.Transparent);

Subwindow priority

As subwindows are inserted into the scene, they are automatically assigned a priority drawing value by HOOPS Visualize. If you have multiple overlapping subwindows in a scene, you can set an integer priority value that determines the draw order. Subwindows are drawn in order from least to greatest, therefore, the subwindows with higher priorities are drawn on top. To set a priority value for a subwindow, simply call SegmentKey::SetPriority with an integer value indicating the desired priority.

[snippet 3.4.e]
mySegmentKey.SetPriority(5);
mySegmentKey.SetPriority(5);