IStream

Functions

SET_CID

RED_RC

Open

bool

IsOpen

RED_RC

Close

RED_RC

Size

RED_RC

MemorySize

RED_RC

IsEnd

const String &

GetPath

const void *

GetAddress

RED_RC

Move

RED_RC

GetCurrentPosition

RED_RC

SaveChunk

RED_RC

LoadChunk

RED_RC

JumpToNextChunk

void

SetLoadChunkNotificationCallback

LoadChunkNotificationCallback

GetLoadChunkNotificationCallback

RED_RC

WriteByte

RED_RC

ReadByte

RED_RC

WriteWord

RED_RC

ReadWord

RED_RC

WriteDWord

RED_RC

ReadDWord

RED_RC

ReadDWord

RED_RC

WriteDDWord

RED_RC

ReadDDWord

RED_RC

WriteFloat

RED_RC

ReadFloat

RED_RC

WriteDFloat

RED_RC

ReadDFloat

RED_RC

WriteString

RED_RC

ReadString

RED_RC

ReadLine

RED_RC

WriteVector3

RED_RC

ReadVector3

RED_RC

WriteVector4

RED_RC

ReadVector4

RED_RC

WriteMatrix

RED_RC

ReadMatrix

RED_RC

WriteColor

RED_RC

ReadColor

RED_RC

WriteData

RED_RC

WriteData

RED_RC

ReadData

RED_RC

ReadData

void

SetEncryptionKey

Detailed Description

class IStream : public RED::IREDObject

Interface that exposes stream I/O methods.

@related class RED::IREDFile

This interface exposes all the needed method to read from or write to streams. They can be either file or memory streams.

Streams can be used to load .red files (see the RED::IREDFile::Load method for further details).

\task tk_creating_red_streams

Public Functions

SET_CID(CID_class_REDIStream)
virtual RED_RC Open(ACCESS_MODE iAccessMode) = 0

Opens a stream using the given access mode.

Parameters

iAccessMode – One of the available access mode.

Returns

RED_OK on success,

RED_ACCESS_DENIED when the file could not be accessed with the requested rights (for a file stream),

RED_FILE_NOT_FOUND when the file could not be found (for a file stream),

RED_FAIL otherwise.

virtual bool IsOpen() const = 0

Gets the open status flag of a stream.

Returns

true if the stream is open, false otherwise.

virtual RED_RC Close() = 0

Closes a previously opened stream.

Returns

RED_OK on success,

RED_FAIL otherwise.

virtual RED_RC Size(RED::uint64 &oSize) const = 0

Gets the current size of the stream in bytes.

If the stream has not been opened prior to the call, oSize is set to 0 and the method returns RED_OK.

For a file stream, this is the total size of the file.

For a memory stream, this is the currently used size in the stream.

Parameters

oSize – Reference to the returned size of the stream.

Returns

RED_OK on success,

RED_FAIL otherwise.

virtual RED_RC MemorySize(RED::uint64 &oSize) const = 0

Gets the current allocated size in a memory stream in bytes.

If the stream has not been opened prior to the call, oSize is set to 0 and the method returns RED_OK.

For a file stream, this is the total size of the file.

For a memory stream, this is the currently allocated memory size in the stream. The memory size may be larger than the actually used

RED::IStream::Size in the stream.

Parameters

oSize – Reference to the returned memory size of the stream.

Returns

RED_OK on success,

RED_FAIL otherwise.

virtual RED_RC IsEnd(bool &oEnd) const = 0

Returns true if the end of the stream is reached, false otherwise.

If the stream has not been opened prior to the call, oEnd is set to true and the method returns RED_OK.

Parameters

oEnd – Reference to the returned flag.

Returns

RED_OK on success,

RED_FAIL otherwise.

virtual const RED::String &GetPath() const = 0

Gets the path to the stream.

For a file disk stream, the method returns the path to the file. For a memory stream, the returned path is empty.

Returns

the path to the stream.

virtual const void *GetAddress() const = 0

Gets the base memory address of the stream.

For a file disk stream, the method returns NULL. For a memory stream, the returned address is the base memory address of the stream.

Returns

the address of the stream.

virtual RED_RC Move(RED::int64 iPosition, bool iRelative = false) = 0

Moves the current stream position at the given location.

The given location can be expressed either relative to the stream start or to the current position.

Parameters
  • iPosition – new position inside the stream.

  • iRelative – flag indicating if the new position must be taken relative to the current stream position (=true) or to the stream start (=false). Default is false (the new position is expressed from the stream start).

Returns

RED_OK on success,

RED_FAIL otherwise (new position is invalid).

virtual RED_RC GetCurrentPosition(RED::uint64 &oPosition) const = 0

Gets the current position inside the stream.

If the stream has not been opened prior to the call, oPosition is set to 0 and the method returns RED_OK;

Parameters

oPosition – Reference to the returned position.

Returns

RED_OK on success,

RED_FAIL otherwise (new position is invalid).

virtual RED_RC SaveChunk(RED::Object *iObject, RED::StreamingPolicy &iPolicy) = 0

Writes a chunk to the stream.

This method will fail if the given object does not implement the RED::IChunkSaver interface.

If the object relies on dependencies, it’s the object responsibility to save all its dependencies too.

Parameters
  • iObject – Pointer to the RED::Object to save.

  • iPolicy – Reference to the policy to be used for streaming.

Returns

RED_OK on success,

RED_BAD_PARAM if iObject is an invalid pointer or if iObject does not implement the

RED::IChunkSaver

interface,

RED_FILE_WRITE_ERROR on file write error (for a file stream),

RED_FAIL otherwise.

virtual RED_RC LoadChunk(RED::IReferenceManager *iReferenceManager, const RED::StreamingPolicy &iPolicy, const RED::State &iState, RED::Object **oChunk, unsigned int *oSignature = NULL, RED::uint64 *oSize = NULL) = 0

Loads a chunk from the stream. This method will succeed if the current position into the stream points to a chunk start.

Call this method only on streams pointing to data in .red format.

If the call fails, the current stream position is not modified. On success, the stream position is updated to point right after the last chunk byte in the stream. Note that if you pass pointers to retrieve chunk signature, chunk size or both, the info will be filled even if the chunk is unknown.

Parameters
  • iReferenceManager – Pointer to a RED::IReferenceManager interface implementation. This interface will be used to register references for future pending references solving.

  • iPolicy – Policy to be used to interpret the chunk content.

  • iState – Current transaction parameter.

  • oChunk – Pointer to the loaded chunk address. Default is NULL.

  • oSignature – Optional pointer to the returned chunk signature. Default is NULL.

  • oSize – Optional pointer to the returned chunk size.

Returns

RED_OK on success (the address of the loaded chunk is copied into oChunk),

RED_BAD_PARAM if oChunk is an invalid pointer,

RED_FILE_DATA_ERROR on a file read error,

RED_END_OF_STREAM on an unexpected end of stream,

RED_ALLOC_FAILURE on a memory allocation error,

RED_UNKNOWN_CHUNK on a unsupported chunk,

RED_INIT_FAILED if the render was not initialized,

RED_FAIL otherwise (unknown chunk for example).

virtual RED_RC JumpToNextChunk() = 0

Moves the current stream position to the start of the next chunk.

This method is meangingful only for streams pointing to data in .red format. This should never be used for streams of other types.

Returns

RED_OK on success,

RED_FILE_DATA_ERROR on a file read error,

RED_END_OF_STREAM on an unexpected end of stream,

RED_FAIL otherwise.

virtual void SetLoadChunkNotificationCallback(LoadChunkNotificationCallback iCallback, void *iParameter = NULL) = 0

Sets a user callback that will be called each time a chunk is successfully loaded.

This callback will receive the size of the loaded chunk in parameter. This information is useful to display a progress indicator.

Parameters
  • iCallback – Pointer to the user callback.

  • iParameter – Pointer to a custom parameter that will be passed to the callback. Default is NULL.

virtual LoadChunkNotificationCallback GetLoadChunkNotificationCallback() const = 0

Gets the user callback set on chunk loading.

Returns

A pointer to the user defined callback.

virtual RED_RC WriteByte(unsigned char iByte) = 0

Writes a byte to the stream and increment the current stream position by 1.

If the stream has not been allocated with sufficient size, it is automatically expanded to receive the given data.

Parameters

iByte – byte to write.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC ReadByte(unsigned char &oByte) = 0

Reads a byte from the stream and increment the current stream position by 1.

Parameters

oByte – reference to the read byte.

Returns

RED_OK on success,

RED_FILE_DATA_ERROR on file read error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC WriteWord(unsigned short iWord) = 0

Writes a word to the stream and increment the current stream position by 2.

If the stream has not been allocated with sufficient size, it is automatically expanded to receive the given data.

Parameters

iWord – word to write.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC ReadWord(unsigned short &oWord) = 0

Reads a word from the stream and increment the current stream position by 2.

Parameters

oWord – reference to the read word.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC WriteDWord(unsigned int iDWord) = 0

Writes a double word to the stream and increment the current stream position by 4.

If the stream has not been allocated with sufficient size, it is automatically expanded to receive the given data.

Parameters

iDWord – double word to write.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC ReadDWord(unsigned int &oDWord) = 0

Reads a double word from the stream and increment the current stream position by 4.

Parameters

oDWord – reference to the read double word.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC ReadDWord(RED::uint64 &oDWord) = 0

Reads a double word from the stream and increment the current stream position by 4.

Parameters

oDWord – reference to the read double word.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC WriteDDWord(RED::uint64 iDDWord) = 0

Writes a 64 bits value to the stream and increment the current stream position by 8.

If the stream has not been allocated with sufficient size, it is automatically expanded to receive the given data.

Note that on a 32bit system, this method will write iDWord in the first 32 bits of the 
stream and write 0 in the following other 32 bits.

Parameters

iDDWord – double word to write.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC ReadDDWord(RED::uint64 &oDDWord) = 0

Reads a 64 bits value from the stream and increment the current stream position by 8.

Note that on a 32bit system, this method will return the first 32 bits of the stream as an unsigned int stored in oDWord and discard the following other 32 bits.

Parameters

oDDWord – reference to the read double word.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC WriteFloat(float iFloat) = 0

Writes a float to the stream and increment the current stream position by 4.

If the stream has not been allocated with sufficient size, it is automatically expanded to receive the given data.

Parameters

iFloat – float to write.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC ReadFloat(float &oFloat) = 0

Reads a float from the stream and increment the current stream position by 4.

Parameters

oFloat – reference to the read float.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC WriteDFloat(double iDFloat) = 0

Writes a double float to the stream and increment the current stream position by 8.

If the stream has not been allocated with sufficient size, it is automatically expanded to receive the given data.

Parameters

iDFloat – double float to write.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC ReadDFloat(double &oDFloat) = 0

Reads a double float from the stream and increment the current stream position by 8.

Parameters

oDFloat – reference to the read double float.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC WriteString(const RED::String &iString, bool iBinaryMode = true) = 0

Writes a string to the stream and increment the current stream position by 2 * length of the string (including the terminal zeros).

If the stream has not been allocated with sufficient size, it is automatically expanded to receive the given data.

Parameters
  • iString – string to write.

  • iBinaryMode – true to write a terminal zero after the string, false otherwise. When outputing to a text file, the iBinaryMode parameter should be set to false to produce correct files.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC ReadString(RED::String &oString) = 0

Reads a string from the stream and increment the current stream position by 2 * length of the string (including the terminal zeros).

Characters are read from the stream until a ‘\0’ character is encountered.

Note

This method is not suitable to read strings from a text stream as they do not end with a terminal zero. Prefer the use of RED::IStream::ReadLine in that case.

Parameters

oString – reference to the read string.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC ReadLine(RED::String &oString) = 0

Reads a string from the stream and increment the current stream position by 2 * length of the string.

Characters are read from the stream until a ‘

’ character is encountered.

Parameters

oString – reference to the read string.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC WriteVector3(const RED::Vector3 &iVector3, bool iDoublePrecision) = 0

Writes a RED::Vector3 to the stream and increment the current stream position.

The stream position is incremented by 3 * sizeof( float ) if iDoublePrecision is false or by 3 * sizeof( double ) if iDoublePrecision is true.

If the stream has not been allocated with sufficient size, it is automatically expanded to receive the given data.

Parameters
  • iVector3RED::Vector3 to write.

  • iDoublePrecision – Set the numerical accuracy of the written data. ‘false’ writes float values. ‘true’ writes double (DFloat) values.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC ReadVector3(RED::Vector3 &oVector3, bool iDoublePrecision) = 0

Reads a RED::Vector3 from the stream and increment the current stream position.

The stream position is incremented by 3 * sizeof( float ) if iDoublePrecision is false or by 3 * sizeof( double ) if iDoublePrecision is true.

Parameters
  • oVector3 – reference to the read RED::Vector3.

  • iDoublePrecision – Set the numerical accuracy of the read data. ‘false’ reads float values. ‘true’ reads double (DFloat) values.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC WriteVector4(const RED::Vector4 &iVector4, bool iDoublePrecision) = 0

Writes a RED::Vector3 to the stream and increment the current stream position.

The stream position is incremented by 4 * sizeof( float ) if iDoublePrecision is false or by 4 * sizeof( double ) if iDoublePrecision is true.

If the stream has not been allocated with sufficient size, it is automatically expanded to receive the given data.

Parameters
  • iVector4RED::Vector4 to write.

  • iDoublePrecision – Set the numerical accuracy of the read data. ‘false’ reads float values. ‘true’ reads double (DFloat) values.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC ReadVector4(RED::Vector4 &oVector4, bool iDoublePrecision) = 0

Reads a RED::Vector4 from the stream and increment the current stream position.

The stream position is incremented by 4 * sizeof( float ) if iDoublePrecision is false or by 4 * sizeof( double ) if iDoublePrecision is true.

Parameters
  • oVector4 – reference to the read RED::Vector4.

  • iDoublePrecision – Set the numerical accuracy of the read data. ‘false’ reads float values. ‘true’ reads double (DFloat) values.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC WriteMatrix(const RED::Matrix &iMatrix, bool iDoublePrecision) = 0

Writes a RED::Matrix to the stream and increment the current stream position.

The stream position is incremented by 16 * sizeof( float ) if iDoublePrecision is false or by 16 * sizeof( double ) if iDoublePrecision is true.

If the stream has not been allocated with sufficient size, it is automatically expanded to receive the given data.

Parameters
  • iMatrixRED::Matrix to write.

  • iDoublePrecision – Set the numerical accuracy of the written data. ‘false’ writes float values. ‘true’ writes double (DFloat) values.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC ReadMatrix(RED::Matrix &oMatrix, bool iDoublePrecision) = 0

Reads a RED::Matrix from the stream and increment the current stream position.

The stream position is incremented by 16 * sizeof( float ) if iDoublePrecision is false or by 16 * sizeof( double ) if iDoublePrecision is true.

Parameters
  • oMatrix – reference to the read RED::Matrix.

  • iDoublePrecision – Set the numerical accuracy of the read data. ‘false’ reads float values. ‘true’ reads double (DFloat) values.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC WriteColor(const RED::Color &iColor) = 0

Writes a Color to the stream and increment the current stream position by 16.

If the stream has not been allocated with sufficient size, it is automatically expanded to receive the given data.

Parameters

iColorColor to write.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC ReadColor(RED::Color &oColor) = 0

Reads a Color from the stream and increment the current stream position by 16.

Parameters

oColor – reference to the read Color.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC WriteData(const unsigned char *iData, RED::uint64 iDataLength) = 0

Writes a data buffer of a given length to the stream.

If the stream has not been allocated with sufficient size, it is automatically expanded to receive the given data.

Parameters
  • iData – Pointer to the data buffer to be written.

  • iDataLength – Size of the data buffer.

Returns

RED_OK on success,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC WriteData(RED::IStream *iStream, RED::uint64 iSize = 0) = 0

Writes a stream content into our stream.

Parameters
  • iStream – Pointer to the source input stream to be written to us.

  • iSize – Optional size of the data to be written. Default is 0 (means whole stream is appended to this).

Returns

RED_OK on success,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_WRITE_ERROR on file write error,

RED_FAIL otherwise.

virtual RED_RC ReadData(unsigned char *oData, RED::uint64 iDataLength) = 0

Reads a data buffer of a given length from the stream.

Parameters
  • oData – Pointer to the returned read data buffer.

  • iDataLength – Size of the data buffer to be read.

Returns

RED_OK on success,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_DATA_ERROR on file read error,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual RED_RC ReadData(unsigned char *oData, RED::uint64 &oReadDataLength, RED::uint64 iDataLength) = 0

Reads data of unknown length from the stream.

Parameters
  • oData – Pointer to the returned read data buffer.

  • oReadDataLength – Size of the data effectively read (can be less than iDataLength if end of stream has been reached).

  • iDataLength – Max size of the data buffer to be read.

Returns

RED_OK on success,

RED_BAD_ACCESS_MODE if the stream has been opened in an incompatible access mode,

RED_FILE_DATA_ERROR on file read error,

RED_END_OF_STREAM if we read beyond the stream’s end,

RED_FAIL otherwise.

virtual void SetEncryptionKey(const RED::String &iEncryptionKey) = 0

Sets the key used for encryption/decryption.

After calling this method:

  • all the reading operations will decrypt the data using the given key,

  • all the writing operations will encrypt the data using the given key.

At any time, you can stop encryption/decryption operations by resetting the key to an empty key “”. By default, no encryption key is set for a new stream.

Parameters

iEncryptionKey – encryption/decryption key.