==============
View hierarchy
==============

Now that the application is set up with a window it can use for rendering, let's take a closer look at the pipeline for how rendering is accomplished. The geometry and associated attributes of any HNP scene are stored in an internal database. This database is organized into a hierarchical scene graph which dictates how rendering takes place. While the scene graph itself is a low-level data structure, HNP provides higher level abstractions which facilitate viewing and scene manipulation. These higher level components make up the `view hierarchy <https://docs.techsoft3d.com/hps/latest/build/prog_guide/0301_core.html>`_.

Four classes work together as nested containers to provide this functionality:

.. raw:: html

	<ul>
		<li><span class="code">HPS::Canvas</span> - analogous to the client area of an native application GUI window</li>
		<ul>
			<li><span class="code">HPS::Layout</span> - optional, used to determine how views are arranged in the window when multiple views are in use</li>
			<ul>
				<li><span class="code">HPS::View</span> - represents a camera's view of the model, and many views can be active simultaneously</li>
				<ul>
					<li><span class="code">HPS::Model</span> - a portion of the scene graph which corresponds to a logical model - this contains the geometry</li>
				</ul>
			</ul>
		</ul>
	</ul>

.. image:: images/view_hierarchy.png

The objects which correspond to the classes listed above are all created using the static class `HPS::Factory <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_factory.html>`_. For example, continuing from the last code snippet, we can see the `View <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_view.html>`_ being created and immediately attached to the `Canvas <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_canvas.html>`_:

.. literalinclude:: /source/CHPSView.cpp
	:language: c
	:start-after: //! [attach_view]
	:end-before: //! [attach_view]

`HPS::Canvas <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_canvas.html>`_, `HPS:Layout <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_layout.html>`_, and `HPS::Model <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_model.html>`_ are created in a similar way. All of these are static functions:

.. code-block:: cpp

	HPS::Canvas myCanvas = HPS::Factory::CreateCanvas()
	HPS::Layout myLayout = HPS::Factory::CreateLayout()
	HPS::Model myModel = HPS::Factory::CreateModel()

Additionally, each view hierarchy object has a function to attach children, which binds the hierarchy together. For example:

.. code-block:: cpp

	canvas.AttachLayout(myLayout);
	myLayout.AttachViewFront(myView);
	myView.AttachModel(myModel);

See the HPS `Programming Guide <https://docs.techsoft3d.com/hps/latest/build/prog_guide/0301_core.html>`_ and `API reference <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_factory.html>`_ for more information.

Note that in the example above, the `HPS::Layout <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_layout.html>`_ wasn't used because there is only a single `View <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_view.html>`_ which takes the whole window (this shortcut is made available since this is such a common situation). In this case, a `View <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_view.html>`_ can be attached directly to a `Canvas <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_canvas.html>`_, but if you have multiple views, you'll need to you a `Layout <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_layout.html>`_ to arrange them correctly inside the window.

The last part of the view hierarchy, the `HPS::Model <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_model.html>`_, is a branch of the scene graph which contains the geometry that is to be rendered in the window whenever an update is triggered. To trigger an update, simply call `HPS::Canvas::Update <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_canvas.html#ae8d7b29ae669e9d020d2ec531ca97462>`_. We'll look at the `HPS::Model <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_model.html>`_ object in the next section.