================================
Interaction with a window system
================================

In the :doc:`viewing section </prog_guide/3dgs/03_4_viewing_windows>`, we covered how to connect HOOPS/3dGS to the native window system so that HOOPS would know where to send its output. This also required disabling input processing which is discussed in more detail here.

You disable HOOPS/3dGS input processing using the "disable input" driver option. This driver option has two variations: 

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../hoops_3df/demo/common/sanity/0700_docs_0019.cpp
		   :start-after: //! [disable_input]
		   :end-before: //! [disable_input]

Both variations tell HOOPS/3dGS that your application will receive input events directly from the window system. Therefore, HOOPS/3dGS does not attempt to read input devices such as the mouse or keyboard. 

With the first variation, HOOPS/3dGS does not read input devices, but it still receives paint messages (sometimes called expose or damage events) from the window system. Therefore, when your application receives a paint message (because all or part of the output window was obscured and was then made visible), HOOPS/3dGS will repaint its output window automatically. 

In the second variation ``("disable input = all")``, HOOPS/3dGS receives no input messages at all. Therefore, your application will have to receive paint messages and to call ``Update_Display`` explicitly.
  

Controlling updates
===================

If the system option "disable input" is set to all, when you call ``Update_Display``, HOOPS will redraw the entire scene, even if only a small part of that scene needs redrawing. To fix this inefficiency, HOOPS/3dGS  provides a command called ``Control_Update``. 

You can use the ``Control_Update`` command to specify which parts of the HOOPS/3dGS database need to be redrawn. You can specify the parts to be redrawn by segment, by key (using the ``Control_Update_By_Key`` command), or by area (using the ``Control_Update_Area`` or ``Control_Update_Area_By_Key`` commands). For example, if a paint message from the window system specifies that only part of the output window needs to be redrawn, you can specify the area to be drawn using the ``Control_Update_Area`` command. 

In some cases, when a part of the HOOPS/3dGS database is modified, HOOPS automatically sets a flag at that node and then propagates it up to the driver segment. This flag signals to HOOPS, during the next display update, to redraw that part of the tree. However, you might not want to trigger a redraw if you are modifying an attribute that does not affect the rendering of a scene like a user option.  To prevent flag propagation, you can turn off the "update control" option in ``Define_System_Options``.  We recommend that you turn it off just before your specific database modification and then turn it back on. By default, "update control" is on.

When you use the ``Control_Update`` command (or related commands) you are assuming all responsibility for choosing which parts of the HOOPS database to update. This responsibility can require serious work. See the entry for ``Control_Update`` in the HOOPS/3dGS Reference Manual for more information.


Update display and application responsiveness
=============================================

During user manipulation of a model, HOOPS provides functionality like :doc:`LODs </prog_guide/3dgs/06_2_rendering_level_of_detail>` to help your application preserve as much visual integrity in the scene with as little impact to the rendering performance as possible. However, an update can sometimes cause your application to appear unresponsive to user input especially when HOOPS renders a scene in full detail after a series of user manipulations.

To ensure that your application is responsive to user input during an update, you can set a callback with the "exit update" option in ``Set_Driver_Options`` before a call to ``Update_Display``. During the update process, HOOPS will invoke your callback at regular intervals. If you want to break out of the update to respond to a user event or to just end the update process, you can call ``HIC_Abort_Update`` from within your callback. We recommend that you set this callback only in the case of an extensive update.

In the main application loop, to determine if the last update was interrupted by an abort, driver event or a user-queued special event, you can query the "event interrupted" option using ``HC_Show_Device_Info``.When the update process is interrupted, HOOPS uses the "display interrupted update" option in ``HC_Set_Driver_Options`` to determine if it should display the partially rendered scene.  The valid values for this option are default, on and off.  If you do not set this value, it will automatically be set to default which tells HOOPS to display the partially rendered scene if the update was timed or not if the update was not timed.

When an update ends before an entire scene is rendered, HOOPS might resume drawing the scene on the next update if nothing has changed.  For instance, this might occur if you have used ``Set_Heuristics`` to set the "maximum extent mode" to "defer" and are using timed updates. To find out if the last update was a continuation of the previous update, you can call ``Show_Device_Info`` passing the "resume update" option.  If HOOPS returns "yes", then the last update was an attempt to finish drawing a partially rendered scene.

The following is a example of how you can set up and use the "exit update" option on the Microsoft Windows platform::

	void MainForm::MainForm()
	{
		...
		//Registering the callback
		HC_Define_Callback_Name("exit_update_handler", UpdateEventHandler);
		...
	}	

	void MainForm::SetExitUpdate()
	{	
		HC_Open_Segment_By_Key(m_pView->GetViewKey());
		
		//sets the exit update option to UpdateEventHandler
		HC_Set_Driver_Options("exit update = exit_update_handler");
		HC_Close_Segment();
	}	

	void MainForm::UpdateEventHandler(struct ht_net_rendition *nr)
	{
		//Checks to see the left mouse button was pressed
		int state = GetAsyncKeyState(VK_LBUTTON);
		if (state & 32768)				
			HIC_Abort_Update(nr);			
	}
