==================
HSF Data Streaming
==================

This guide explains how you can implement on-demand and view-dependent streaming in your application. It is assumed that your application uses HOOPS/3dGS, HOOPS/Stream, and HOOPS/MVO components from HOOPS product suites. For details on these components and their usage, please refer to their respective sections in HOOPS documentation.

The ``HStreamer`` class provides functionality for streaming HSF data from a local file. The following is a step-by-step explanation for using the HStreamer class.


1. Create a HStreamer Object
----------------------------

	m_pHsfStreamer = new HStreamer();          

The HStreamer object should normally be associated with the HOOPS/Stream API.


2. Set the Condition and Error Notice Handler Function
------------------------------------------------------

	m_pHsfStreamer->SetConditionNoticeFunction(hstreamer_condition_notice_handler,(void*)this); 

The ``HStreamer`` object notifies the application about various error and state message through a callback function. The application must register the condition handler function as shown above. The following is a sample implementation of the condition handler function::

	void HQNetworkClientDlg::hstreamer_condition_notice_handler(unsigned int condition, void * user_data)
	{
		if(condition == HSTREAMER_CONDITION_VIEW_UPDATE)
			// do: update the view
		else if(condition == HSTREAMER_CONDITION_COMPLETE_READ_PAUSES)
		{
			// the dictionary/simplified representation has been loaded
			// do: populate segment brower or doc structure
			// do: subscribe to camera change notices
		}
		else if(condition == HSTREAMER_CONDITION_COMPLETE_SWEETENING)
		{
			// the streaming request has been completed
			// do: full update view
		}
	}


3. Set Up the HStreamer Object
------------------------------
   
	m_pHsfStreamer->Setup(GetHoopsView()->GetModel()->GetModelKey(), m_pHNetClient, n_pause);

Before trying to stream a file, the application must set up the ``HStreamer`` object by calling the ``HStreamer::Setup`` function. This function takes a segment key under which the streamed data will be loaded (this is usually the model key). For streaming local files (files on the local file system), you can pass this parameter as ``null``. Finally pass an integer which indicates how much of the file has to be loaded in the first request. Pass 0 to load the complete file. Pass 1 to load segment structure only and pass 2 to load the segment structure along with simplified representation (if available).
  

4. Load the File
----------------

	m_pHsfStreamer->LoadFile(filename);

Using ``HStreamer::LoadFile`` function, the application now loads the file. You must make sure that the filename matches exactly the one on the server and is present in the currently associated directory with the session.

After calling the ``HStreamer::LoadFile`` function, the application should wait for the ``HStreamer`` to complete the initial loading of the file before making any requests for sweetening. The application will be informed about this by the condition notice ``HSTREAMER_CONDITION_COMPLETE_READ_PAUSES``. Upon receiving this notice, the application has the HOOPS segment tree available. The segment tree might contain no shell geometry or simplified representation of it. 


5. Stream Data On-Demand
------------------------

	m_pHsfStreamer->Sweeten(key);

The ``HStreamer::Sweeten`` function takes the segment key. All the geometry contained in this segment will be streamed in. 
  
  
6. View-Dependent Streaming of Data
-----------------------------------

	m_pHsfStreamer->Sweeten(camera_position, camera_target, camera_up_vector, field, camera_projection);

The above variation of the ``HStreamer::Sweeten`` function takes the camera parameters and streams in all the geometry which lies in the view of this camera. Normally, for view-dependent streaming, the application would call this function each time the user changes the camera. 


7. Cleanup
----------

	delete m_pHsfStreamer;

Calling the destructor will clean up the HStreamer object and release the resources.
