The BStreamFileToolkit class provides support for importing/exporting HOOPS Stream File information. More...

#include <BStreamFileToolkit.h>

Public Member Functions

virtual void ActivateContext (ID_Key key)
 
TK_Status AddBounds (ID_Key key, float const bounds[])
 
bool AddExternalReference (char const *ref, ID_Key context)
 
bool AddExternalReference (__wchar_t const *ref, ID_Key context)
 
TK_Status AddIndexKeyPair (int index, ID_Key key)
 
void AddSegment (ID_Key key)
 
TK_Status AddVariant (ID_Key key, int variant, int value1, int value2=-1)
 
TK_Status AppendLastKey (ID_Key key)
 
 BStreamFileToolkit ()
 
void ClearLastKey ()
 
void ClearPauses ()
 
virtual TK_Status CloseFile ()
 
virtual TK_Status CloseGeometry ()
 
void CloseLogFile ()
 
int CurrentBufferLength ()
 
ID_Key CurrentSegment ()
 
virtual void DeactivateContext (ID_Key key)
 
virtual TK_Status Error (char const *msg=0) const
 
int GeneratedSoFar () const
 
bool GeometryIsOpen () const
 
bool GetAsciiMode ()
 
TK_Status GetBounds (ID_Key key, float bounds[]) const
 
int GetBufferLimit () const
 
__wchar_t const * GetCurrentFile () const
 
void GetCurrentFile (__wchar_t const *&filename) const
 
int GetDictionaryFormat () const
 
int GetDictionaryOffset () const
 
int GetDictionaryOptions () const
 
int GetDictionarySize () const
 
wchar_t const * GetExternalReference () const
 
void GetExternalReference (__wchar_t const *&exref) const
 
ID_Key GetExternalReferenceContext () const
 
unsigned int GetFileOffset () const
 Gets the file offset, a displacement to be added to positions used in the dictionary (for example, in case the data is appended to another file)
 
virtual TK_Status GetFileSize (unsigned HLONG &size)
 
int GetFirstPause () const
 
int GetFlags () const
 
int GetJpegQuality () const
 
TK_Status GetLastKey (ID_Key &key) const
 
char const * GetLogFile () const
 
bool GetLogging () const
 
unsigned int GetLoggingOptions (unsigned int mask=~0) const
 
int GetNumColorBits () const
 
int GetNumIndexBits () const
 
int GetNumNormalBits () const
 
int GetNumParameterBits () const
 
int GetNumVertexBits () const
 
TK_Status GetOffset (ID_Key key, int variant, int &offset) const
 
TK_Status GetOffset (ID_Key key, int variant, int &offset, int &length) const
 
TK_Status GetOffset (ID_Key key, int variant, int &offset, int &length, __wchar_t const *&filename) const
 
BBaseOpcodeHandlerGetOpcodeHandler (int which) const
 
int GetPauseCount () const
 
int const * GetPauseTable () const
 
int GetPosition () const
 
TK_Progress_Callback GetProgressCallback () const
 
void * GetProgressValue () const
 
float GetQuantizationError () const
 
int GetReadFlags (int mask=~0) const
 
int GetTabs ()
 
int GetTargetVersion () const
 
int GetVersion () const
 
float const * GetWorldBounding () const
 
int GetWriteFlags (int mask=~0) const
 
bool HeaderCommentSeen () const
 
TK_Status IndexToKey (int index, ID_Key &key) const
 
TK_Status KeyToIndex (ID_Key key, int &index) const
 
virtual TK_Status LocateDictionary ()
 
virtual TK_Status LocateEntity (ID_Key key, int variant)
 
void LogEntry (char const *string) const
 
void LogEntry (__wchar_t const *string) const
 
virtual bool MatchPreviousExRef () const
 
virtual void NewFileContext (ID_Key key)
 
bool NextExternalReference ()
 
unsigned int NextOpcodeSequence ()
 
int NextTagIndex ()
 
unsigned int ObjectsSoFar () const
 
virtual TK_Status OpenFile (char const *name, bool write=false)
 
virtual TK_Status OpenFile (__wchar_t const *name, bool write=false)
 
virtual TK_Status OpenGeometry ()
 
TK_Status OpenLogFile (char const *filename, char const *mode)
 
virtual TK_Status ParseBuffer (char const *b, int s, TK_Status mode=TK_Normal)
 
int PeekTagIndex () const
 
virtual TK_Status PositionFile (int offset)
 
TK_Status PrepareBuffer (char *b, int s)
 
TK_Status Read_Stream_File ()
 
virtual TK_Status ReadBuffer (char *buffer, int size, int &amount_read)
 
void RecordPause (int offset)
 
ID_Key RemoveSegment ()
 
void ReportQuantizationError (float error)
 
void ReportQuantizationError (int bits_per_sample, float const *bounding, int num_dimensions=3)
 
void ResetQuantizationError ()
 
virtual void Restart ()
 
ID_Key RevisitKey () const
 
ID_Key RevisitOwner () const
 
TK_Status SelectFile (char const *name)
 
TK_Status SelectFile (__wchar_t const *name)
 
TK_Status SetAsciiMode (bool whether)
 
void SetBufferLimit (int limit)
 
void SetDictionaryFormat (int format=3, int options=TK_Dictionary_Bounding_Volumes)
 
void SetDictionaryOffset (int offset)
 
void SetDictionarySize (int size)
 
void SetFilename (char const *name)
 
void SetFilename (__wchar_t const *name)
 
void SetFileOffset (unsigned int offset)
 Sets the file offset, a displacement to be added to positions used in the dictionary (for example, in case the data is appended to another file)
 
void SetFirstPause (int offset)
 
void SetFlags (int flags)
 
void SetJpegQuality (int quality=75)
 
void SetLastKey (ID_Key key)
 
void SetLogFile (char const *filename=0)
 
void SetLogging (bool setting)
 
void SetLoggingOptions (unsigned int options=~0)
 
void SetNewFile (char const *name)
 
void SetNewFile (__wchar_t const *name)
 
void SetNumColorBits (int numbits)
 
void SetNumIndexBits (int numbits)
 
void SetNumNormalBits (int numbits)
 
void SetNumParameterBits (int numbits)
 
void SetNumVertexBits (int numbits)
 
void SetOpcodeHandler (int which, BBaseOpcodeHandler *handler)
 
void SetOpcodeSequence (unsigned int seq=0)
 
void SetPostwalkHandler (BBaseOpcodeHandler *handler)
 
void SetPrewalkHandler (BBaseOpcodeHandler *handler)
 
void SetProgressCallback (TK_Progress_Callback cb=0)
 
void SetProgressValue (void *value)
 
void SetReadFlags (int flags)
 
void SetReadVersion (int version)
 
void SetTabs (int)
 
void SetTargetVersion (int version)
 
void SetWorldBounding (float const bbox[])
 
void SetWorldBoundingBySphere (float const pt[], float radius)
 
void SetWriteFlags (int flags)
 
int Unused () const
 
virtual TK_Status WriteBuffer (char *buffer, int size)
 
- Public Member Functions inherited from BControlledMemoryObject
void operator delete (void *p)
 force deallocation to happen in the stream toolkit's scope
 
void * operator new (size_t size)
 force allocation to happen in the stream toolkit's scope
 

Static Public Member Functions

static int ParseVersion (char const *block)
 
static bool SupportsAsciiMode ()
 

Protected Attributes

void * m_file
 

Friends

class BBaseOpcodeHandler
 
class HTK_Reference
 
class Internal_Segment_Processor
 
class TK_Comment
 
class TK_Compression
 
class TK_Default
 
class TK_Dictionary
 
class TK_Header
 
class TK_Instance
 
class TK_Shell
 
class TK_Tag
 

Detailed Description

The BStreamFileToolkit class provides support for importing/exporting HOOPS Stream File information.

BStreamFileToolkit is the primary support class which manages streaming of HOOPS Stream File data into the HOOPS database. The class also provides support for the user to manage export of information from the HOOPS database to a HOOPS Stream File. It is HOOPS/3dGS-independent; therefore the data does not have to reside in a HOOPS/3dGS scene-graph prior to export and it will not be mapped to a HOOPS/3dGS scene-graph during import. (See the opcode handler notes below)

The HSF file reading process involves reading the opcode at the start of each piece of binary information, and calling the Read method of the associated opcode handler. After the opcode handler reports that reading is complete, the Execute method should be called. The ParseBuffer method of the BStreamFileToolkit object encapsulates this process.

The HSF file writing process involves determining the proper opcode for each piece of binary information, and calling the Interpret method of the associated opcode handler. After interpretation is complete,
the Write method of the opcode handler should be called until writing is complete.
BStreamFileToolkit uses a concept of opcode handlers to manage reading and writing of logical pieces of binary information stored in the file. A set of default opcode handlers support standard HOOPS file objects such as segments, attributes and geometry, and the toolkit can be extended by deriving from the existing opcode handlers or adding new ones in order to handle user-specific data. All of the default opcode handlers registered with this class are of the naming convention TK_XXX, where XXX is the type of HSF object. The TK_XXX opcode handlers only provide implementations of the Read and Write methods; therefore the following two methods need to be implemented:

  • Interpret : this method should query the graphics data (meaning, extract it from data structures); the data will then be written out to an HSF via the Write method
  • Execute : this method should map the HSF data to custom data structures after it has been read in from the HSF file via the Read method

Streaming refers to a method of import where the user can incrementally supply pieces of data to the file toolkit object. This is useful in order to incrementally update the scene while data is still being read in, rather than wait until the entire file has been read before any visual result is available.

To begin the streaming process, read a buffer of HOOPS Stream File data from a local file, a remote location, or memory.
This reading process could happen asynchronously on a thread that is separate from the main application thread. The toolkit class provides some wrapper functions to open/close and read/write a buffer of data to and from the HOOPS Stream File.

Constructor & Destructor Documentation

◆ BStreamFileToolkit()

BStreamFileToolkit::BStreamFileToolkit ( )

Default constructor for an BStreamFileToolkit object

Member Function Documentation

◆ ActivateContext()

virtual void BStreamFileToolkit::ActivateContext ( ID_Key  key)
inlinevirtual

While parsing a buffer it may be necessary to keep a context. This method will be called by ParseBuffer to activate a context, and should be overloaded to provide custom context-activation.

Parameters
keyA context identifier

Reimplemented in HStreamFileToolkit.

◆ AddBounds()

TK_Status BStreamFileToolkit::AddBounds ( ID_Key  key,
float const  bounds[] 
)
inline

Records the bounding volume associated with a previously recorded object.

Parameters
keyThe HOOPS key of the object
boundsThe bounding volume as 6 floats (min & max points of a box)
Returns
The result of the function call.

◆ AddExternalReference() [1/2]

bool BStreamFileToolkit::AddExternalReference ( char const *  ref,
ID_Key  context 
)

Saves an external reference (string) and associated context (current open segment) to be processed.

Parameters
refexternal reference string
contextexternal reference context
Returns
true if the reference was added, false if the reference would form a loop

◆ AddExternalReference() [2/2]

bool BStreamFileToolkit::AddExternalReference ( __wchar_t const *  ref,
ID_Key  context 
)

Saves an external reference (Unicode string) and associated context (current open segment) to be processed.

Parameters
refexternal reference Unicode string
contextexternal reference context
Returns
true if the reference was added, false if the reference would form a loop

◆ AddIndexKeyPair()

TK_Status BStreamFileToolkit::AddIndexKeyPair ( int  index,
ID_Key  key 
)
inline

Associates a HOOPS key with a file index, and adds the an entry to the toolit's index/key association table.

Parameters
indexAn integer denoting a file index.
keyThe HOOPS key that to associate with the specified index.
Returns
The result of the function call.

◆ AddSegment()

void BStreamFileToolkit::AddSegment ( ID_Key  key)

Adds the specified key to the from of a list to keep track of "open" segments.

Parameters
keyof segment being openned

◆ AddVariant()

TK_Status BStreamFileToolkit::AddVariant ( ID_Key  key,
int  variant,
int  value1,
int  value2 = -1 
)
inline

Records the file offset, and optionally the size, of a variant (LOD) associated with a previously recorded key.

Parameters
keyThe HOOPS key of the object
variantThe variant (LOD number) being recorded
value1The file offset of the start of the variant
value2The size of the variant
Returns
The result of the function call.

◆ AppendLastKey()

TK_Status BStreamFileToolkit::AppendLastKey ( ID_Key  key)

Appends the identifier of the last object processed to the current identifier list

◆ ClearLastKey()

void BStreamFileToolkit::ClearLastKey ( )

Clears identifier of the last object processed

◆ ClearPauses()

void BStreamFileToolkit::ClearPauses ( )
inline

Clears the pause table

◆ CloseFile()

virtual TK_Status BStreamFileToolkit::CloseFile ( )
virtual

Closes a file. This acts as a simple wrapper for the 'fclose' command.

Returns
The result of function call.

◆ CloseGeometry()

virtual TK_Status BStreamFileToolkit::CloseGeometry ( )
inlinevirtual

Completes dealing with geometry-level attributes

Returns
status of the request, error if no geometry is open

References TK_Normal.

◆ CloseLogFile()

void BStreamFileToolkit::CloseLogFile ( )

Closes the log file

◆ CurrentBufferLength()

int BStreamFileToolkit::CurrentBufferLength ( )
inline

Returns how much of the internal data buffer is currently filled

◆ CurrentSegment()

ID_Key BStreamFileToolkit::CurrentSegment ( )
inline

Returns the key of the currently "open" segment

Returns
key of the current segment

◆ DeactivateContext()

virtual void BStreamFileToolkit::DeactivateContext ( ID_Key  key)
inlinevirtual

While parsing a buffer it may be necessary to keep a context. This method will be called by ParseBuffer to deactivate a context, and should be overloaded to provide custom context-deactivation.

Parameters
keyA context identifier

Reimplemented in HStreamFileToolkit.

◆ Error()

virtual TK_Status BStreamFileToolkit::Error ( char const *  msg = 0) const
virtual

Prints out a debug message informing the user that an error has occurred. Also provides a handy choke point for break points during debugging.

Returns
TK_Error always

Referenced by BBaseOpcodeHandler::Clone().

◆ GeneratedSoFar()

int BStreamFileToolkit::GeneratedSoFar ( ) const
inline

Returns the number of bytes that have been written since the beginning of the writing process. This is currently used internally during writing to build up a dictionary of file offets for each logical piece of binary data in the file, so that random lookups may be performed during file loading.

◆ GeometryIsOpen()

bool BStreamFileToolkit::GeometryIsOpen ( ) const
inline

Queries the state of geometry-level attribute handling

Returns
whether geometry-level handling is active

◆ GetAsciiMode()

bool BStreamFileToolkit::GetAsciiMode ( )

Ascii is a deprecated mode. DO NOT USE.

◆ GetBounds()

TK_Status BStreamFileToolkit::GetBounds ( ID_Key  key,
float  bounds[] 
) const
inline

Returns the bounding volume associated with a previously recorded key.

Parameters
keyThe HOOPS key of the object
boundsThe bounding volume as 6 floats (min & max points of a box)
Returns
The result of the function call.

◆ GetBufferLimit()

int BStreamFileToolkit::GetBufferLimit ( ) const
inline

Returns the progress passthrough value

◆ GetCurrentFile() [1/2]

__wchar_t const* BStreamFileToolkit::GetCurrentFile ( ) const
inline

Returns the name of the last file, if any, that was associated with the toolkit.

Returns
The name of the file associated with the toolkit.

◆ GetCurrentFile() [2/2]

void BStreamFileToolkit::GetCurrentFile ( __wchar_t const *&  filename) const
inline

Returns the name of the last file, if any, that was associated with the toolkit.

Parameters
Thepointer to receive the adress of then name of the file associated with the toolkit.

◆ GetDictionaryFormat()

int BStreamFileToolkit::GetDictionaryFormat ( ) const
inline

Returns the currently requested dictionary format level

Returns
Dictionary format

◆ GetDictionaryOffset()

int BStreamFileToolkit::GetDictionaryOffset ( ) const
inline

Returns the recorded dictionary offset

Returns
Dictionary offset

◆ GetDictionaryOptions()

int BStreamFileToolkit::GetDictionaryOptions ( ) const
inline

Returns the options for the dictionary format.

Returns
Dictionary options bitmask

◆ GetDictionarySize()

int BStreamFileToolkit::GetDictionarySize ( ) const
inline

Returns the recorded dictionary size

Returns
Dictionary size

◆ GetExternalReference() [1/2]

wchar_t const* BStreamFileToolkit::GetExternalReference ( ) const
inline

Returns the string representing the external reference at the beginning of the list, null if none.

Returns
external reference string

◆ GetExternalReference() [2/2]

void BStreamFileToolkit::GetExternalReference ( __wchar_t const *&  exref) const
inline

Returns the string representing the external reference at the beginning of the list, null if none.

Parameters
pointerto receive the address of the external reference string

◆ GetExternalReferenceContext()

ID_Key BStreamFileToolkit::GetExternalReferenceContext ( ) const
inline

Returns the context associated with the external reference at the beginning of the list, -1 if none.

Returns
external reference context

◆ GetFileSize()

virtual TK_Status BStreamFileToolkit::GetFileSize ( unsigned HLONG &  size)
virtual

Utility function which returns the size of the currently open file. This acts a wrapper for fstat, and is used by the progress callback (if any), but might be reimplemented by classes derived from BStreamFileToolkit to perform custom file repositioning.

Parameters
sizereference to the variable to receive the file size.
Returns
The result of function call.

◆ GetFirstPause()

int BStreamFileToolkit::GetFirstPause ( ) const
inline

supported for older code

◆ GetFlags()

int BStreamFileToolkit::GetFlags ( ) const
inline

Deprecated; Use GetWriteFlags; Returns the writing flags set on the toolkit.

◆ GetJpegQuality()

int BStreamFileToolkit::GetJpegQuality ( ) const
inline

Returns the current JPEG quality setting

◆ GetLastKey()

TK_Status BStreamFileToolkit::GetLastKey ( ID_Key key) const

Returns identifier of the last object processed

◆ GetLogFile()

char const* BStreamFileToolkit::GetLogFile ( ) const
inline

Returns the name of the log file

◆ GetLogging()

bool BStreamFileToolkit::GetLogging ( ) const
inline

Returns the logging state

Referenced by BBaseOpcodeHandler::PutOpcode().

◆ GetLoggingOptions()

unsigned int BStreamFileToolkit::GetLoggingOptions ( unsigned int  mask = ~0) const
inline

Returns the logging options

◆ GetNumColorBits()

int BStreamFileToolkit::GetNumColorBits ( ) const
inline

Returns the maximum number of bits that will be used per vertex color

◆ GetNumIndexBits()

int BStreamFileToolkit::GetNumIndexBits ( ) const
inline

Returns the maximum number of bits that will be used per vertex color-by-index

◆ GetNumNormalBits()

int BStreamFileToolkit::GetNumNormalBits ( ) const
inline

Returns the maximum number of bits that will be used per normal

◆ GetNumParameterBits()

int BStreamFileToolkit::GetNumParameterBits ( ) const
inline

Returns 3 times the number of bits that will be used per sample in vertex parameters (texture cordinate)

◆ GetNumVertexBits()

int BStreamFileToolkit::GetNumVertexBits ( ) const
inline

Returns the maximum number of bits that will be used per vertex location (x,y,z combined).

◆ GetOffset() [1/3]

TK_Status BStreamFileToolkit::GetOffset ( ID_Key  key,
int  variant,
int &  offset 
) const
inline

Returns the file offset of a variant (LOD) associated with a previously recorded key.

Parameters
keyThe HOOPS key of the object
variantThe variant (LOD number) being recorded
offsetThe file offset of the start of the variant
Returns
The result of the function call.

◆ GetOffset() [2/3]

TK_Status BStreamFileToolkit::GetOffset ( ID_Key  key,
int  variant,
int &  offset,
int &  length 
) const
inline

Returns the file offset and length of a variant (LOD) associated with a previously recorded key.

Parameters
keyThe HOOPS key of the object
variantThe variant (LOD number) being recorded
offsetThe file offset of the start of the variant
lengthThe size of the variant (returned as 0 if unknown)
Returns
The result of the function call.

◆ GetOffset() [3/3]

TK_Status BStreamFileToolkit::GetOffset ( ID_Key  key,
int  variant,
int &  offset,
int &  length,
__wchar_t const *&  filename 
) const

Returns the file offset and length of a variant (LOD) associated with a previously recorded key.

Parameters
keyThe HOOPS key of the object
variantThe variant (LOD number) being recorded
offsetThe file offset of the start of the variant
lengthThe size of the variant (returned as 0 if unknown)
filenamepointer to the stored filename associated with the key (may be null)
Returns
The result of the function call.

◆ GetOpcodeHandler()

BBaseOpcodeHandler* BStreamFileToolkit::GetOpcodeHandler ( int  which) const
inline
Returns
A pointer to the requested opcode handler

◆ GetPauseCount()

int BStreamFileToolkit::GetPauseCount ( ) const
inline

Returns the number of pauses recorded

Returns
The number of pauses

◆ GetPauseTable()

int const* BStreamFileToolkit::GetPauseTable ( ) const
inline

Returns the pause offsets

Returns
address of an array of file offsets corresponding the the pauses

◆ GetPosition()

int BStreamFileToolkit::GetPosition ( ) const
inline

Returns the current file position

◆ GetProgressCallback()

TK_Progress_Callback BStreamFileToolkit::GetProgressCallback ( ) const
inline

Returns the progress callback

◆ GetProgressValue()

void* BStreamFileToolkit::GetProgressValue ( ) const
inline

Returns the progress passthrough value

◆ GetQuantizationError()

float BStreamFileToolkit::GetQuantizationError ( ) const
inline
Returns
the largest quantization error reported by any of the opcodes during writing. Error reported is object space, with no attempt to account for modelling matrices.

◆ GetReadFlags()

int BStreamFileToolkit::GetReadFlags ( int  mask = ~0) const
inline

Returns the reading flags set on the toolkit. These flags control various import properties, and are defined in TK_File_Read_Options

Parameters
maskof flags to be returned (default is all).
Returns
The result of function call.

◆ GetTargetVersion()

int BStreamFileToolkit::GetTargetVersion ( ) const
inline

Returns the file format version desired for writing

Referenced by BBaseOpcodeHandler::PutGeneral().

◆ GetVersion()

int BStreamFileToolkit::GetVersion ( ) const
inline

Returns the file format version during reading

Referenced by BBaseOpcodeHandler::GetGeneral().

◆ GetWorldBounding()

float const* BStreamFileToolkit::GetWorldBounding ( ) const
inline
Returns
the world bounding box

◆ GetWriteFlags()

int BStreamFileToolkit::GetWriteFlags ( int  mask = ~0) const
inline

Returns the writing flags set on the toolkit. These flags control a variety of export properties, and are defined in TK_File_Write_Options

Parameters
maskof flags to be returned (default is all).
Returns
The result of function call.

Referenced by BBaseOpcodeHandler::Tagging().

◆ HeaderCommentSeen()

bool BStreamFileToolkit::HeaderCommentSeen ( ) const
inline

Returns true if the header comment has been processed

◆ IndexToKey()

TK_Status BStreamFileToolkit::IndexToKey ( int  index,
ID_Key key 
) const

Calculates the HOOPS key associated with the specified index.

Parameters
indexAn integer denoting a file index.
keyThe HOOPS key associated with the specified index. Returned to user. Passed by reference.
Returns
The result of the function call.

◆ KeyToIndex()

TK_Status BStreamFileToolkit::KeyToIndex ( ID_Key  key,
int &  index 
) const

Calculates the index associated with the specified HOOPS key.

Parameters
keyA HOOPS key.
indexAn integer denoting the file index associated with the HOOPS key. Returned to user. Passed by reference.
Returns
The result of the function call.

◆ LocateDictionary()

virtual TK_Status BStreamFileToolkit::LocateDictionary ( )
virtual

Instructs the BStreamFileToolkit object to sets its internal file pointer to the location of the file dictionary. The dictionary contains entries for the file locations of various representations of entities.

Objects which are derived from BStreamFileToolkit may reimplement to support locating a dictionary for a file that resides on a remote location such as a web server. This might involve passing a message that instructs the server process to locate the dictionary.

Returns
The result of function call.

◆ LocateEntity()

virtual TK_Status BStreamFileToolkit::LocateEntity ( ID_Key  key,
int  variant 
)
virtual

Instructs the BStreamFileToolkit object to sets its internal file pointer to the location of a
variant of an entity, which could be the full representation or a LOD representation. This allows reading a single entity from the file, even though it resides at an offset in the file.

Parameters
keyThe key of a HOOPS entity.
variantThe variant of the HOOPS entity to locate. 0 represents the full representation, 1 represents LOD level 1, etc....
Returns
The result of function call.

◆ LogEntry() [1/2]

void BStreamFileToolkit::LogEntry ( char const *  string) const

Writes a message into the log

◆ LogEntry() [2/2]

void BStreamFileToolkit::LogEntry ( __wchar_t const *  string) const

Writes a message into the log with wide characters

◆ MatchPreviousExRef()

virtual bool BStreamFileToolkit::MatchPreviousExRef ( ) const
inlinevirtual

Allows derived toolkits to process an external reference directly if it matches a previous one

Returns
true if the function matched and handled the reference, false if we need to try to read the reference

Reimplemented in HStreamFileToolkit.

◆ NewFileContext()

virtual void BStreamFileToolkit::NewFileContext ( ID_Key  key)
inlinevirtual

While processing External_References a previously visited context will be revisited. This method will be called by the default Read_Stream_File to indicate that context should be prepared to receive content, and should be overloaded to provide custom preparation. This might include operations such as clearing out any placeholder geometry.

Parameters
keyA context identifier

Reimplemented in HStreamFileToolkit.

◆ NextExternalReference()

bool BStreamFileToolkit::NextExternalReference ( )

Removes the current external reference and readies the next one (if any).

Returns
true if another external reference is present

◆ NextOpcodeSequence()

unsigned int BStreamFileToolkit::NextOpcodeSequence ( )
inline

internal use

Referenced by BBaseOpcodeHandler::PutOpcode().

◆ NextTagIndex()

int BStreamFileToolkit::NextTagIndex ( )
inline

Reserves & returns the next available tag index

Returns
The tag index.

◆ ObjectsSoFar()

unsigned int BStreamFileToolkit::ObjectsSoFar ( ) const
inline

Returns the number of objects that have been written since the beginning of the writing process. This is available to applications for estimation of writing progress if there is a means of estimating the total.

◆ OpenFile() [1/2]

virtual TK_Status BStreamFileToolkit::OpenFile ( char const *  name,
bool  write = false 
)
virtual

Opens a file. This acts as a simple wrapper for the 'fopen' command.

Parameters
nameThe name of the file to open.
writeTrue if the file is open for writing, otherwise, file is open for reading.
Returns
The result of function call.

◆ OpenFile() [2/2]

virtual TK_Status BStreamFileToolkit::OpenFile ( __wchar_t const *  name,
bool  write = false 
)
virtual

Opens a file. This acts as a simple wrapper for the 'fopen' command.

Parameters
nameThe name of the file to open.
writeTrue if the file is open for writing, otherwise, file is open for reading.
Returns
The result of function call.

◆ OpenGeometry()

virtual TK_Status BStreamFileToolkit::OpenGeometry ( )
inlinevirtual

Prepares the toolkit for dealing with geometry-level attributes

Returns
status of the request, error if a geometry is already open

References TK_Normal.

◆ OpenLogFile()

TK_Status BStreamFileToolkit::OpenLogFile ( char const *  filename,
char const *  mode 
)

Opens the log file for writing.

Parameters
filenamethe name of the file to be opened as a log
modepassed through to fopen
Returns
TK_Error on failure

◆ ParseBuffer()

virtual TK_Status BStreamFileToolkit::ParseBuffer ( char const *  b,
int  s,
TK_Status  mode = TK_Normal 
)
virtual

ParseBuffer reads the opcode at the start of the binary data buffer and continually calls the Read method of the associated opcode handler. The Read methods of the default object handlers read binary information from the buffer that was passed in and convert it into HOOPS/3dGS formatted segment, geometry and attribute information. After the opcode handler reports that reading is complete, ParseBuffer calls the Execute method of the opcode handler.
If the HOOPS/3dGS-specific opcode handlers are being used (the HoopsStream classes, of the form HTK_XXX) then the Execute methods will call the appropriate HOOPS/3dGS functions to either create segemnts, insert geometry or set attributes underneath the currently open HOOPS/3dGS segment. When using HoopsStream, a HOOPS/3dGS scene-graph segment must currently be open before calling ParseBuffer.

If the HOOPS/3dGS-independent default object handlers are used (the BaseStream classes, of the form TK_XXX), then the Execute method does nothing and the developer would need to overload it to map the HSF data to custom data structures.

If the buffer being parsed ends in the middle of an object, it will be saved along with any HOOPS database state information and the next buffer will be appended to it.

The mode parameter allows for control of how the buffer is parsed. The default of TK_Normal indicates read until the Termination code.
TK_Pause indicates read to the next Pause or Termination. If the HOOPS Stream File has been written out with default streaming properties, a pause will occur at the end of the HOOPS segment tree. This tree contains simple bounding box representations for the HOOPS geometric primitives that are used to represent facetted surfaces.

TK_Single indicates read only the first object in the buffer. If the buffer ends in the middle of an object, it will be saved and the next buffer will be appended to it. Any extra data in the buffer than is associated with more than one object is thrown away. This is referred to as 'a la carte mode', and is useful when the application wants specific entities to be read in from the file, typically from random locations. This is necessary for image sweetening.

Parameters
bA pointer to a character buffer.
sAn integer denoting the length of the buffer.
modeA flag controlling how the buffer is to be parsed.
Returns
The result of the function call.

◆ ParseVersion()

static int BStreamFileToolkit::ParseVersion ( char const *  block)
static

ParseVersion attempts to read a given block as a header to extract the file version

Parameters
blockA pointer to a character buffer.
Returns
the version number if the block starts with ";; HSF V", otherwise 0

◆ PeekTagIndex()

int BStreamFileToolkit::PeekTagIndex ( ) const
inline

Returns the next available tag index without reserving it for use

Returns
The tag index.

◆ PositionFile()

virtual TK_Status BStreamFileToolkit::PositionFile ( int  offset)
virtual

Utility function which repositions the current file pointer. This acts a wrapper for fseek, and is used by LocateDictionary and LocateEntity, but might be reimplemented by classes derived from BStreamFileToolkit to perform custom file repositioning.

Parameters
offsetIf positive, repositions the file pointer to offset bytes from the beginning of the file, otherwise repositions the file pointer to offset bytes from the end of the file.
Returns
The result of function call.

◆ PrepareBuffer()

TK_Status BStreamFileToolkit::PrepareBuffer ( char *  b,
int  s 
)

Tells the toolkit where to begin writing data.

Parameters
bA character pointer denoting the buffer to write into.
sSize of the buffer

◆ Read_Stream_File()

TK_Status BStreamFileToolkit::Read_Stream_File ( )

Reads the file associated with the toolkit (internal utility).

Returns
The result of the function call.

◆ ReadBuffer()

virtual TK_Status BStreamFileToolkit::ReadBuffer ( char *  buffer,
int  size,
int &  amount_read 
)
virtual

Reads a buffer of data to the file associated with the BStreamFileToolkit object. This acts as a simple wrapper for the 'fread' command.

Parameters
bufferCharacter buffer used to store the data being read.
sizeInteger denoting amount of data to read.
amount_readThe amount of data actually read into the buffer.
Returns
The result of function call.

◆ RecordPause()

void BStreamFileToolkit::RecordPause ( int  offset)

Record a pause at the given file offset

Parameters
offsetFile offset of this pause

◆ RemoveSegment()

ID_Key BStreamFileToolkit::RemoveSegment ( )

Removes the most currently "openned" segment

Returns
the key of the segment which was removed

◆ ReportQuantizationError() [1/2]

void BStreamFileToolkit::ReportQuantizationError ( float  error)
inline

Intended primarily for use by opcode handlers, this function sets m_quantization_error to error if it is the largest error seen so far.

◆ ReportQuantizationError() [2/2]

void BStreamFileToolkit::ReportQuantizationError ( int  bits_per_sample,
float const *  bounding,
int  num_dimensions = 3 
)

Intended primarily for use by opcode handlers, this function calculates the longest dimension cell size and uses that as an upper bound on quantization error for a call to ReportQuantizationError

◆ ResetQuantizationError()

void BStreamFileToolkit::ResetQuantizationError ( )
inline

resets the quantization error back to zero

◆ Restart()

virtual void BStreamFileToolkit::Restart ( )
virtual

Initializes the file toolkit. This is useful if a single toolkit object is to be used for dealing with different files, rather than deleting the current toolkit object and creating a new instance. Call this function after processing of the current file is complete.

Reimplemented in HStreamFileToolkit.

◆ SelectFile() [1/2]

TK_Status BStreamFileToolkit::SelectFile ( char const *  name)

[Re]Selects a previously accessed file for further processing

Parameters
nameThe name of the file.
Returns
TK_Normal if the file was found and selected, TK_NotFound otherwise.

◆ SelectFile() [2/2]

TK_Status BStreamFileToolkit::SelectFile ( __wchar_t const *  name)

[Re]Selects a previously accessed file for further processing

Parameters
nameThe Unicode name of the file.
Returns
TK_Normal if the file was found and selected, TK_NotFound otherwise.

◆ SetAsciiMode()

TK_Status BStreamFileToolkit::SetAsciiMode ( bool  whether)

Ascii is a deprecated mode. DO NOT USE.

◆ SetBufferLimit()

void BStreamFileToolkit::SetBufferLimit ( int  limit)
inline

Sets the progress passthrough value

References TK_DEFAULT_BUFFER_SIZE.

◆ SetDictionaryFormat()

void BStreamFileToolkit::SetDictionaryFormat ( int  format = 3,
int  options = TK_Dictionary_Bounding_Volumes 
)
inline

Sets the desired dictionary format level and options

Parameters
formatThe desried dictionary format
optionsBitmask of any options that many modify a specific format

◆ SetDictionaryOffset()

void BStreamFileToolkit::SetDictionaryOffset ( int  offset)
inline

Sets (records) the dictionary offset

Parameters
offsetThe dictionary offset

◆ SetDictionarySize()

void BStreamFileToolkit::SetDictionarySize ( int  size)
inline

Sets (records) the dictionary size

Parameters
sizeThe dictionary size

◆ SetFilename() [1/2]

void BStreamFileToolkit::SetFilename ( char const *  name)

Sets the starting filename for the toolkit (normally used internally).

Parameters
nameThe name of the file.

◆ SetFilename() [2/2]

void BStreamFileToolkit::SetFilename ( __wchar_t const *  name)

Sets the starting filename for the toolkit (normally used internally).

Parameters
nameThe name of the file.

◆ SetFirstPause()

void BStreamFileToolkit::SetFirstPause ( int  offset)
inline

supported for older code

◆ SetFlags()

void BStreamFileToolkit::SetFlags ( int  flags)
inline

Deprecated; Use SetWriteFlags; Sets the toolkit writing flags.

◆ SetJpegQuality()

void BStreamFileToolkit::SetJpegQuality ( int  quality = 75)
inline

Sets the quality level for JPEG compression, range is 0-100, 0 disables, 75 by default

◆ SetLastKey()

void BStreamFileToolkit::SetLastKey ( ID_Key  key)

Reports to the toolkit the identifier of the last object processed

◆ SetLogFile()

void BStreamFileToolkit::SetLogFile ( char const *  filename = 0)

Sets the name of the log file

◆ SetLogging()

void BStreamFileToolkit::SetLogging ( bool  setting)
inline

Sets the logging state. If true, the toolkit will output files called hsf_export_log.txt and hsf_import_log.txt which contain a byte representing each opcode that was exported or imported. during the write and/or read phase, respectively.

◆ SetLoggingOptions()

void BStreamFileToolkit::SetLoggingOptions ( unsigned int  options = ~0)
inline

Sets the logging options. controls the types of logging information collected.

◆ SetNewFile() [1/2]

void BStreamFileToolkit::SetNewFile ( char const *  name)

Associates a new filename with the toolkit.

Parameters
nameThe name of the file.

◆ SetNewFile() [2/2]

void BStreamFileToolkit::SetNewFile ( __wchar_t const *  name)

Associates a new Unicode filename with the toolkit.

Parameters
nameThe name of the file.

◆ SetNumColorBits()

void BStreamFileToolkit::SetNumColorBits ( int  numbits)
inline

Sets the maximum number of bits to use for vertex colors

◆ SetNumIndexBits()

void BStreamFileToolkit::SetNumIndexBits ( int  numbits)
inline

Sets the maximum number of bits to use for vertex colors-by-index

◆ SetNumNormalBits()

void BStreamFileToolkit::SetNumNormalBits ( int  numbits)
inline

Sets the maximum number of bits that will be used per normal (x,y, and z combined). The default is 10 (for the entire normal). Opcode handlers may, at their option, decide to use less

◆ SetNumParameterBits()

void BStreamFileToolkit::SetNumParameterBits ( int  numbits)
inline

Sets the number of bits per sample for vertex parameters (texture coordinates). For backwards compatibility it is specified as 3 times the number (previous versions of the stream toolkit specified the number of bits for the entire parameter, but always assumed 3 parameters (u,v,w) per vertex). Thus, for example, if you specify '24' bits, a 1d texture will have 8 bits total, a 2d texture will have 16, and a 3d texture will have 24.

◆ SetNumVertexBits()

void BStreamFileToolkit::SetNumVertexBits ( int  numbits)
inline

Sets the maximum number of bits to use for vertex locations (x,y, and z combined). Default is 24.

◆ SetOpcodeHandler()

void BStreamFileToolkit::SetOpcodeHandler ( int  which,
BBaseOpcodeHandler handler 
)

Registers an opcode handler for the specified type, allowing for variations on normal processing of HOOPS Stream Metafile objects, or handling of user-defined binary objects.

Parameters
whichThe type of binary object to associated the opcode handler with.
handlerA pointer to an BBaseOpcodeHandler object.

◆ SetOpcodeSequence()

void BStreamFileToolkit::SetOpcodeSequence ( unsigned int  seq = 0)
inline

internal use

◆ SetPostwalkHandler()

void BStreamFileToolkit::SetPostwalkHandler ( BBaseOpcodeHandler handler)

Registers an opcode handler which will be called by the toolkit after it processes (walks and imports/exports) the HOOPS segment tree. This allows the user to import/export user-specified data from/to the HOOPS Stream File, at a location following the segment tree information. objects, or handling of user-defined binary objects.

Parameters
handlerA pointer to an BBaseOpcodeHandler object.

◆ SetPrewalkHandler()

void BStreamFileToolkit::SetPrewalkHandler ( BBaseOpcodeHandler handler)

Registers an opcode handler which will be called by the toolkit before it processes (walks and imports/exports) the HOOPS segment tree. This allows the user to import/export user-specified data from/to the HOOPS Stream File, at a location prior to the segment tree information. objects, or handling of user-defined binary objects.

Parameters
handlerA pointer to an BBaseOpcodeHandler object.

◆ SetProgressCallback()

void BStreamFileToolkit::SetProgressCallback ( TK_Progress_Callback  cb = 0)
inline

Sets the progress callback

◆ SetProgressValue()

void BStreamFileToolkit::SetProgressValue ( void *  value)
inline

Sets the progress passthrough value

◆ SetReadFlags()

void BStreamFileToolkit::SetReadFlags ( int  flags)
inline

Sets the toolkit reading flags. These flags control various import properties, and are defined in TK_File_Read_Options

◆ SetReadVersion()

void BStreamFileToolkit::SetReadVersion ( int  version)
inline

for reading embedded hsf data for which format version is externally available.

◆ SetTargetVersion()

void BStreamFileToolkit::SetTargetVersion ( int  version)
inline

This method sets the file format version desired for writing. The default value for the target version is the most recent version in the File Version table.

Parameters
versionThe HSF file version you are writing out. For instance, to export a v15.00 HSF File, pass 1500.

References TK_File_Format_Version.

◆ SetWorldBounding()

void BStreamFileToolkit::SetWorldBounding ( float const  bbox[])

Sets the global bounding box to be used for bounding box aggegation. This is utilized when the TK_Global_Quantization bit of TK_File_Write_Options is set

Parameters
bboxpointer to the bounding box coordinates

◆ SetWorldBoundingBySphere()

void BStreamFileToolkit::SetWorldBoundingBySphere ( float const  pt[],
float  radius 
)

Sets the global bounding box (by sphere) be used for bounding box aggegation. This is utilized when the TK_Global_Quantization bit of TK_File_Write_Options is set

Parameters
ptcenter point of sphere
radiusradius of sphere

◆ SetWriteFlags()

void BStreamFileToolkit::SetWriteFlags ( int  flags)
inline

Sets the toolkit writing flags. These flags control a variety of export properties, and are defined in TK_File_Write_Options

◆ SupportsAsciiMode()

static bool BStreamFileToolkit::SupportsAsciiMode ( )
inlinestatic

Ascii is a deprecated mode. DO NOT USE.

◆ Unused()

int BStreamFileToolkit::Unused ( ) const
inline
Returns
the amount of data in the user's buffer left unused

◆ WriteBuffer()

virtual TK_Status BStreamFileToolkit::WriteBuffer ( char *  buffer,
int  size 
)
virtual

Writes a buffer of data to the file associated with the BStreamFileToolkit object. This acts as a simple wrapper for the 'fwrite' command.

Parameters
bufferCharacter buffer to be written out.
sizeInteger denoting amount of data to write.
Returns
The result of function call.

Member Data Documentation

◆ m_file

void* BStreamFileToolkit::m_file
protected

Pointer to the file associated with the BStreamFileToolkit object


The documentation for this class was generated from the following file: