=======
Reading
=======

In review, 'black box' reading of HSF files offers no 'streaming' features, where streaming refers to incrementally reading and displaying objects in the file. It is no different from reading any other datafile, where the user has to wait until the function returns before seeing anything on the screen. 

The function supplied with the 3dGS-specific classes to perform block box reading of a HOOPS Stream File is called ``HTK_Read_Stream_File``. This function only applies when you have an HSF file that you want to import and map to a HOOPS/3dGS scene-graph. 

Prior to calling ``HTK_Read_Stream_File``, a HOOPS segment must first be open. The function will parse the file and build up the corresponding segments, geometry and attributes in the HOOPS/3dGS scene graph. 

``HTK_Read_Stream_File`` takes as arguments a filename, flags which denote reading options, and a pointer to a HStreamFileToolkit object. The function returns a variable of type #TK_Status, indicating if there was a version mismatch or error, among other things. (The HStreamFileToolkit object is used for custom reading and writing and is discussed in the section :doc:`Controlling the reading and writing process </prog_guide/3dgs_stream/02_03_3dgs_controlling_read_write>`.
  
The following code reads in a file called *sample.hsf* into the segment called '?Picture' within the HOOPS database, and performs simple version/error checking on the file::

	#include "hc.h"            
			  
	main()             
	{ 
		int				flags = 0;  /* no reading flags set for now; use defaults */            
		TK_Status		status; 
				  
		HC_Open_Segment("?Picture");            
		  status = HTK_Read_Stream_File("sample.hsf", flags);          
		  
		  if (status == TK_Version)  
		  { 
			MessageBox("This file was created with a newer version of the            
			HOOPS/Stream Toolkit. This application's version of the toolkit 
			will need to be updated in order to view it."); 
		  } else if (status == TK_Error) 
			MessageBox("Error reading file."); 
					 
		HC_Close_Segment(); 
	} 

The toolkit will automatically detect and read in the various components of the HSF. 
