IStream
Functions
bool |
|
const String & |
|
const void * |
|
void |
|
LoadChunkNotificationCallback |
|
void |
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
-
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::IChunkSaverinterface,
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
iVector3 – RED::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
iVector4 – RED::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
iMatrix – RED::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
iColor – Color 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.
-
virtual RED_RC Open(ACCESS_MODE iAccessMode) = 0
