IOTools

Functions

RED_RC	Load
RED_RC	Save

Detailed Description

class IOTools : public RED::Object

File saving and loading API.

@related Input-Output API, Loading a File using the Input-Output API, Saving a File using the Input-Output API, class RED::IDataManager, Loading and Playing Skeletal Animations

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.

Public Static Functions

static RED_RC Load(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)

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: \ref bk_id_io_tools.

REDsdk imports the following .fbx features:

• node transform hierarchy as RED::ITransformShape;

• meshes as RED::IMeshShape;

• lines as RED::ILineShape (fbx doesn’t support line material import);

• vertex position in the RED::MCL_VERTEX channel;

• vertex color in the RED::MCL_COLOR channel;

• normal in the RED::MCL_NORMAL channel;

• texture coordinates in the RED::MCL_TEX0 to RED::MCL_TEX7 channels;

• tangents in the RED::MCL_USER0 channel;

• binormals in the RED::MCL_USER1 channel;

• FBX Lambert and Phong materials are loaded as generic or realistic materials;

• material textures are bound to the RED::MCL_TEX0 to RED::MCL_TEX7 mesh channel;

• lights: ambient, directional, spot, point, rectangular area (RED::ILightShape);

• cameras: orthographic or perspective (RED::IViewpoint);

• mesh skeleton and skinning data in RED::IMeshShape;

• animations as RED::IAnimationClipController and RED::ISkeletalAnimationController objects.

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 \ref bk_ba_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)’.

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.

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 \ref tk_loading_io_file.

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.

Note

This method needs the REDFbx library to work.

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.

• iProgressCallback – Optional pointer to a user loading progress callback.

• iUserData – Optional 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.

static RED_RC Save(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, bool iLocalImages, RED::IO_FBX_FILE_VERSION iFbxFileVersion, RED::Object *iResourceManager, RED::Map<unsigned int, RED::String> *iIDNameTable = NULL, RED::ProgressCallback iProgressCallback = 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.

REDsdk exports the following REDsdk features:

• node transform hierarchy (RED::IShape);

• meshes (RED::IMeshShape);

• lines (RED::ILineShape);

• vertex position (RED::MCL_VERTEX);

• vertex color (RED::MCL_COLOR);

• normal (RED::MCL_NORMAL);

• RED::MCL_USER0 is saved as tangent;

• RED::MCL_USER1 is saved as binormal;

• texture coordinates (RED::MCL_TEX0 to RED::MCL_TEX7);

• generic and realistic material (emissive, ambient, diffuse, specular, opacity and bump properties);

• material textures as .PNG;

• lights (RED::ILightShape): ambient, directional, spot, point, rectangular area;

• cameras (RED::IViewpoint): orthographic, perspective.

• basic animations (RED::IAnimationClipController)

• mesh skeleton and skinning data;

• skeletal animations (RED::ISkeletalAnimationController)

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 \ref tk_saving_io_file.

Note

This method needs the REDFbx library to work.

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.

• iLocalImages – If true all images are saved sourcing their contents from the local storage.

• iFbxFileVersion – Fbx file version for compatibility.

• iResourceManager – Resource manager.

• iIDNameTable – Table used to get the name of the saved objects from their ID.

• iProgressCallback – Optional pointer to a user saving progress callback.

• iUserData – Optional 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.