===============================
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:

.. image:: images/hoops_stream_usage_overview.gif


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:

.. image:: images/opcodes.png


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.) 

.. only:: standard

	Usage examples
	==============

	The following image depicts how the HOOPS/Stream Toolkit is used by the Parasolid Part Viewer, as well as the HOOPS Stream Control and plug-in: 

	.. image:: images/hoops_stream_example_usage.gif

	**Parasolid Part Viewer** - Both of these applications are based on the components of the HOOPS 3D Application Framework, and use the HOOPS/Stream Toolkit to export the data to an HSF file. The data   could have originated from a Parasolid XT file.
	  
	**HOOPS 3D Stream Control** - This is an ActiveX control which provides support for streaming in an HSF file from an URL, as well as functionality for viewing and manipulating HSF files. It can be reference in an *.html* page for viewing inside Internet Explorer, and can also be embedded into OLE compliant container applications such as the MS Office suite.
