class RED::IOTools

File saving and loading API. More...

#include <REDIOTools.h>

Inherits: Object.

Public static functions:

static RED_RCLoad ( RED::Vector< unsigned int > & oDataContext, const RED::String & iFilePath, unsigned int iObjectTypes, RED::IO_LOAD_MATERIAL_TYPE iMaterialType, const RED::LayerSet * iRealtimeLayerset, const RED::LayerSet * iPhotorealisticLayerset, RED::IO_LOAD_TEXTURE_TRANSPARENCY iTransparencyChannel, RED::IO_SYSTEM_UNIT iSystemUnit, bool iLocalImages, const RED::State & iState, unsigned int iDataContext = 0, RED::Map< unsigned int, RED::String > * iIDNameTable = NULL, RED::ProgressCallback iProgressCallback = NULL, void * iUserData = NULL )
static RED_RCSave ( RED::Vector< RED::Object * > * iDAG, RED::Vector< RED::Object * > * iViewpoints, RED::Vector< RED::Object * > * iAnimationClipControllers, const RED::String & iFilePath, unsigned int iObjectTypes, bool iEmbedMedia, bool iTextMode, RED::IO_SYSTEM_UNIT iSystemUnit, RED::IO_FBX_FILE_VERSION iFbxFileVersion, RED::Object * iResourceManager, RED::Map< unsigned int, RED::String > * iIDNameTable = NULL, RED::ProgressCallback iProgressCallback = NULL, void * iUserData = NULL )

Detailed description:

File saving and loading API.

The RED::IOTools class defines the I/O methods to save or load 3D scenes through commonly used file formats.

Currently supported formats are FBX, OBJ and MTL, DAE and DXF.

This class needs the external REDFbx.dll library to work (provided with REDsdk). If not found, both load and save methods will return the RED_FBX_DLL_NOT_FOUND error code.

The REDFbx library is based on the FBX SDK 2016.0, it is used to import and export .FBX, .OBJ, .DAE and .DXF files.

Functions documentation

public static RED_RC RED::IOTools::Load(RED::Vector< unsigned int > &oDataContext,
const RED::String &iFilePath,
unsigned intiObjectTypes,
RED::IO_LOAD_MATERIAL_TYPEiMaterialType,
const RED::LayerSet *iRealtimeLayerset,
const RED::LayerSet *iPhotorealisticLayerset,
RED::IO_LOAD_TEXTURE_TRANSPARENCYiTransparencyChannel,
RED::IO_SYSTEM_UNITiSystemUnit,
booliLocalImages,
const RED::State &iState,
unsigned intiDataContext = 0,
RED::Map< unsigned int, RED::String > *iIDNameTable = NULL,
RED::ProgressCallbackiProgressCallback = NULL,
void *iUserData = NULL
)

Loads an external file from disk.

Currently supported formats are FBX, OBJ and MTL, DAE and DXF. Format selection is done automatically according to the iFilePath extension. Some limitations may occured for each format. See details here: Input-Output API.

Note:

This method needs the REDFbx library to work.

REDsdk imports the following .fbx features:

The content of the file is stored in a new RED::IDataManager context or in an existing one. This is based on the value of the iDataContext parameter. A value of 0 (default value) will create a new context to store the data. This context will be added at the end of the oDataContext array. See Data manager for details about data contexts.

In REDsdk, the RED::IViewpoint objects are always scenegraphes roots. When loading external files, all the parent nodes of the cameras are ignored. If any parent node was animated, you can retrieve the animation via the RED::IDataManager and apply it to the viewpoint.

All the unnecessary FBX nodes are ignored during the loading. Those are nodes without child, transform and animation.

Fbx object names are used to create the REDsdk object ID (RED::Object::GetIDFromString).

If the FBX objects (mesh, light, camera) have no name, a name is created based on their node name: we add the '(obj)' postfix. For instance: if a node handling a mesh is named 'node_name' and the mesh has no name, we will name it 'node_name(obj)'.

If several FBX objects have the same name, a postfix index is added starting from the second instance at 0. For example: if a node called 'node_name' has already been loaded and another object having the same name is encountered, it will be renamed 'node_name0', then 'node_name1', etc..

FBX files exported from 3dsMax can contain nodes that have a geometric transform in addition to their regular local matrix. This transform is not affecting node hierarchy. Each node containing this type of transform is imported as two parented RED::ITransformShape objects. The upper shape handling the hierarchy transform, the lower one handling the geometric transform. Its name is postfixed with '(geom)'.

Object naming policies

If an external .FBX file contains a skinned mesh and a skeleton, the skinned mesh parent nodes will be ignored and the mesh object will be moved as child of the (animated) skeleton parent node.

Skinned mesh moved under its skeleton

The iObjectTypes parameter specifies which kind of objects must be imported. Use the RED::IO_OBJECT_TYPE flags. The RED::IOOT_ALL flag loads all the external file objects.

The iIDNameTable parameter is used to bind the REDsdk object IDs to FBX object names. It is filled during RED::IOTools::Load and can be reused to export with RED::IOTools::Save.

A progress callback iProgressCallback associated with custom data iUserData can be used to test the loading progress.

See also Loading a file using the Input-Output API.

Images are loaded using the RED::TGT_TEX_2D target, so texture UVs are expected normalized. if iLocalImages is set to true, then local storages of images are used to store loaded pixels data. In this case, loaded pixels in the local storage may have any dimension - including non power of two dimensions - even if the stored local target indicates RED::TGT_TEX_2D. Enforcing power of two dimensions occur on uploading image pixels on the GPU (and/or CPU) for the rendering using RED::IImage2D::SetPixels.

Parameters:

oDataContext:Reference to the list of data context ID(s).
iFilePath:Path to the external file to load.
iObjectTypes:Type of objects to load from external file (see RED::IO_OBJECT_TYPE).
iMaterialType:Type of REDsdk material to create when importing an FBX one.
iRealtimeLayerset:Pointer to the layerset to be used to store the real-time configuration of the generic or realistic material.
iPhotorealisticLayerset:Pointer to the layerset to be used to store the photorealistic configuration of the generic or realistic material.
iTransparencyChannel:Indicate which FBX texture channel(s) contains the transparency information.
iSystemUnit:System unit of the application to convert data to.
iLocalImages:If true all images are loaded in local storage and won't be loaded on the GPU.
iState:Current transaction parameter.
iDataContext:Data context id to use.
iIDNameTable:Table used to get the name of the loaded object from their REDsdk ID.
iProgressCallbackOptional pointer to a user loading progress callback.
iUserDataOptional pointer to user data that will be send to the progress callback.

Returns:

RED_OK if the method has succeeded,
RED_UNSUPPORTED_EXTENSION if the file extension is not valid,
RED_FBX_DLL_NOT_FOUND if the REDFbx dll is not found,
RED_FBX_DLL_ERROR if the REDFbx dll can not be correctly loaded,
RED_FBX_LOAD_ERROR if an error occured during the loading operation,
RED_FAIL otherwise.
public static RED_RC RED::IOTools::Save(RED::Vector< RED::Object * > *iDAG,
RED::Vector< RED::Object * > *iViewpoints,
RED::Vector< RED::Object * > *iAnimationClipControllers,
const RED::String &iFilePath,
unsigned intiObjectTypes,
booliEmbedMedia,
booliTextMode,
RED::IO_SYSTEM_UNITiSystemUnit,
RED::IO_FBX_FILE_VERSIONiFbxFileVersion,
RED::Object *iResourceManager,
RED::Map< unsigned int, RED::String > *iIDNameTable = NULL,
RED::ProgressCallbackiProgressCallback = NULL,
void *iUserData = NULL
)

Saves a list of DAG and viewpoints to an external file.

Currently supported formats are FBX, OBJ and MTL, DAE and DXF. Format selection is done automatically according to the iFilePath extension.

Note:

This method needs the REDFbx library to work.

REDsdk exports the following REDsdk features:

This method needs the lists of REDsdk objects to export:

  • Scenegraphes (iDAG) as a list of RED::IShape roots.
  • Cameras (iViewpoints) as a list of RED::IViewpoint objects.
  • Animations (iAnimationClipControllers) as a list of RED::IAnimationClipController objects. They can be basic or skeletal. Each of these parameters can be NULL but not all. At least one of the given lists must contain an element to save. If not, the function will return RED_BAD_PARAM.

In REDsdk, the RED::IAnimationClipController objects are not linked with any scenegraph object. The basic animations are saved in the .FBX file as animated nodes located under a node named "Animations" directly under the root. When opening the .FBX file with another 3D graphics software, you have to reassign the animations to the desired object.

Each basic or skeletal animation is saved in a separated FBX animation stack.

The iObjectTypes parameter specifies which kind of objects must be exported. Use the RED::IO_OBJECT_TYPE flags. The RED::IOOT_ALL flag saves all the RED DAG objects.

The iEmbedMedia parameter specifies if the media like textures must be embedded inside the .FBX file or stay external.

The iTextMode parameter allows to create .FBX files in ASCII text (mainly for debug purpose). It has no influence on other file formats (OBJ is already a text format).

The iIDNameTable parameter is used to export object names given their REDsdk ID. It is filled during RED::IOTools::Load and can be reused to export with RED::IOTools::Save. It is up to the REDsdk user to fill this map when creating new object in their scene.

A progress callback iProgressCallback associated with custom data iUserData can be used to test the saving progress.

See also Saving a file using the Input-Output API.

Parameters:

iDAG:List of DAG to save (RED::IShape root). Can be NULL.
iViewpoints:List of viewpoints to save (RED::IViewpoint). Can be NULL.
iAnimationClipControllers:List of animation clip controllers to save (RED::IAnimationClipController). Can be NULL.
iFilePath:Path to the external file.
iObjectTypes:Type of objects to save to external file (see RED::IO_OBJECT_TYPE).
iEmbedMedia:Set to true to include media like textures in the .FBX file.
iTextMode:Set to true to save .FBX as ASCII text, false for binary.
iSystemUnit:System unit of the saved data.
iFbxFileVersion:Fbx file version for compatibility.
iResourceManager:Resource manager.
iIDNameTable:Table used to get the name of the saved objects from their ID.
iProgressCallbackOptional pointer to a user saving progress callback.
iUserDataOptional pointer to user data that will be send to the progress callback.

Returns:

RED_OK if the method has succeeded,
RED_BAD_PARAM if a parameter is invalid,
RED_UNSUPPORTED_EXTENSION if the file extension is not valid,
RED_FBX_DLL_NOT_FOUND if the REDFbx dll is not found,
RED_FBX_DLL_ERROR if the REDFbx dll can not be correctly loaded,
RED_FBX_SAVE_ERROR if an error occured during the saving operation,
RED_FAIL otherwise.