- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files
- Directories
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Protected Member Functions

# Stream Class Reference

This reference page is linked to from the following overview topics: Miscellaneous Utilities, Serializing Plug-in Data.

Search for all occurrences

## Detailed Description

Streams are used to read information from a file, or to write it to a file.

In a Mudbox plug-in, you would typically use the Stream class when you override the Serialize method of a custom node that you have derived from the Node class. When you save or load a scene, Mudbox will call that method and pass you a stream object, which you can then use.

Typically, a stream object is used like this:

            void myNode::Serialize( Stream& s )
            {
                myParentClass::Serialize(s);
                s == myVariable1 == myVariable2 == myVariable3;
            }

Here, the "==" operator will store the variables in the stream (if the stream is writing), or read them from the stream (if it is reading). So you can use the same code for both reading and writing. Since the "==" operator returns a stream reference, you can serialize multiple variables on the same line if you wish to do so, as shown above.

Examples:

  CurveBrush/CurveCreator.h, ImmediateModeRenderer/ImmediateModeRenderer.h, MeshDisplace/displacer.h, PtexExtractor/PtexLayout.h, and PtexExtractor/PtexUtilizer.h.

Definition at line 39 of file stream.h.

`#include <stream.h>`

Inheritance diagram for Stream:
[legend]

List of all members.

## Public Types
enum | { chunk = 0x800000 }
## Public Member Functions
virtual | ~Stream (void)
| Destructor.
virtual QString | FileName (void) const
| Returns the name of the file.
virtual bool | IsValid (void)
| Returns true if the stream has a valid version number.
virtual bool | IsOlderThan (int iVersion) const
| (Deprecated) Checks if the file is older than a specified version.
virtual bool | IsNewerThan (int iVersion) const
| (Deprecated) Checks if the file is newer than a specified version.
virtual int | ClassVersion (const class ClassDesc *pClass) const
| Returns the version for a class inside the current stream.
template<typename Type >
bool | IsOlderThan (int iVersion, Type *) const
| Checks if the file is older than a specified version for the given class.
template<typename Type >
bool | IsNewerThan (int iVersion, Type *) const
| Checks if the file is newer than a specified version for the given class.
virtual bool | IsStoring (void) const
| Returns true if the stream is in storing mode (i.e.
virtual void | SetError (bool bError)
| Use this method to inform Mudbox that there is an error in the stream you are trying to read or write.
virtual int | Version (void) const
| Returns the version number of the stream.
virtual uint64 | CurrentPosition (void) const
| Returns the current position in the file. See also SetCurrentPosition().
virtual void | SetCurrentPosition (uint64 iPosition)
| Sets the current position in the file.
virtual void | ReportCorruption (void)
| Call this function from your Serialize implementation, if you detect that the file content is corrupt.
virtual void | Open (const QString &sFileName, bool bStoring=false, int iProjectedFileSize=0, bool bProgressBar=true)
| Opens the file attached to this stream.
virtual void | Reopen (bool bStoring=false)
| Re-opens the file attached to this stream.
virtual bool | Close (void)
| Closes the file attached to this stream.
virtual bool | Eof (void)
| Returns true if you are reading the file, and you have reached the end of it.
virtual bool | ReadContents (void)
| This function reads the content of the stream into the memory, when the stream is opened for read.
virtual size_t | Read (void *pBuffer, size_t iSize)
| Reads data directly from the stream into a buffer you provide.
virtual size_t | Write (const void *pBuffer, size_t iSize)
| Writes data to the stream from a buffer you provide.
int | ReadInt (void)
| Reads a single integer from the stream, and returns it.
virtual void | ReadToFile (const QString &sFile)
| Takes the entire contents of the stream and writes it into the specified file.
virtual void | WriteFromFile (const QString &sFile)
| Fills the stream with the content of the specified file.
template<typename type >
Stream & | operator>> (type &v)
| Reads data from the stream to any data type.
template<typename type >
Stream & | operator<< (const type &v)
| Stores any data type into the stream.
virtual Node * | ReadPointer (void)
| Read/Writes node pointers.
virtual void | WritePointer (Node *pPointer)
template<typename type >
Stream & | operator>> (type *&p)
| Reads a pointer from the file.
template<typename type >
Stream & | operator<< (type *&p)
| Writes a pointer into the stream.
template<typename type >
Stream & | operator>> (Store< type > &s)
| Reads data from the stream to any Store (array) type.
template<typename type >
Stream & | operator<< (const Store< type > &s)
| Writes any store type (array) to the stream.
Stream & | operator>> (QString &s)
| Read/Writes QString.
Stream & | operator<< (const QString &s)
template<typename type >
Stream & | operator>> (QVector< type > &s)
| Reads data from the stream to a QVector object.
template<typename type >
Stream & | operator<< (const QVector< type > &s)
| Writes any store type (array) to the stream.
## Protected Member Functions
| Stream (void)
| You cannot create a Stream object directly. Call CreateInstance<Stream>(), then use Stream::Open to specify parameters.

## Member Enumeration Documentation

anonymous enum

Search for all occurrences

Enumerator:

  chunk | Search for all occurrences

Definition at line 47 of file stream.h.

    { chunk = 0x800000 };

## Constructor & Destructor Documentation

Stream | ( | void |  | ) | `[protected]`

You cannot create a Stream object directly. Call CreateInstance<Stream>(), then use Stream::Open to specify parameters.

virtual ~Stream | ( | void |  | ) | `[virtual]`

Destructor.

## Member Function Documentation

virtual QString FileName | ( | void |  | ) | const `[virtual]`

Search for all occurrences

Returns the name of the file.

virtual bool IsValid | ( | void |  | ) | `[virtual]`

Search for all occurrences

Returns true if the stream has a valid version number.

When Mudbox creates a new stream for writing, it gives the stream its version number. Similarly, if a stream is opened for reading, it has a version number. This method checks to see if the number is valid.

The version number can be invalid if there is a problem with the file, or if the file was saved in a newer version of Mudbox, and you are trying to read it into an older version.

virtual bool IsOlderThan | ( | int | iVersion | ) | const `[virtual]`

Search for all occurrences

(Deprecated) Checks if the file is older than a specified version.

Returns true if it is.

Typically this method is used during Serialize to handle changes to the file format between versions of the software. This function is deprecated. Use the class specific one with the same name instead.

Parameters:

  [in] | iVersion | The version number you want to compare

virtual bool IsNewerThan | ( | int | iVersion | ) | const `[virtual]`

Search for all occurrences

(Deprecated) Checks if the file is newer than a specified version.

Returns true if it is, false if it is not. Typically this method is used during Serialize() to handle changes to the file format between versions of the software. This function is deprecated. Use the class specific one with the same name instead.

Parameters:

  [in] | iVersion | The version number you want to compare

virtual int ClassVersion | ( | const class ClassDesc * | pClass | ) | const `[virtual]`

Search for all occurrences

Returns the version for a class inside the current stream.

This function returns the version number which was used for a class when the stream was created. If the stream is a storing stream, then this number equals to the current version of the class.

bool IsOlderThan | ( | int | iVersion,
|  | Type * |
| ) |  | const `[inline]`

Search for all occurrences

Checks if the file is older than a specified version for the given class.

Returns true if it is.

Typically this method is used during Serialize to handle changes to the file format between versions of the software.

Normally, you call this function within your Serialize implementation, something like this:

     if ( s.IsOlderThan( 5, this );

In this example the specified version number (5) is a local version number to your class, while the second parameter just identifies the class where you are calling the function. See the macro IMPLEMENT_SCLASS for more details.

Parameters:

  [in] | iVersion | The version number you want to compare

Definition at line 103 of file stream.h.

                                 { return ClassVersion( Type::StaticClass() ) < iVersion; };

bool IsNewerThan | ( | int | iVersion,
|  | Type * |
| ) |  | const `[inline]`

Search for all occurrences

Checks if the file is newer than a specified version for the given class.

Returns true if it is, false if it is not. Typically this method is used during Serialize() to handle changes to the file format between versions of the software.

Normally, you call this function within your Serialize implementation, something like this:

     if ( s.IsNewerThan( 4, this );

In this example the specified version number (4) is a local version number to your class, while the second parameter just identifies the class where you are calling the function. See the macro IMPLEMENT_SCLASS for more details.

Parameters:

  [in] | iVersion | The version number you want to compare

Definition at line 121 of file stream.h.

                                 { return ClassVersion( Type::StaticClass() ) > iVersion; };

virtual bool IsStoring | ( | void |  | ) | const `[virtual]`

Search for all occurrences

Returns true if the stream is in storing mode (i.e.

writing a file), and false if it is in reading mode.

virtual void SetError | ( | bool | bError | ) | `[virtual]`

Search for all occurrences

Use this method to inform Mudbox that there is an error in the stream you are trying to read or write.

virtual int Version | ( | void |  | ) | const `[virtual]`

Search for all occurrences

Returns the version number of the stream.

Reimplemented from Node.

virtual uint64 CurrentPosition | ( | void |  | ) | const `[virtual]`

Search for all occurrences

Returns the current position in the file. See also SetCurrentPosition().

virtual void SetCurrentPosition | ( | uint64 | iPosition | ) | `[virtual]`

Search for all occurrences

Sets the current position in the file.

Further calls to the stream will serialize from the new location. You can use this to skip over data in the file that you don't currently need.

Parameters:

  [in] | iPosition | The byte address to jump to

virtual void ReportCorruption | ( | void |  | ) | `[virtual]`

Search for all occurrences

Call this function from your Serialize implementation, if you detect that the file content is corrupt.

This function will throw an exception, so don't expect it to return. This call basically cancels the serialization of the current node and will try to step to the next one.

virtual void Open | ( | const QString & | sFileName,
|  | bool | bStoring = `false`,
|  | int | iProjectedFileSize = `0`,
|  | bool | bProgressBar = `true`
| ) |  | `[virtual]`

Search for all occurrences

Opens the file attached to this stream.

After creating a Stream object, this is the first function you normally call, which initializes the stream.

Parameters:

  [in] | sFileName | The name of the file to be opened
  [in] | bStoring | Set this to true if you are storing data (i.e. writing the file), and false otherwise
  [in] | iProjectedFileSize | If you know how big your file will be, you can optionally specify this argument to help display the status bar correctly
  [in] | bProgressBar | If true, a progress bar will be displayed while reading and writing the file.

virtual void Reopen | ( | bool | bStoring = `false` | ) | `[virtual]`

Search for all occurrences

Re-opens the file attached to this stream.

Parameters:

  [in] | bStoring | If true, open the file for writing. If false, open it for reading.

virtual bool Close | ( | void |  | ) | `[virtual]`

Search for all occurrences

Closes the file attached to this stream.

Returns true if the operation succeed.

This function is automatically called when the stream object is deleted. You can call this function directly before destructing the stream object, if you want to know about any corruption during writing, in which case this function returns false.

virtual bool Eof | ( | void |  | ) | `[virtual]`

Search for all occurrences

Returns true if you are reading the file, and you have reached the end of it.

virtual bool ReadContents | ( | void |  | ) | `[virtual]`

Search for all occurrences

This function reads the content of the stream into the memory, when the stream is opened for read.

This function is called automatically when the first pointer is serialized from the stream. You can directly call this function right after opening the stream, if you would like to know if the stream is loaded properly, or corruption was detected.

virtual size_t Read | ( | void * | pBuffer,
|  | size_t | iSize
| ) |  | `[virtual]`

Search for all occurrences

Reads data directly from the stream into a buffer you provide.

This method returns the number of bytes that were successfully transferred to the buffer. (This number can be different if there is an error, or if you reach the end of the file-- IS THIS TRUE?)

Parameters:

  [in] | pBuffer | A pointer to a block of memory to hold the data
  [in] | iSize | The number of bytes to be read

virtual size_t Write | ( | const void * | pBuffer,
|  | size_t | iSize
| ) |  | `[virtual]`

Search for all occurrences

Writes data to the stream from a buffer you provide.

Returns the number of bytes written.

Parameters:

  [in] | pBuffer | A pointer to a buffer of data you want to write
  [in] | iSize | The number of bytes you want to write

int ReadInt | ( | void |  | ) | `[inline]`

Search for all occurrences

Reads a single integer from the stream, and returns it.

Definition at line 204 of file stream.h.

    { int i=0; operator >>( i ); return i; };

virtual void ReadToFile | ( | const QString & | sFile | ) | `[virtual]`

Search for all occurrences

Takes the entire contents of the stream and writes it into the specified file.

Parameters:

  [in] | sFile | The name of the file that you want to store the stream data in

virtual void WriteFromFile | ( | const QString & | sFile | ) | `[virtual]`

Search for all occurrences

Fills the stream with the content of the specified file.

Parameters:

  [in] | sFile | The name of the file that you want the stream to get its data from.

Stream& operator>> | ( | type & | v | ) | `[inline]`

Reads data from the stream to any data type.

Definition at line 219 of file stream.h.

    { MB_VERIFY_EQ( Read( &v, sizeof(type) ), sizeof(type) ); return *this; };

Stream& operator<< | ( | const type & | v | ) | `[inline]`

Stores any data type into the stream.

Definition at line 223 of file stream.h.

    { MB_VERIFY_EQ( Write( &v, sizeof(type) ), sizeof(type) ); return *this; };

virtual Node* ReadPointer | ( | void |  | ) | `[virtual]`

Search for all occurrences

Read/Writes node pointers.

virtual void WritePointer | ( | Node * | pPointer | ) | `[virtual]`

Search for all occurrences

Stream& operator>> | ( | type *& | p | ) | `[inline]`

Reads a pointer from the file.

This function will serialize any pointer whose target is an object whose class was derived from the Node class. Other kind of pointers (like int*) cannot be serialized.

Definition at line 233 of file stream.h.

    { p = dynamic_cast<type *>( ReadPointer() ); return *this; };

Stream& operator<< | ( | type *& | p | ) | `[inline]`

Writes a pointer into the stream.

This function writes a pointer to the stream, if the pointer target is an object whose class was derived from the Node class. Other kind of pointers cannot be serialized.

Definition at line 240 of file stream.h.

    { WritePointer( p ); return *this; };

Stream & operator>> | ( | Store< type > & | s | ) | `[inline]`

Reads data from the stream to any Store (array) type.

Definition at line 303 of file stream.h.

    { unsigned int iSize; (*this) >> iSize; if ( o.SetItemCount( iSize ) && iSize ) Read( &(o[0]), sizeof(type)*iSize ); RegisterBlock( o.Name(), o.Size(), sizeof(type) ); return *this; };

Stream & operator<< | ( | const Store< type > & | s | ) | `[inline]`

Writes any store type (array) to the stream.

Definition at line 301 of file stream.h.

    { (*this) << o.ItemCount(); Write( &(o[0]), sizeof(type)*o.ItemCount() ); RegisterBlock( o.Name(), o.Size(), sizeof(type) ); return *this; };

Stream& operator>> | ( | QString & | s | ) |

Read/Writes QString.

Stream& operator<< | ( | const QString & | s | ) |

Stream& operator>> | ( | QVector< type > & | s | ) | `[inline]`

Reads data from the stream to a QVector object.

This function only works for arrays which contain simple objects only, which means the object has no pointers.

Definition at line 258 of file stream.h.

        {
            int iSize = ReadInt();
            s.resize( iSize );
            Read( s.data(), iSize*sizeof(type) );
            return *this;
        };

Stream& operator<< | ( | const QVector< type > & | s | ) | `[inline]`

Writes any store type (array) to the stream.

This function only works for arrays which contain simple objects only, which means the object has no pointers.

Definition at line 270 of file stream.h.

        {
            (*this) << s.size();
            Write( s.data(), s.size()*sizeof(type) );
            return *this;
        };

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

- Mudbox/stream.h

Stream Stream Stream Stream Stream Stream Stream Stream Stream Stream
Stream Stream Stream Stream Stream Stream Stream Stream Stream Stream