class RED::IStream

Interface that exposes stream I/O methods. More...

#include <REDIStream.h>

Inherits: IREDObject.

Public functions:

virtual RED_RC	Close ( ) = 0
virtual const void *	GetAddress ( ) const = 0
virtual RED_RC	GetCurrentPosition ( RED::uint64 & oPosition ) const = 0
virtual LoadChunkNotificationCallback	GetLoadChunkNotificationCallback ( ) const = 0
virtual const RED::String &	GetPath ( ) const = 0
virtual RED_RC	IsEnd ( bool & oEnd ) const = 0
virtual bool	IsOpen ( ) const = 0
virtual RED_RC	JumpToNextChunk ( ) = 0
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
virtual RED_RC	MemorySize ( RED::uint64 & oSize ) const = 0
virtual RED_RC	Move ( RED::int64 iPosition, bool iRelative = false ) = 0
virtual RED_RC	Open ( ACCESS_MODE iAccessMode ) = 0
virtual RED_RC	ReadByte ( unsigned char & oByte ) = 0
virtual RED_RC	ReadColor ( RED::Color & oColor ) = 0
virtual RED_RC	ReadData ( unsigned char * oData, RED::uint64 iDataLength ) = 0
virtual RED_RC	ReadData ( unsigned char * oData, RED::uint64 & oReadDataLength, RED::uint64 iDataLength ) = 0
virtual RED_RC	ReadDDWord ( RED::uint64 & oDDWord ) = 0
virtual RED_RC	ReadDFloat ( double & oDFloat ) = 0
virtual RED_RC	ReadDWord ( unsigned __int64 & oDWord ) = 0
virtual RED_RC	ReadDWord ( unsigned int & oDWord ) = 0
virtual RED_RC	ReadFloat ( float & oFloat ) = 0
virtual RED_RC	ReadLine ( RED::String & oString ) = 0
virtual RED_RC	ReadMatrix ( RED::Matrix & oMatrix, bool iDoublePrecision ) = 0
virtual RED_RC	ReadString ( RED::String & oString ) = 0
virtual RED_RC	ReadVector3 ( RED::Vector3 & oVector3, bool iDoublePrecision ) = 0
virtual RED_RC	ReadVector4 ( RED::Vector4 & oVector4, bool iDoublePrecision ) = 0
virtual RED_RC	ReadWord ( unsigned short & oWord ) = 0
virtual RED_RC	SaveChunk ( RED::Object * iObject, RED::StreamingPolicy & iPolicy ) = 0
virtual void	SetEncryptionKey ( const RED::String & iEncryptionKey ) = 0
virtual void	SetLoadChunkNotificationCallback ( LoadChunkNotificationCallback iCallback, void * iParameter = NULL ) = 0
virtual RED_RC	Size ( RED::uint64 & oSize ) const = 0
virtual RED_RC	WriteByte ( unsigned char iByte ) = 0
virtual RED_RC	WriteColor ( const RED::Color & iColor ) = 0
virtual RED_RC	WriteData ( const unsigned char * iData, RED::uint64 iDataLength ) = 0
virtual RED_RC	WriteData ( RED::IStream * iStream, RED::uint64 iSize = 0 ) = 0
virtual RED_RC	WriteDDWord ( RED::uint64 iDDWord ) = 0
virtual RED_RC	WriteDFloat ( double iDFloat ) = 0
virtual RED_RC	WriteDWord ( unsigned int iDWord ) = 0
virtual RED_RC	WriteFloat ( float iFloat ) = 0
virtual RED_RC	WriteMatrix ( const RED::Matrix & iMatrix, bool iDoublePrecision ) = 0
virtual RED_RC	WriteString ( const RED::String & iString, bool iBinaryMode = true ) = 0
virtual RED_RC	WriteVector3 ( const RED::Vector3 & iVector3, bool iDoublePrecision ) = 0
virtual RED_RC	WriteVector4 ( const RED::Vector4 & iVector4, bool iDoublePrecision ) = 0
virtual RED_RC	WriteWord ( unsigned short iWord ) = 0

Detailed description:

Interface that exposes stream I/O methods.

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: Creating RED streams

REDsdk provides an abstraction of the I/O devices called RED::IStream. By creating streams, you can redirect I/O operations either to files on disk or memory buffers. To create a stream, you must use the RED::Factory:

case of a memory stream

RED::Object* mem_stream = RED::Factory::CreateMemoryStream();

case of a file stream

RED::Object* file_stream = RED::Factory::CreateFileStream( "./my_file.red" );

After the stream creation, you can get access to its RED::IStream interface to start using it.

Functions documentation

public static RED::CID RED::IStream::GetClassID

(

)

public virtual RED_RC RED::IStream::Close

(

) = 0

Closes a previously opened stream.

Returns:

RED_OK on success,
RED_FAIL otherwise.

public virtual const void * RED::IStream::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.

public virtual RED_RC RED::IStream::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).

public virtual LoadChunkNotificationCallback RED::IStream::GetLoadChunkNotificationCallback

(

) const = 0

Gets the user callback set on chunk loading.

Returns:

A pointer to the user defined callback.

public virtual const RED::String & RED::IStream::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.

public virtual RED_RC RED::IStream::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.

public virtual bool RED::IStream::IsOpen

(

) const = 0

Gets the open status flag of a stream.

Returns:

true if the stream is open, false otherwise.

public virtual RED_RC RED::IStream::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.

public virtual RED_RC RED::IStream::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).

public virtual RED_RC RED::IStream::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.

public virtual RED_RC RED::IStream::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).

public virtual RED_RC RED::IStream::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.

public virtual RED_RC RED::IStream::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.

public virtual RED_RC RED::IStream::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.

public virtual RED_RC RED::IStream::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.

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::ReadDWord

(

unsigned __int64 &

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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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.

public virtual void RED::IStream::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.

public virtual void RED::IStream::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.

public virtual RED_RC RED::IStream::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.

public virtual RED_RC RED::IStream::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.

public virtual RED_RC RED::IStream::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:

iColor:

Color to write.

Returns:

public virtual RED_RC RED::IStream::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.

public virtual RED_RC RED::IStream::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.

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

iMatrix:	RED::Matrix to write.
iDoublePrecision:	Set the numerical accuracy of the written data. 'false' writes float values. 'true' writes double (DFloat) values.

Returns:

public virtual RED_RC RED::IStream::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:

public virtual RED_RC RED::IStream::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:

iVector3:	RED::Vector3 to write.
iDoublePrecision:	Set the numerical accuracy of the written data. 'false' writes float values. 'true' writes double (DFloat) values.

Returns:

public virtual RED_RC RED::IStream::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:

iVector4:	RED::Vector4 to write.
iDoublePrecision:	Set the numerical accuracy of the read data. 'false' reads float values. 'true' reads double (DFloat) values.

Returns:

public virtual RED_RC RED::IStream::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:

class RED::IStream

Public functions:

Public static functions:

Detailed description:

Task: Creating RED streams

Functions documentation