# HOOPS/Stream Technical Overview

## Overview

The ‘base’ classes of the HOOPS Stream Toolkit are intended to be used to export an HSF file when the graphics information is stored in a custom scene graph or set of application data-structures, or to import an HSF file which needs to be mapped to these types of data structures.

If the data to be exported to an HSF file already resides in the HOOPS 3D Graphics System (HOOPS/3DGS) scene graph, or if data being imported from an HSF file needs to be mapped to the HOOPS/3DGS scene graph, then the ‘3DGS’ classes should be used. The work of exporting the HOOPS/3DGS scene graph information to an HSF file, or mapping an HSF to a HOOPS/3DGS scene graph is encapsulated by the ‘3DGS’ classes. These classes and the full HOOPS 3D Graphics System are included with the HOOPS 3D Application Framework (HOOPS/3dAF). Developers who are currently using the standalone HOOPS/Stream Toolkit (which only contains the ‘base’ classes) can contact Tech Soft 3D for information about licensing the HOOPS 3D Application Framework.

## Architecture

During the export phase, the toolkit generates data buffers which contain the encoded, compressed, binary HSF representation of scene graph objects or custom user data. The toolkit provides built-in support for exporting these buffers to a file, but they can also be exported to a user-specified location. In this case, the developer supplies a buffer and buffer size, and the toolkit fills it with HSF data.

When importing, data buffers are passed to the toolkit for parsing and insertion into the appropriate data structures. Similar to the export process, data could also be imported from a user-specified location. (The developer gets a buffer of HSF data from their own data structures, from their own proprietary file, or perhaps it is sent as part of a message over a network connection, and the data is then passed to the toolkit.)

The following diagram provides an abstract, platform and GUI-independent overview of HSF file export/import using the toolkit:

### Opcode handlers

An HSF file consists of opcodes, each of which is followed by a corresponding set of operands that define a logical piece of data. HOOPS/Stream utilizes ‘opcode handlers’ to manage reading and writing of HSF objects. A set of default opcode handlers support the scene graph objects which are supported by the HOOPS 3D Graphics System; these include segments, attributes and geometry. However, the toolkit can be extended by deriving from the existing opcode handlers to export/import extra information that is appended to default objects or by adding new opcode handlers to export/import user-specific data.

The following diagram shows default opcode handlers that have been customized, along with a user-defined opcode handler:

### Streaming HSF data

Streaming of graphical 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 data buffer generation and parsing capabilities of the HOOPS/Stream toolkit, combined with its ability to create stream-enabled files, make it well suited for streaming data.

When streaming, it is useful for the reading process to occur asynchronously on a thread separated from the main application thread. This involves making platform and GUI specific function calls to create a new thread which continually obtains data buffers. This thread would then post a message to the main thread’s event loop indicating that a new buffer is ready for drawing. If the HOOPS/Stream Toolkit is being used in a standalone fashion, then this GUI-specific streaming logic must be written by the developer.

The HOOPS 3D Application Framework includes various GUI-specific modules (HOOPS/ActiveX, HOOPS/MFC, and HOOPS/Qt) to encapsulate the platform and GUI-specific logic required to support streaming of HSF files from either a local file, or from a website (URL). These modules provide a set of base classes from which developers can derive their own custom application classes and ActiveX controls.)

The HOOPS/Stream Toolkit has a client-side only architecture. It does not require deployment and configuration of any server-side modules, and is server-independent. Future versions of the toolkit may provide an optional server-side module as well. If the file resides on a remote webserver, having server-side logic enables support for additional features such as accessing specific parts of the remote file, view-dependent streaming, etc…

## Stream-related features

Both the HOOPS/Stream Toolkit and the HSF file format have properties which facilitate the streaming process. The stream-related features of the toolkit are discussed here; refer to the HSF Specification for details about the stream-related features of the file format itself.

### General features

Both the ‘base’ classes and the ‘3DGS’ classes support the following stream-related features:

- Compression - Both lossless LZ compression and sophisticated geometry-specific compression are supported. For example, the vertices, normals and vertex connectivity information of the ‘shell’ primitive (the primary primitive used to represent facet information) as well as any LOD representations of the shell are written out using compression techniques. Vertices and user-specified normals are written out with a compact, low resolution format rather than with the original floating-point representation passed to the toolkit.

  A variety of compression options can be set by the developer in order to balance the reduction in file size vs. the potential increase in export time.

- Object Revisiting - HSF objects can be tagged so that they can be ‘revisited’ at a later stage of file import or export. This allows export of a lower level of detail (LOD) representation of an object toward the beginning of the file, which can then be followed by a more detailed representation(s) of the same object later in the file.

- Piecemeal writing/reading - HSF data can be exported to a user-specified location via chunks of data with user-specified size. Similarly, as HSF data is available for import (perhaps it streamed infrom a web server), incremental pieces of HSF data can be passed to the toolkit.

### HOOPS/3DGS-specific features

The ‘3DGS’ classes support additional stream-related features, because knowledge of the scene graph structure is available to them:

- Custom scene graph organization - An HSF file exported with the 3DGS classes contains a scene graph that is specially ordered so that a reading application (which must sequentially read the file) can provide a more effective presentation of the data. The scene graph first contains all of the HOOPS/3DGS scene graph nodes (segments) and attributes, but only contains a first-level Level of Detail (LOD) representation for any ‘shell’ geometry in the segments. (A shell is one of the standard HOOPS/3DGS geometric primitives and is the main primitive used for representing facet information.)

  No other geometry is included in the initial segment tree.

  Following the regular segment tree are the remaining LOD representations for the shell objects, then the original full representation of the shell, and finally all the other geometry in the scene (polylines, circles, text, etc…).

  LOD representations are only written out to the HSF file if the HOOPS/3DGS scene graph already contains them. The developer can instruct HOOPS/3DGS to generate the LODs and also has control of the number of LODs, the ratios for polygon decimation, etc…) Using the HOOPS/Stream Toolkit, the file may then be streamed in and the scene incrementally updated as more detailed representations of objects are encountered in the file. Because the first part of the file contains simple geometry, the application can read and display a rough picture very quickly, even if the data is being pulled in over a slower connection such as from a remote website.

- Object Prioritizing - All ‘shell’ primitives are ordered using a ‘priority’ heuristic, which balances their size relative to other objects in the scene vs the number of vertices in the object. This also helps improve the quality of the streaming process.

- Shells stored via tristrips - Representation of the HOOPS/3DGS ‘shell’ primitive is written out in a special tristripped format. This format is more compact than the normal shell format and is also faster to process when drawing for the first time. Because objects are stored in the file as tristrips, HOOPS does not need to re-tristrip the object when it is drawn for the first time, thereby speeding up the initial scene drawing. (Tristripping involves triangulation of the faces in a HOOPS shell, and then building up a list of optimal-length tristrips in order to maximize subsequent retraversal and redrawing of the geometry, particularly for OpenGL rendering. HOOPS internally generates optimum-length tristrips.)