BStreamFileToolkit Class Reference

#include <BStreamFileToolkit.h>

Inheritance diagram for BStreamFileToolkit:

Inheritance graph
[legend]
Collaboration diagram for BStreamFileToolkit:

Collaboration graph
[legend]
List of all members.

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:

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.

Definition at line 333 of file BStreamFileToolkit.h.

Public Member Functions

 BStreamFileToolkit (void)
TK_Status SetAsciiMode (bool whether)
bool GetAsciiMode ()
int ParseVersion (char const *block) const
TK_Status ParseBuffer (char const *b, int s, TK_Status mode=TK_Normal) alter
TK_Status PrepareBuffer (char *b, int s) alter
int CurrentBufferLength ()
virtual void ActivateContext (ID_Key key)
virtual void DeactivateContext (ID_Key key)
virtual void NewFileContext (ID_Key key)
int GeneratedSoFar (void) const
unsigned int ObjectsSoFar (void) const
void SetOpcodeHandler (int which, BBaseOpcodeHandler *handler) alter
void SetPrewalkHandler (BBaseOpcodeHandler *handler) alter
void SetPostwalkHandler (BBaseOpcodeHandler *handler) alter
BBaseOpcodeHandlerGetOpcodeHandler (int which) const
virtual void Restart (void) alter
TK_Status IndexToKey (int index, ID_Key alter &key) const
TK_Status KeyToIndex (ID_Key key, int alter &index) const
TK_Status AddIndexKeyPair (int index, ID_Key key) alter
TK_Status AddVariant (ID_Key key, int variant, int value1, int value2=-1) alter
TK_Status AddBounds (ID_Key key, float const *bounds) alter
TK_Status GetOffset (ID_Key key, int variant, int alter &offset) const
TK_Status GetOffset (ID_Key key, int variant, int alter &offset, int alter &length) const
TK_Status GetOffset (ID_Key key, int variant, int alter &offset, int alter &length, char const *alter &filename) const
TK_Status GetBounds (ID_Key key, float alter *bounds) const
int NextTagIndex (void) alter
int PeekTagIndex (void) const
void SetFilename (char const *name) alter
void SetFilename (unsigned short const *name) alter
TK_Status Read_Stream_File (void)
void SetNewFile (char const *name) alter
char const * GetCurrentFile (void) const
TK_Status SelectFile (char const *name) alter
virtual TK_Status OpenFile (char const *name, bool write=false) alter
virtual TK_Status OpenFile (unsigned short const *name, bool write=false) alter
virtual TK_Status CloseFile (void) alter
virtual TK_Status ReadBuffer (char alter *buffer, int size, int alter &amount_read) alter
virtual TK_Status WriteBuffer (char alter *buffer, int size) alter
virtual TK_Status PositionFile (int offset) alter
virtual TK_Status GetFileSize (unsigned long &size) alter
virtual TK_Status LocateDictionary (void) alter
virtual TK_Status LocateEntity (ID_Key key, int variant) alter
int GetFlags (void) const
void SetFlags (int flags) alter
void SetWriteFlags (int flags) alter
int GetWriteFlags (int mask=~0) const
void SetReadFlags (int flags) alter
int GetReadFlags (int mask=~0) const
int GetNumNormalBits (void) const
void SetNumNormalBits (int numbits) alter
int GetNumVertexBits (void) const
void SetNumVertexBits (int numbits) alter
int GetNumParameterBits (void) const
void SetNumParameterBits (int numbits) alter
int GetNumColorBits (void) const
void SetNumColorBits (int numbits) alter
int GetNumIndexBits (void) const
void SetNumIndexBits (int numbits) alter
void SetJpegQuality (int quality=75) alter
int GetJpegQuality (void) const
int GetVersion (void) const
void SetTargetVersion (int version) alter
int GetTargetVersion (void) const
unsigned int GetFileOffset (void) 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).
void SetFileOffset (unsigned int offset) alter
 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).
int Unused (void) const
virtual TK_Status Error (char const *msg=0) const
char const * GetLogFile (void) const
void SetLogFile (char const *filename=0) alter
bool GetLogging (void) const
void SetLogging (bool setting) alter
unsigned int GetLoggingOptions (unsigned int mask=~0) const
void SetLoggingOptions (unsigned int options=~0) alter
TK_Status OpenLogFile (char const *filename, char const *mode) alter
void LogEntry (char const *string) alter
void LogEntry (unsigned short const *string) alter
void CloseLogFile (void) alter
unsigned int NextOpcodeSequence (void) alter
void SetOpcodeSequence (unsigned int seq=0) alter
bool HeaderCommentSeen (void) const
TK_Progress_Callback GetProgressCallback (void) const
void SetProgressCallback (TK_Progress_Callback cb=0) alter
void * GetProgressValue (void) const
void SetProgressValue (void *value) alter
int GetBufferLimit (void) const
void SetBufferLimit (int limit) alter
void SetLastKey (ID_Key key) alter
TK_Status AppendLastKey (ID_Key key) alter
void ClearLastKey () alter
TK_Status GetLastKey (ID_Key &key) const
void SetDictionaryFormat (int format=3, int options=TK_Dictionary_Bounding_Volumes) alter
int GetDictionaryFormat (void) const
int GetDictionaryOptions (void) const
void SetDictionaryOffset (int offset) alter
int GetDictionaryOffset (void) const
void SetDictionarySize (int size) alter
int GetDictionarySize (void) const
void RecordPause (int offset) alter
void ClearPauses (void) alter
int GetPauseCount (void) const
int const * GetPauseTable (void) const
void SetFirstPause (int offset) alter
int GetFirstPause (void) const
int GetPosition (void) const
void SetWorldBounding (float const *bbox)
void SetWorldBoundingBySphere (float const *pt, float radius)
float const * GetWorldBounding () const
void AddExternalReference (char const *ref, ID_Key context) alter
bool NextExternalReference (void) alter
char const * GetExternalReference (void) const
ID_Key GetExternalReferenceContext (void) const
void AddSegment (ID_Key key) alter
ID_Key RemoveSegment (void) alter
ID_Key CurrentSegment (void) alter
void ResetQuantizationError ()
void ReportQuantizationError (float error)
void ReportQuantizationError (int bits_per_sample, float const *bounding, int num_dimensions=3)
float GetQuantizationError () const
TK_Status OpenGeometry (void) alter
TK_Status CloseGeometry (void) alter
bool GeometryIsOpen (void) const

Static Public Member Functions

static bool SupportsAsciiMode (void)

Protected Attributes

void * m_file
DWFInputStream_pInputStream

Friends

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


Constructor & Destructor Documentation

BStreamFileToolkit::BStreamFileToolkit void   ) 
 

Default constructor for an BStreamFileToolkit object


Member Function Documentation

virtual void BStreamFileToolkit::ActivateContext ID_Key  key  )  [inline, virtual]
 

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:
key A context identifier

Definition at line 541 of file BStreamFileToolkit.h.

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

Records the bounding volume associated with a previously recorded object.

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

Definition at line 652 of file BStreamFileToolkit.h.

void BStreamFileToolkit::AddExternalReference char const *  ref,
ID_Key  context
 

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

Parameters:
ref external reference string
context external reference context

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:
index An integer denoting a file index.
key The HOOPS key that to associate with the specified index.
Returns:
The result of the function call.

Definition at line 632 of file BStreamFileToolkit.h.

void BStreamFileToolkit::AddSegment ID_Key  key  ) 
 

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

Parameters:
key of segment being openned

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:
key The HOOPS key of the object
variant The variant (LOD number) being recorded
value1 The file offset of the start of the variant
value2 The size of the variant
Returns:
The result of the function call.

Definition at line 643 of file BStreamFileToolkit.h.

TK_Status BStreamFileToolkit::AppendLastKey ID_Key  key  ) 
 

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

void BStreamFileToolkit::ClearLastKey  ) 
 

Clears identifier of the last object processed

void BStreamFileToolkit::ClearPauses void   )  [inline]
 

Clears the pause table

Definition at line 1022 of file BStreamFileToolkit.h.

virtual TK_Status BStreamFileToolkit::CloseFile void   )  [virtual]
 

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

Returns:
The result of function call.

TK_Status BStreamFileToolkit::CloseGeometry void   )  [inline]
 

Completes dealing with geometry-level attributes

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

Definition at line 1123 of file BStreamFileToolkit.h.

void BStreamFileToolkit::CloseLogFile void   ) 
 

Closes the log file

int BStreamFileToolkit::CurrentBufferLength  )  [inline]
 

Returns how much of the internal data buffer is currently filled

Definition at line 533 of file BStreamFileToolkit.h.

ID_Key BStreamFileToolkit::CurrentSegment void   )  [inline]
 

Returns the key of the currently "open" segment

Returns:
key of the current segment

Definition at line 1095 of file BStreamFileToolkit.h.

virtual void BStreamFileToolkit::DeactivateContext ID_Key  key  )  [inline, virtual]
 

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:
key A context identifier

Definition at line 548 of file BStreamFileToolkit.h.

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

int BStreamFileToolkit::GeneratedSoFar void   )  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.

Definition at line 564 of file BStreamFileToolkit.h.

bool BStreamFileToolkit::GeometryIsOpen void   )  const [inline]
 

Queries the state of geometry-level attribute handling

Returns:
whether geometry-level handling is active

Definition at line 1133 of file BStreamFileToolkit.h.

bool BStreamFileToolkit::GetAsciiMode  ) 
 

Gets current ASCII Mode of toolkit

TK_Status BStreamFileToolkit::GetBounds ID_Key  key,
float alter *  bounds
const [inline]
 

Returns the bounding volume associated with a previously recorded key.

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

Definition at line 694 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetBufferLimit void   )  const [inline]
 

Returns the progress passthrough value

Definition at line 960 of file BStreamFileToolkit.h.

char const* BStreamFileToolkit::GetCurrentFile void   )  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.

Definition at line 737 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetDictionaryFormat void   )  const [inline]
 

Returns the currently requested dictionary format level

Returns:
Dictionary format

Definition at line 987 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetDictionaryOffset void   )  const [inline]
 

Returns the recorded dictionary offset

Returns:
Dictionary offset

Definition at line 1002 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetDictionaryOptions void   )  const [inline]
 

Returns the options for the dictionary format.

Returns:
Dictionary options bitmask

Definition at line 992 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetDictionarySize void   )  const [inline]
 

Returns the recorded dictionary size

Returns:
Dictionary size

Definition at line 1012 of file BStreamFileToolkit.h.

char const* BStreamFileToolkit::GetExternalReference void   )  const [inline]
 

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

Returns:
external reference string

Definition at line 1074 of file BStreamFileToolkit.h.

ID_Key BStreamFileToolkit::GetExternalReferenceContext void   )  const [inline]
 

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

Returns:
external reference context

Definition at line 1080 of file BStreamFileToolkit.h.

virtual TK_Status BStreamFileToolkit::GetFileSize unsigned long &  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:
size reference to the variable to receive the file size.
Returns:
The result of function call.

int BStreamFileToolkit::GetFirstPause void   )  const [inline]
 

supported for older code

Definition at line 1038 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetFlags void   )  const [inline]
 

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

Definition at line 844 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetJpegQuality void   )  const [inline]
 

Returns the current JPEG quality setting

Definition at line 892 of file BStreamFileToolkit.h.

TK_Status BStreamFileToolkit::GetLastKey ID_Key &  key  )  const
 

Returns identifier of the last object processed

char const* BStreamFileToolkit::GetLogFile void   )  const [inline]
 

Returns the name of the log file

Definition at line 911 of file BStreamFileToolkit.h.

bool BStreamFileToolkit::GetLogging void   )  const [inline]
 

Returns the logging state

Definition at line 916 of file BStreamFileToolkit.h.

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

Returns the logging options

Definition at line 923 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetNumColorBits void   )  const [inline]
 

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

Definition at line 884 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetNumIndexBits void   )  const [inline]
 

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

Definition at line 886 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetNumNormalBits void   )  const [inline]
 

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

Definition at line 867 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetNumParameterBits void   )  const [inline]
 

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

Definition at line 878 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetNumVertexBits void   )  const [inline]
 

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

Definition at line 875 of file BStreamFileToolkit.h.

TK_Status BStreamFileToolkit::GetOffset ID_Key  key,
int  variant,
int alter &  offset,
int alter &  length,
char const *alter &  filename
const
 

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

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

TK_Status BStreamFileToolkit::GetOffset ID_Key  key,
int  variant,
int alter &  offset,
int alter &  length
const [inline]
 

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

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

Definition at line 673 of file BStreamFileToolkit.h.

TK_Status BStreamFileToolkit::GetOffset ID_Key  key,
int  variant,
int alter &  offset
const [inline]
 

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

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

Definition at line 662 of file BStreamFileToolkit.h.

BBaseOpcodeHandler* BStreamFileToolkit::GetOpcodeHandler int  which  )  const [inline]
 

Returns:
A pointer to the requested opcode handler

Definition at line 600 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetPauseCount void   )  const [inline]
 

Returns the number of pauses recorded

Returns:
The number of pauses

Definition at line 1027 of file BStreamFileToolkit.h.

int const* BStreamFileToolkit::GetPauseTable void   )  const [inline]
 

Returns the pause offsets

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

Definition at line 1032 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetPosition void   )  const [inline]
 

Returns the current file position

Definition at line 1043 of file BStreamFileToolkit.h.

TK_Progress_Callback BStreamFileToolkit::GetProgressCallback void   )  const [inline]
 

Returns the progress callback

Definition at line 950 of file BStreamFileToolkit.h.

void* BStreamFileToolkit::GetProgressValue void   )  const [inline]
 

Returns the progress passthrough value

Definition at line 955 of file BStreamFileToolkit.h.

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.

Definition at line 1109 of file BStreamFileToolkit.h.

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:
mask of flags to be returned (default is all).
Returns:
The result of function call.

Definition at line 864 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetTargetVersion void   )  const [inline]
 

Returns the file format version desired for writing

Definition at line 897 of file BStreamFileToolkit.h.

int BStreamFileToolkit::GetVersion void   )  const [inline]
 

Returns the file format version during reading

Definition at line 894 of file BStreamFileToolkit.h.

float const* BStreamFileToolkit::GetWorldBounding  )  const [inline]
 

Returns:
the world bounding box

Definition at line 1059 of file BStreamFileToolkit.h.

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:
mask of flags to be returned (default is all).
Returns:
The result of function call.

Definition at line 855 of file BStreamFileToolkit.h.

bool BStreamFileToolkit::HeaderCommentSeen void   )  const [inline]
 

Returns true if the header comment has been processed

Definition at line 947 of file BStreamFileToolkit.h.

TK_Status BStreamFileToolkit::IndexToKey int  index,
ID_Key alter &  key
const
 

Calculates the HOOPS key associated with the specified index.

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

TK_Status BStreamFileToolkit::KeyToIndex ID_Key  key,
int alter &  index
const
 

Calculates the index associated with the specified HOOPS key.

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

virtual TK_Status BStreamFileToolkit::LocateDictionary void   )  [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.

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:
key The key of a HOOPS entity.
variant The variant of the HOOPS entity to locate. 0 represents the full representation, 1 represents LOD level 1, etc....
Returns:
The result of function call.

void BStreamFileToolkit::LogEntry unsigned short const *  string  ) 
 

Writes a message into the log with wide characters

void BStreamFileToolkit::LogEntry char const *  string  ) 
 

Writes a message into the log

virtual void BStreamFileToolkit::NewFileContext ID_Key  key  )  [inline, virtual]
 

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:
key A context identifier

Definition at line 557 of file BStreamFileToolkit.h.

bool BStreamFileToolkit::NextExternalReference void   ) 
 

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

Returns:
true if another external reference is present

unsigned int BStreamFileToolkit::NextOpcodeSequence void   )  [inline]
 

internal use

Definition at line 942 of file BStreamFileToolkit.h.

int BStreamFileToolkit::NextTagIndex void   )  [inline]
 

Reserves & returns the next available tag index

Returns:
The tag index.

Definition at line 701 of file BStreamFileToolkit.h.

unsigned int BStreamFileToolkit::ObjectsSoFar void   )  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.

Definition at line 570 of file BStreamFileToolkit.h.

virtual TK_Status BStreamFileToolkit::OpenFile unsigned short const *  name,
bool  write = false
[virtual]
 

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

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

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:
name The name of the file to open.
write True if the file is open for writing, otherwise, file is open for reading.
Returns:
The result of function call.

TK_Status BStreamFileToolkit::OpenGeometry void   )  [inline]
 

Prepares the toolkit for dealing with geometry-level attributes

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

Definition at line 1114 of file BStreamFileToolkit.h.

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

Opens the log file for writing.

Parameters:
filename the name of the file to be opened as a log
mode passed through to fopen
Returns:
TK_Error on failure

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

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:
b A pointer to a character buffer.
s An integer denoting the length of the buffer.
mode A flag controlling how the buffer is to be parsed.
Returns:
The result of the function call.

int BStreamFileToolkit::ParseVersion char const *  block  )  const
 

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

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

int BStreamFileToolkit::PeekTagIndex void   )  const [inline]
 

Returns the next available tag index without reserving it for use

Returns:
The tag index.

Definition at line 706 of file BStreamFileToolkit.h.

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:
offset If 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.

TK_Status BStreamFileToolkit::PrepareBuffer char *  b,
int  s
 

Tells the toolkit where to begin writing data.

Parameters:
b A character pointer denoting the buffer to write into.
s Size of the buffer

TK_Status BStreamFileToolkit::Read_Stream_File void   ) 
 

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

Returns:
The result of the function call.

virtual TK_Status BStreamFileToolkit::ReadBuffer char alter *  buffer,
int  size,
int alter &  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:
buffer Character buffer used to store the data being read.
size Integer denoting amount of data to read.
amount_read The amount of data actually read into the buffer.
Returns:
The result of function call.

void BStreamFileToolkit::RecordPause int  offset  ) 
 

Record a pause at the given file offset

Parameters:
offset File offset of this pause

ID_Key BStreamFileToolkit::RemoveSegment void   ) 
 

Removes the most currently "openned" segment

Returns:
the key of the segment which was removed

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

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.

Definition at line 1101 of file BStreamFileToolkit.h.

void BStreamFileToolkit::ResetQuantizationError  )  [inline]
 

resets the quantization error back to zero

Definition at line 1097 of file BStreamFileToolkit.h.

virtual void BStreamFileToolkit::Restart void   )  [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.

TK_Status BStreamFileToolkit::SelectFile char const *  name  ) 
 

[Re]Selects a previously accessed file for further processing

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

TK_Status BStreamFileToolkit::SetAsciiMode bool  whether  ) 
 

Sets toolkit into ASCII Mode

void BStreamFileToolkit::SetBufferLimit int  limit  )  [inline]
 

Sets the progress passthrough value

Definition at line 962 of file BStreamFileToolkit.h.

void BStreamFileToolkit::SetDictionaryFormat int  format = 3,
int  options = TK_Dictionary_Bounding_Volumes
[inline]
 

Sets the desired dictionary format level and options

Parameters:
format The desried dictionary format
options Bitmask of any options that many modify a specific format

Definition at line 981 of file BStreamFileToolkit.h.

void BStreamFileToolkit::SetDictionaryOffset int  offset  )  [inline]
 

Sets (records) the dictionary offset

Parameters:
offset The dictionary offset

Definition at line 997 of file BStreamFileToolkit.h.

void BStreamFileToolkit::SetDictionarySize int  size  )  [inline]
 

Sets (records) the dictionary size

Parameters:
size The dictionary size

Definition at line 1007 of file BStreamFileToolkit.h.

void BStreamFileToolkit::SetFilename unsigned short const *  name  ) 
 

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

Parameters:
name The name of the file.

void BStreamFileToolkit::SetFilename char const *  name  ) 
 

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

Parameters:
name The name of the file.

void BStreamFileToolkit::SetFirstPause int  offset  )  [inline]
 

supported for older code

Definition at line 1035 of file BStreamFileToolkit.h.

void BStreamFileToolkit::SetFlags int  flags  )  [inline]
 

Deprecated; Use SetWriteFlags; Sets the toolkit writing flags.

Definition at line 845 of file BStreamFileToolkit.h.

void BStreamFileToolkit::SetJpegQuality int  quality = 75  )  [inline]
 

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

Definition at line 890 of file BStreamFileToolkit.h.

void BStreamFileToolkit::SetLastKey ID_Key  key  ) 
 

Reports to the toolkit the identifier of the last object processed

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

Sets the name of the log file

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.

Definition at line 920 of file BStreamFileToolkit.h.

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

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

Definition at line 926 of file BStreamFileToolkit.h.

void BStreamFileToolkit::SetNewFile char const *  name  ) 
 

Associates a new filename with the toolkit.

Parameters:
name The name of the file.

void BStreamFileToolkit::SetNumColorBits int  numbits  )  [inline]
 

Sets the maximum number of bits to use for vertex colors

Definition at line 885 of file BStreamFileToolkit.h.

void BStreamFileToolkit::SetNumIndexBits int  numbits  )  [inline]
 

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

Definition at line 887 of file BStreamFileToolkit.h.

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

Definition at line 873 of file BStreamFileToolkit.h.

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.

Definition at line 883 of file BStreamFileToolkit.h.

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.

Definition at line 877 of file BStreamFileToolkit.h.

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:
which The type of binary object to associated the opcode handler with.
handler A pointer to an BBaseOpcodeHandler object.

void BStreamFileToolkit::SetOpcodeSequence unsigned int  seq = 0  )  [inline]
 

internal use

Definition at line 944 of file BStreamFileToolkit.h.

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:
handler A pointer to an BBaseOpcodeHandler object.

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:
handler A pointer to an BBaseOpcodeHandler object.

void BStreamFileToolkit::SetProgressCallback TK_Progress_Callback  cb = 0  )  [inline]
 

Sets the progress callback

Definition at line 952 of file BStreamFileToolkit.h.

void BStreamFileToolkit::SetProgressValue void *  value  )  [inline]
 

Sets the progress passthrough value

Definition at line 957 of file BStreamFileToolkit.h.

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

Definition at line 858 of file BStreamFileToolkit.h.

void BStreamFileToolkit::SetTargetVersion int  version  )  [inline]
 

Sets the file format version desired for writing

Definition at line 896 of file BStreamFileToolkit.h.

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:
bbox pointer to the bounding box coordinates

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:
pt center point of sphere
radius radius of sphere

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

Definition at line 849 of file BStreamFileToolkit.h.

static bool BStreamFileToolkit::SupportsAsciiMode void   )  [inline, static]
 

Sets toolkit into ASCII Mode

Definition at line 459 of file BStreamFileToolkit.h.

int BStreamFileToolkit::Unused void   )  const [inline]
 

Returns:
the amount of data in the user's buffer left unused

Definition at line 904 of file BStreamFileToolkit.h.

virtual TK_Status BStreamFileToolkit::WriteBuffer char alter *  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:
buffer Character buffer to be written out.
size Integer denoting amount of data to write.
Returns:
The result of function call.


Member Data Documentation

void* BStreamFileToolkit::m_file [protected]
 

Pointer to the file associated with the BStreamFileToolkit object

Definition at line 445 of file BStreamFileToolkit.h.


The documentation for this class was generated from the following file:
Generated on Tue Jan 6 22:41:39 2009 for Autodesk DWF 3D Toolkit by  doxygen 1.4.5