==========
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 |HPSNOW|, 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:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_3_3_abcde.cpp
		   :start-after: //! [0303_a]
		   :end-before: //! [0303_a]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_3_3_abcde.cs
		   :start-after: //! [0303_a]
		   :end-before: //! [0303_a]
		   
.. image:: images/3.3.a.png

*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.

.. _implicit_subwindow:

**IMPORTANT:** It should be noted that all |HPSNOW| 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 ``HPS::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. ``HPS::Coordinate::Space::InnerWindow`` is the coordinate system of any other subwindow.

.. image:: images/3.2.2.b.gif

*The Coordinate::Space::Window coordinate system*

|HPSNOW| 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 |HPSNOW| rendering context while the lightweight version has a few features and limitations:


.. _lightweight:

Lightweight Subwindow Features and Limitations
----------------------------------------------

* Uses less resources than standard subwindow
* Cannot be nested
* Lights positioned in lightweight subwindows will affect geometry in the parent window
* Background is always transparent
* Selection events pass through

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

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_3_3_abcde.cpp
		   :start-after: //! [0303_b]
		   :end-before: //! [0303_b]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_3_3_abcde.cs
		   :start-after: //! [0303_b]
		   :end-before: //! [0303_b]
		   
		   
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:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_3_3_abcde.cpp
		   :start-after: //! [0303_c]
		   :end-before: //! [0303_c]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_3_3_abcde.cs
		   :start-after: //! [0303_c]
		   :end-before: //! [0303_c]

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

.. image:: images/3.3.c.png

*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:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_3_3_abcde.cpp
		   :start-after: //! [0303_d]
		   :end-before: //! [0303_d]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_3_3_abcde.cs
		   :start-after: //! [0303_d]
		   :end-before: //! [0303_d]
		   
		   
Subwindow Priority
------------------

As subwindows are inserted into the scene, they are automatically assigned a priority drawing value by |HPSNOW|. 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 ``HPS::SegmentKey::SetPriority`` with an integer value indicating the desired priority.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_3_3_abcde.cpp
		   :start-after: //! [0303_e]
		   :end-before: //! [0303_e]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_3_3_abcde.cs
		   :start-after: //! [0303_e]
		   :end-before: //! [0303_e]
		   
		   
.. _modelcomparemode:
		   
Model Compare Mode
------------------

Subwindows can be used to compare two models in model comparison mode. The model comparison algorithm uses a depth buffer based difference to compare two models located in other segments.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_3_3_abcde.cpp
		   :start-after: //! [model_compare]
		   :end-before: //! [model_compare]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_3_3_abcde.cs
		   :start-after: //! [model_compare]
		   :end-before: //! [model_compare]

The two ``HPS::SegmentKey`` arguments are to be keys to model segments (segments containing only geometry without camera or lighting attributes). The subwindow object will contain a view with a camera and other attributes with which to view the compare mode for the two models. Once you call this function, the subwindow will automatically display the comparison view. You can manipulate the comparison mode display using |HPSNOW| operators (to respond to UI events) or by setting a camera programmatically.

After you have done the comparison, two segments will be created under the subwindow which contain the two models. You can customize the colors by modifying the style segments that get created under the destination segment.

.. image:: images/model-compare.png

*One possible result of the model compare algorithm, highlighting differences in two models.*

