IREDFile

Detailed Description

class IREDFile : public RED::IREDObject 

Class used to load or save .red files.

An object implementing that interface is needed to load or to save .red files. The RED::Factory::CreateInstance method can be used to create an instance that implements the IREDFile interface. This is the CID_REDFile object.

Loading as well as saving a .red file must occur on the rendering thread.

.red files are made of chunks. A chunk is an atomic piece of RED data (can be an image or a triangle mesh for example). REDsdk supplies working chunks reader and writer for every built-in data type. As the chunk orientation is extensible, anyone can add his own types of chunk to the .red file format. Please, refer to the REDsdk “Programming guide” and to the various chunk classes documentations for further details about loadind, saving and extending .red files.

When you load .red files, you can encounter chunks for which you do not know any valid interpreter. In that case, it’s upon the loader responsibility to choose the appropriate action (see the RED::IREDFile::SetUnknownChunkPolicy method for explanations).

To save RED data to a .red file, simply add the following lines of code to your program:

(we assume that resmgr is a pointer to the instance of the RED resource manager and iresmgr is a pointer to an instance of RED::IResourceManager)

RED::Object* redfile = RED::Factory::CreateInstance( CID_REDFile );
RED::IREDFile* ifile = redfile->As< RED::IREDFile >();

if( ifile->Create( fileName, true ) == RED_OK )
{
  RED::StreamingPolicy policy;
  ifile->WriteDAG( dagRoot, policy, resmgr );
}
  
RED::Factory::DeleteInstance( redfile, iresmgr->GetState() ) );

To be exhaustive, you should also check the codes returned by the RED::IREDFile::WriteDAG and RED::FactoryDeleteInstance calls to capture every error that could occur.

This API can also be used to save encrypted data just by supplying an additional encryption key to the file creation method (RED::IREDFile::Create). To read an encrypted file, you need to know the exact key used for encryption (the key is not stored in the encrypted file). If you supply a wrong key at loading, you’ll get an error at an unpredictable time leading to more or less important memory leaks.

File encryption/decryption is not a very time consuming process and can be used even for very large files.

Public Functions

virtual RED_RC Create(const RED::String &iPath, bool iOverwrite = false, const RED::String &iEncryptionKey = "") = 0

Creates a .red file for writing/appending data.

If a file with the same path already exits, the encryption is activated based on the file header. If the file is encrypted, new data will be encrypted too using the given key. Otherwise, encryption will not be performed even if an encryption key has been supplied by the user.

Parameters

iPath – Path to the .red file.
iOverwrite – Optional flag indicating if an existing file should be overwritten (true) or not.
iEncryptionKey – Optional encryption key to use to encrypt file data. Default is “” (no encryption).

Returns

RED_OK on success,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL if the file exists and ‘iOverwrite’ is false,

Other file management RED_RC’s can be returned by the method.

virtual RED_RC Create(RED::Object *ioMemoryStream, bool iOverwrite = false, const RED::String &iEncryptionKey = "") = 0

Creates a .red stream file for writing/appending data.

The method is similar to RED::IREDFile::Create except that the target is the specified user memory stream.

Note that write calls that will follow may cause memory reallocations in ‘ioMemoryStream’ to occur if the stream was not created large enough to store all written chunks. Consequently, the base address of the memory stream may be moved after the reallocations.

Parameters

ioMemoryStream – The memory stream to write to.
iOverwrite – Optional flag indicating if an existing file should be overwritten (true) or or open to append new data (false).
iEncryptionKey – Optional encryption key to use to encrypt file data. Default is “” (no encryption).

Returns

RED_OK on success,

RED_BAD_PARAM if ‘iMemoryStream’ is not a memory stream,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

virtual RED_RC SetAuthor(const RED::String &iAuthor) = 0

Sets the author of the .red file.

The author information are stored in the RED::FileHeader chunk (Default value is “Techsoft3D”). This information must be filled BEFORE any call to RED::IREDFile::Create.

Parameters

iAuthor – String describing the .red file author.

Returns

RED_OK on success,

RED_FAIL otherwise.

virtual RED_RC SetParentApplication(const RED::String &iParentApplication) = 0

Sets the name of the .red file parent application.

The parent application information are stored in the RED::FileHeader chunk (Default value is “Redsdk”). This information must be filled BEFORE any call to RED::IREDFile::Create.

Parameters

iParentApplication – String describing the .red file parent application.

Returns

RED_OK on success,

RED_FAIL otherwise.

virtual RED_RC WriteFileInfo(const RED::FileInfo &iFileInfo) = 0

Writes some user’s info about the file’s content.

This file section stores various miscellaneous information about how the file’s content must be intepreted: animation frame rate, clipping plane values, ID of the default viewpoint

Parameters

iFileInfo – Reference to the file info object to be written.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_FILE_WRITE_ERROR on disk error,

RED_FAIL if the file has not been created for writing,

RED_FAIL otherwise.

virtual RED_RC WriteDAG(RED::Object *iObject, RED::StreamingPolicy &iPolicy, RED::Object *iResMgr, int iStateNumber = -1) = 0

Writes a DAG to a .red file.

The given object must implement the RED::IShape interface. All the children of the passed object are saved too (including their dependencies (materials, shaders, textures). To save the dynamic part of the model, use the REDREDFile::WriteDynamic method.

Parameters

iObject – Pointer to the root of the DAG to save.
iPolicy – Streaming policy defining how the chunks are streamed.
iResMgr – The cluster’s resource manager.
iStateNumber – Number of the transaction to export.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_FILE_WRITE_ERROR on disk error,

RED_FAIL if the file has not been created for writing,

RED_FAIL if iObject can’t be saved,

RED_FAIL otherwise.

virtual RED_RC WriteDynamic(unsigned int iFrame, RED::StreamingPolicy &iPolicy, RED::Object *iResMgr, int iStateNumber = -1) = 0

Writes the dynamic part of RED data.

The user must first call RED::IREDFile::WriteDAG prior to RED::IREDFile::WriteDynamic. RED::IREDFile::WriteDynamic filters the RED engine events to save only those affecting the data saved by RED::IREDFile::WriteDAG. So be careful of using the following sequence of calls:

WriteDAG( dag1 )  // save the dag1 data
WriteDynamic      // save the animation of dag1
WriteDAG( dag2 )  // save the dag2 data
WriteDynamic      // save the animation of dag2
// ...
WriteDAG( dagn )  // save the dagn data
WriteDynamic      // save the animation of dagn

Parameters

iFrame – Index of the frame being exported.
iPolicy – Streaming policy defining how the chunks are streamed.
iResMgr – The cluster’s resource manager.
iStateNumber – Number of the transaction to export. Default is -1 (last transaction).

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_FILE_WRITE_ERROR on disk error,

RED_FAIL otherwise.

virtual RED_RC Write(const RED::Object *iObject, RED::StreamingPolicy &iPolicy, RED::Object *iResMgr, int iStateNumber = -1) = 0

Writes a RED::Object instance into a .red file.

The passed object must implement the RED::IChunkSaver interface to be saved. Otherwise the method returns RED_FAIL.

Parameters

iObject – Pointer to the instance being saved.
iPolicy – Streaming policy defining how the chunks are streamed.
iResMgr – The cluster’s resource manager.
iStateNumber – Number of the transaction to export.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on memory allocation error,

RED_FILE_WRITE_ERROR on disk error,

RED_FAIL if the file has not been created for writing,

RED_FAIL if iObject can’t be saved,

RED_FAIL otherwise.

virtual RED_RC WriteShaderProgram(const RED::ShaderProgramID &iID, RED::StreamingPolicy &iPolicy, const RED::String &iShaderProgram, RED::Object *iResMgr, int iStateNumber = -1) = 0

Writes a shader program to a .red file.

All the shaders used by the data contained in the file must be written too. The shader programs are compressed and are therefore not readable when opening a .red file into a hexadecimal editor.

Parameters

iID – ID of the shader program (the one used in RED::IResourceManager).
iPolicy – Streaming policy defining how the chunks are streamed.
iShaderProgram – the shader program source code.
iResMgr – The cluster’s resource manager.
iStateNumber – Number of the transaction to export.

virtual RED_RC WriteAnimationTrackDescriptor(const RED::String &iTrackName) = 0

Writes info about the current animation track.

The data found after that descriptor will be considered as being parts of the same animation track until another descriptor is met.

Parameters

iTrackName – Name of the animation track.

Returns

RED_OK on success,

RED_FAIL otherwise.

virtual RED_RC WriteContext(unsigned int iContext, RED::StreamingPolicy &iPolicy, const RED::FileInfo &iFileInfo, RED::Object *iResMgr, const RED::State &iState) = 0

Writes the content of a context to a .red file.

After calling this method, the data are reset to their animation's first frame.

Parameters

iContext – Index of the context to save.
iPolicy – Streaming policy defining how the chunks are streamed.
iFileInfo – Read information on the context from the file informations.
iResMgr – The cluster’s resource manager.
iState – Current transaction.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid parameter,

RED_ALLOC_FAILURE on memory allocation error,

RED_FILE_WRITE_ERROR on disk error,

RED_FAIL otherwise.

virtual RED_RC WriteMaterial(RED::Object *iMaterial, RED::StreamingPolicy &iPolicy, RED::Object *iResMgr, int iStateNumber = -1) = 0

Writes a material to a .red file.

This is an helper to let you save RED materials very simply. It takes care of saving all the needed resources (shader programs, textures) along with the material.

Enable auto-saving of controllers (see RED::StreamingPolicy::SetMaterialControllerAutoSaving for details) to also automatically save the material controller if it exists.

Note that this method performs data caching for material resources, meaning that when two materials using a same texture are saved in a single file, the texture gets saved only once. However, calling this method twice with the same input material will still output the material twice to the file.

Parameters

iMaterial – pointer to the material to save.
iPolicy – Streaming policy defining how the chunks are streamed.
iResMgr – Pointer to the cluster resource manager.
iStateNumber – Number of the transaction to export (default is current transaction).

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid parameter,

RED_ALLOC_FAILURE on memory allocation error,

RED_FILE_WRITE_ERROR on disk error,

RED_FAIL otherwise.

virtual RED_RC Close() = 0

Closes a .red file on which the Create method has been called.

A .red file is automatically closed when its destructor is called.

Returns

RED_OK on success,

RED_FILE_WRITE_ERROR on disk error,

RED_FAIL otherwise.

virtual RED_RC Load(const RED::String &iPath, const RED::State &iState, RED::StreamingPolicy &iPolicy, RED::FileHeader &oHeader, RED::FileInfo &oInfo, RED::Vector<unsigned int> &oDataContext, unsigned int iDataContext = 0, const RED::String &iEncryptionKey = "", ProgressCallback iProgressCallback = NULL, void *iUserData = NULL) = 0

Loads a .red file from disk.

A .red file may have been encrypted using an encryption key. To know if a file is encrypted first call Load with no encryption key. If the return code is RED_ENCRYPTED_FILE, then the file is encrypted and you need to call Load again by supplying the correct encryption key.

A .red file may be loaded using a new data manager context, or using an existing data manager context. This is based on the value set for ‘iDataContext’. If ‘iDataContext’ is zero (default), then the method will create a new data context on the RED::DataManager and return it in ‘oDataContext’, otherwise the ‘iDataContext’ value will be used. All items loaded from the file will be registered using this context. Please note that in the case of a multiple animation tracks file each track is loaded using its own context. The number of items returned in ‘oDataContext’ is then the number of animation tracks found in the file plus one for the rest of the scene (static world + cameras). Loaded cameras can always be found by looking at the last data context returned.

The Load operation must be launched on the rendering thread.

Parameters

iPath – Complete path to the .red file.
iState – Current transaction parameter.
iPolicy – Policy to be applied while loading.
oHeader – .red file header content
oInfo – Miscellaneous file information.
oDataContext – Reference to the list of data context ID(s).
iDataContext – Data context id to use.
iEncryptionKey – Optional key used to encrypt the data.
iProgressCallback – Optional pointer to a user loading progression callback. The message set to the callback is the path to the file.
iUserData – Optional pointer to a user data associated to the progression callback.

Returns

RED_OK on success,

RED_ENCRYPTED_FILE if the file is encrypted and no encryption key is supplied,

RED_FILE_DATA_ERROR on file read error,

RED_END_OF_STREAM on an unexpected end of stream,

RED_ALLOC_FAILURE on memory allocation failure,

RED_FAIL otherwise. RED_FAIL may be returned for a variety of reasons, including an incorrect engine initialization, for example if no window has been created yet.

virtual RED_RC Load(RED::IStream &iStream, const RED::State &iState, RED::StreamingPolicy &iPolicy, RED::FileHeader &oHeader, RED::FileInfo &oInfo, RED::Vector<unsigned int> &oDataContext, unsigned int iDataContext = 0, const RED::String &iEncryptionKey = "", ProgressCallback iProgressCallback = NULL, void *iUserData = NULL) = 0

Loads a .red file from a stream.

The stream can be either a memory or a file stream.

If the stream is already opened, the current position inside it must be set to the first byte of the data. If the stream is not opened, it is automatically opened (and not closed) for reading.

Then, the size of the stream must be exactly the size of the file to read. It can’t be greater than the exact size to read, as the routine will try to read and understand the entire stream.

A .red file may have been encrypted using an encryption key. To know if a file is encrypted first call Load with no encryption key. If the return code is RED_ENCRYPTED_FILE, then the file is encrypted and you need to call Load again by supplying the correct encryption key.

A .red file may be loaded using a new data manager context, or using an existing data manager context. This is based on the value set for ‘iDataContext’. If ‘iDataContext’ is zero (default), then the method will create a new data context on the RED::DataManager and return it in ‘oDataContext’, otherwise the ‘iDataContext’ value will be used. All items loaded from the file will be registered using this context. Please note that in the case of a multiple animation tracks file each track is loaded using its own context. The number of items returned in ‘oDataContext’ is then the number of animation tracks found in the file plus one for the rest of the scene (static world + cameras). Loaded cameras can always be found by looking at the last data context returned.

The Load operation must be launched on the rendering thread.

Parameters

iStream – Reference to a stream pointing to data in .red format.
iState – Current transaction parameter.
iPolicy – Policy to be applied while loading.
oHeader – .red file header content
oInfo – Miscellaneous file information.
oDataContext – Reference to the list of data context ID(s).
iDataContext – Optionnally store the first read context using ‘iDataContext’.
iEncryptionKey – Optional key used to encrypt the data.
iProgressCallback – Optional pointer to a user loading progression callback.
iUserData – Optional pointer to a user data associated to the progression callback.

Returns

RED_OK on success,

RED_ENCRYPTED_FILE if the file is encrypted and no encryption key is supplied,

RED_FILE_DATA_ERROR on file read error,

RED_END_OF_STREAM on an unexpected end of stream,

RED_ALLOC_FAILURE on memory allocation failure,

RED_FAIL otherwise.

Public Static Functions

static inline RED::CID GetClassID()

CID	`GetClassID`
`RED_RC`	`Create`
`RED_RC`	`Create`
`RED_RC`	`SetAuthor`
`RED_RC`	`SetParentApplication`
`RED_RC`	`WriteFileInfo`
`RED_RC`	`WriteDAG`
`RED_RC`	`WriteDynamic`
`RED_RC`	`Write`
`RED_RC`	`WriteShaderProgram`
`RED_RC`	`WriteAnimationTrackDescriptor`
`RED_RC`	`WriteContext`
`RED_RC`	`WriteMaterial`
`RED_RC`	`Close`
`RED_RC`	`Load`
`RED_RC`	`Load`

IREDFile

Functions

Detailed Description