class RED::IREDFile

Class used to load or save .red files. More...

#include <REDIREDFile.h>

Inherits: IREDObject.

Public functions:

virtual RED_RC	Close ( ) = 0
virtual RED_RC	Create ( RED::Object * ioMemoryStream, bool iOverwrite = false, const RED::String & iEncryptionKey = "" ) = 0
virtual RED_RC	Create ( const RED::String & iPath, bool iOverwrite = false, const RED::String & iEncryptionKey = "" ) = 0
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
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
virtual RED_RC	SetAuthor ( const RED::String & iAuthor ) = 0
virtual RED_RC	SetParentApplication ( const RED::String & iParentApplication ) = 0
virtual RED_RC	Write ( const RED::Object * iObject, RED::StreamingPolicy & iPolicy, RED::Object * iResMgr, int iStateNumber = -1 ) = 0
virtual RED_RC	WriteAnimationTrackDescriptor ( const RED::String & iTrackName ) = 0
virtual RED_RC	WriteContext ( unsigned int iContext, RED::StreamingPolicy & iPolicy, const RED::FileInfo & iFileInfo, RED::Object * iResMgr, const RED::State & iState ) = 0
virtual RED_RC	WriteDAG ( RED::Object * iObject, RED::StreamingPolicy & iPolicy, RED::Object * iResMgr, int iStateNumber = -1 ) = 0
virtual RED_RC	WriteDynamic ( unsigned int iFrame, RED::StreamingPolicy & iPolicy, RED::Object * iResMgr, int iStateNumber = -1 ) = 0
virtual RED_RC	WriteFileInfo ( const RED::FileInfo & iFileInfo ) = 0
virtual RED_RC	WriteMaterial ( RED::Object * iMaterial, RED::StreamingPolicy & iPolicy, RED::Object * iResMgr, int iStateNumber = -1 ) = 0
virtual RED_RC	WriteShaderProgram ( const RED::ShaderProgramID & iID, RED::StreamingPolicy & iPolicy, const RED::String & iShaderProgram, RED::Object * iResMgr, int iStateNumber = -1 ) = 0

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.

Functions documentation

public static RED::CID RED::IREDFile::GetClassID

(

)

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

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

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

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

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

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.

public virtual RED_RC RED::IREDFile::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 "Redway3d"). 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.

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

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

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

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

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

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

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

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

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

class RED::IREDFile

Public functions:

Public static functions:

Detailed description:

Functions documentation