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 Controlling the reading and writing process.

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.