Verifying HSF Files

Licensees of HOOPS/Stream who chose to use '.hsf' as their file name extension are contractually required to write compliant HSF files.

Therefore, it is highly recommended that you take steps to verify the correctness of HSF files that you export using the base classes, since there is the potential of incorrectly formatting the data (especially user-data) or incorrectly organizing the scene-graph. For example, every #TKE_Open_Segment opcode must be matched by #TKE_Close_Segment opcode. Testing can be performed in two phases:

Basic Testing

In Windows distributions, the SDK includes a Reference Application called the Hoops3DPartViewer. It is located in the /bin directory. After creating an HSF file, read it into the Reference Application. If there is an error with the formatting of the HSF data, the app will generate a corresponding message box and Advanced Testing should be performed (discussed below). If no message is generated, then the formatting of the data in the HSF file is valid.

Correct formatting of the data is not to be confused with the validity of the scene-graph represented in the HSF file. If there is a problem with how the scene-graph is organized, the reference application will generate a HOOPS/3dGS-specific error. This error should be used to try and locate the problem with how the scene-graph was organized. Additionally, after a problematic file has finished loading, it can be useful to export it to an 'HMF' file from the application. This is a readable, ASCII representation of the scene-graph. Inspection of this file may provide clues to the problem with scene-graph organization.

Advanced Testing

If the Reference Application reports that there was an error with reading the file, then further steps must be taken to determine the problem. If user data is being written out (via the #TKE_Start_User_Data opcode, which can be manually exported or exported using the TK_User_Data opcode handler) confirm that the data is being properly formatted per the notes in Section 4.1: Customizing HSF Objects This type of error could also be due to a bug in the writing or reading logic of the toolkit itself.

The toolkit provides logfile capabilities to help track down such problems. To use these capabilities, perform the following steps:

  1. Call BStreamFileToolkit::SetLogging passing true.
  2. Re-export the HSF file; the toolkit will create a file called hsf_export_log.txt which contains a byte representing each opcode that was exported.
  3. Read the HSF file using the ::TK_Read_Stream_File function as reviewed in the section on Controlling Reading (ensure that any custom opcode handlers that you've created are registered with the BStreamFileToolkit object passed into ::TK_Read_Stream_File). The toolkit will create a file called hsf_import_log.txt which contains a byte representing each opcode that was imported.
  4. Compare the opcodes in the two log files and look for the first opcode where they differ (if any). It is likely that the first pair of matching opcodes has a problem with data formatting (or the toolkit has a bug). If you cannot find any problem with how you've formatted or exported the data and have a support contract, you should submit the problematic HSF file and the log files to technical support.

top_level:2 prog_guide:2 prog_guide/base_stream:0