==================
Updating the Scene
==================

Visualize is a retained mode (as opposed to an immediate mode) graphics system, which means it retains an internal database of the scene it is expected to render. During a display update, Visualize traverses the scene graph and ensures the picture on the screen or specified output context matches the contents of the scene graph. It follows that changes to the scene graph as a result loading a file, altering geometry, or modifying segment attributes are not reflected until you request an update by calling ``HPS::WindowKey::Update`` or ``HPS::WindowKey::UpdateWithNotifier``. All display contexts, including offscreen windows and hardcopy contexts, derive from ``HPS::WindowKey``, so the same method is used to update a scene regardless of the type of output device. In some cases, ``Update`` is called indirectly:

* If you are using the view hierarchy classes, the scene is updated in a slightly different way. See :doc:`this page <0301_core>` on view hierarchy for details.
* If you are utilizing an operator, each operator method will typically call ``HPS::WindowKey::Update`` inside each of its mouse, keyboard, or touch screen event handlers, so there is no need to manually call it again. See :doc:`our section on operators <0601_standard_operators>` and refer to each operator's reference manual entry for details.


.. _update_notification:

Update Notification
===================

Visualize will perform an asynchronous update by default, so the call to the ``Update`` method will return immediately even though the scene may not be finished rendering. However, it is often necessary to know when rendering is complete. ``HPS::UpdateNotifier`` allows you to be notified when the update is completed: 

.. tabs::

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

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

It may also be desirable to know the status of an update before it finishes. In this case, you can use the ``UpdateNotifier`` to inform you of the update progress.

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_window_update_progress.cs
		   :start-after: //! [window_update_progress]
		   :end-before: //! [window_update_progress]
		   
For many situations, ``UpdateWithNotifier`` will be the preferred choice because once ``HPS::UpdateNotifier::Wait`` returns, you are guaranteed that the Visualize database matches what is shown on the screen. However, for some situations, asynchronous updates are recommended. For example, during file I/O, it is probably better to keep other parts of the program responsive and not waiting for a long operation to finish.


.. _controlling_updates:

Controlling Updates
===================

Normally, when you make a change to the scene graph (by deleting geometry, moving objects, etc.) Visualize marks the modified segments as requiring a redraw. Upon the next display update, Visualize traverses the list of segments requiring redraws. By default, Visualize will draw as little as possible to ensure a correctly drawn scene is displayed. This could mean overlaying geometry over an old buffer, simply redrawing the back buffer, or doing a complete update. The end result is that after the update call, the picture on the screen matches the picture described by the scene graph.

Visualize offers some control over how updates are performed, in order to ensure a correct result or boost performance in specific situations. Updates can be manually controlled by passing one of the ``HPS::Window::UpdateType`` enums to the ``HPS::WindowKey::Update`` method.

.. tabs::

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

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

Other types of updates are described in the reference manual and are generally not required except in special situations.


.. _timed_updates:

Timed Updates
=============

It may be desirable to have Visualize spend a fixed amount of time for an update. The ``HPS::WindowKey::Update`` function accepts an optional argument that represents a time value in seconds. The value imposes a hard limit on how long Visualize will spend rendering before aborting and starting on the next frame.

.. tabs::

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

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

Timed-updates are internally utilized by Visualize's *fixed framerate* support, to ensure that a fixed number of frames are drawn per second during user interaction. Fixed framerate is covered in :ref:`this section <prog_guide/0703_performance_considerations:Fixed framerate>`.
