Basic Streaming for an HSF File

Streaming of 3D data typically refers to a process whereby graphical information is retrieved from a remote location such as a website or server and is displayed as soon as it is received by the client application. It allows the end-user to quickly obtain some visual feedback, as well as interact with the scene as it is still being displayed.

The various HOOPS/GUI modules provide <b>built-in</b> support for asynchronous streaming of the HSF format by leveraging the HOOPS/Stream Toolkit capabilities. They all utilize the 3dGS-specific classes; therefore, the HSF data will be automatically mapped to a HOOPS/3dGS scene-graph.

The HOOPS/MFC and HOOPS/Qt modules, which help developers build standalone Unix and Windows applications that use HOOPS/3dGS for graphics, provide support for asynchronously streaming a local disk based file. (Future versions of these tools may provide support for streaming a file from a remote location; i.e. the file may reside on a webs server or application server.)

For more detailed information on how to use the HOOPS/GUI modules as a basis for streaming-enabled applications, refer to the appropriate HOOPS/GUI module for the development environment of interest. For developers who wish to understand the actual streaming process in more detail, or will not be using the prebuilt HOOPS/GUI modules (perhaps to performing streaming for a GUI/web environment which we currently do not provide a connector for, such as Java/Swing) the following sections provide details on how the streaming process works.

The following steps are necessary to add support for streaming an HSF into an application:

Create an instance of an HStreamFileToolkit object.
Open a file. For a local file, this could be done manually using fopen, or the toolkit’s wrapper function HStreamFileToolkit::OpenFile could be used.
Read, process and incrementally draw chunks of the file to the screen by calling the sequence of HStreamFileToolkit::ReadBuffer, HStreamFileToolkit::ParseBuffer and HC_Update_Display within a loop until the entire file has been read. For a local file, reading could be done manually using fread. If the toolkit’s OpenFile wrapper function was used to previously open the file, than ReadBuffer may be used to read from the file.

In review, ParseBuffer translates the specially formatted binary data into HOOPS segment, geometry and attribute information and inserts the information into the HOOPS database when using the 3dGS-specific classes. It is up to the developer to map the data to their custom data-structures within the Execute method of their cusotm opcode handlers when using the base classes. Most of the examples in this section deals with using the 3dGS-specific classes, but they would be very similar when using the base classes; any text that refers to using HOOPS/3dGS functions or mapping data to HOOPS/3dGS would be ‘replaced’ with the concept that the data is going to be mapped to your own data structures, and your own graphics subsystem’s functions would be called to draw objects, etc…

Additional notes when using the 3dGS-specific classes:

HC_Update_Display is a standard HOOPS/3dGS function which causes the database to be traversed and rendered to the display. When HC_Update_Display is called, HOOPS utilizes internal logic called ‘incremental updates’, whereby only changes made to the database since the last call to the update function are traversed. For example, if only a single HOOPS shell has been inserted into to the database since the last call to HC_Update_Display, only that shell will be traversed and drawn into the existing scene.
If the buffer passed to ParseBuffer ends in the middle of an HSF object, the toolkit automatically saves the partial information, as well as any HOOPS database state information (i.e. maybe several segments are currently open), and the next call to ParseBuffer will result in the binary information being pieced together correctly.

The following code demonstrates how an HSF file called factory.hsf could be streamed into the HOOPS database and incrementally drawn, using the the 3dGS-specific classes:

void StreamHSFFile (char const * filename)
{
        auto    char            block[BUFFER_SIZE];
        auto    TK_Status       status = TK_Normal;
        auto    int                     amount;

        HStreamFileToolkit * tk = new HStreamFileToolkit;

        if ((status = tk->OpenFile (filename)) != TK_Normal)
                return status;
        do
        {
                if (tk->ReadBuffer (block, BUFFER_SIZE, amount) != TK_Normal)
                        break;

                status = tk->ParseBuffer (block, amount);

                HC_Update_Display();

                if (status == TK_Error)
                {
                        // whatever...
                        break;
                }
        } while (status != TK_Complete);

        tk->CloseFile ();

        delete tk;
}