KFbxImporter Class Reference

#include <kfbximporter.h>

Inheritance diagram for KFbxImporter:

[legend]

List of all members.

---

Detailed Description

Class to import an FBX file into SDK objects.

Normally this class is used as is. But for very special needs a user can override Initialize() for special purpose.

An importer will select the appropriate reader to a particular file. Ex: When an importer must import an FBX 7 file, the importer will ask for all registered readers if an FBX 7 file reader is available, then if a reader is found, the importer will create the specialized FBX 7 reader and read the file. This way, an importer can "read" many different type of files like FBX 5/6/7, 3DS, Obj, Dxf, Collada, etc.

See also:

KFbxReader

Typical workflow for using the KFbxImporter class:

1. create a SDKManager
2. create an IOSettings object
3. create an empty scene
4. create an importer
5. initialize the importer with a file name and IOSettings
6. set numerous states, take information, defining how the importer will behave
7. call KFbxImporter::Import() with an empty scene

    ex:
    // create a SdkManager
    KFbxSdkManager *lSdkManager = KFbxSdkManager::Create();
   
    // create an IOSettings object
    KFbxIOSettings * ios = KFbxIOSettings::Create(lSdkManager, IOSROOT );
   
    // set some IOSettings options 
    ios->SetBoolProp(IMP_FBX_MATERIAL, true);
    ios->SetBoolProp(IMP_FBX_TEXTURE,  true);
   
    // create an empty scene
    KFbxScene* lScene = KFbxScene::Create(lSdkManager,"");
   
    // Create an importer.
    KFbxImporter* lImporter = KFbxImporter::Create(lSdkManager, "");
   
    // Initialize the importer by providing a filename and the IOSettings to use
    lImporter->Initialize("C:\\myfile.fbx", -1, ios);
   
    // Import the scene.
    lImporter->Import(lScene); 
   
    // Destroy the importer.
    lImporter->Destroy(); 
   

Remarks:

According to the file suffix, a specialized reader will be created internally. Ex: for .fbx files a FBX Reader, for .3ds files, a 3ds reader, etc. Supported files formats: FBX 5/6/7 Binary & ASCII, Collada, DXF, OBJ, 3DS

Definition at line 139 of file kfbximporter.h.

Import Functions
enum	EStreamOptionsGeneration {    eSTREAMOPTIONS_PARSE_FILE,    eSTREAMOPTIONS_FAST,    eSTREAMOPTIONS_COUNT }
	Stream options identifiers. More...
virtual bool	Initialize (const char *pFileName, const int pFileFormat=-1, KFbxIOSettings *pIOSettings=NULL)
	Initialize object.
virtual bool	Initialize (KFile *pFile, const int pFileFormat=-1, KFbxIOSettings *pIOSettings=NULL)
	Initialize object.
virtual KFile *	GetFile ()
	Get the file, if any.
void	GetFileVersion (int &pMajor, int &pMinor, int &pRevision)
	Get the FBX version number of the FBX file.
bool	GetDefaultRenderResolution (KString &pCamName, KString &pResolutionMode, double &pW, double &pH)
	Get the default rendering resolution if present in the file header.
KFbxFileHeaderInfo *	GetFileHeaderInfo ()
	Get the complete file header information.
bool	GetImportOptions (EStreamOptionsGeneration pStreamOptionsGeneration=eSTREAMOPTIONS_PARSE_FILE)
	Read the currently opened file header to retrieve information related to takes.
bool	GetImportOptions (KFbx *pFbxObject)
	Read the currently opened file header to retrieve information related to takes.
bool	Import (KFbxDocument *pDocument, bool pNonBlocking=false)
	Import the currently opened file into a scene.
bool	IsImporting (bool &pImportResult)
	Check if the importer is currently importing.
float	GetProgress (KString &pStatus)
	Get the progress status in non-blocking mode.
void	SetProgressCallback (KFbxProgressCallback pHandler)
	Register a callback function for progress reporting in single thread mode.
KFbxIOSettings *	GetIOSettings ()
	Access to a IOSettings object.
void	SetIOSettings (KFbxIOSettings *pIOSettings)
	Set the IOSettings pointer.
void	SetPassword (char *pPassword)
	Set the password.
Animation Stack Description Access
See also: KFbxAnimStack
K_DEPRECATED int	GetTakeCount ()
	Get the number of available takes in the file.
int	GetAnimStackCount ()
	Get the number of available animation stacks in the file.
KFbxTakeInfo *	GetTakeInfo (int pIndex)
	Get the take information about an available take.
K_DEPRECATED char *	GetCurrentTakeName ()
	Return the current take name.
KString	GetActiveAnimStackName ()
	Return the active animation stack name.
Scene Description Access
KFbxDocumentInfo *	GetSceneInfo ()
	Get the scene info.
File Format
int	GetFileFormat ()
	Returns the index of the reader (FbxReader) associated with the file format.
bool	IsFBX ()
Public Member Functions
void	ParseForGlobalSettings (bool pState)
	Set a flag to parse or not the GlobalSettings data section when the importer is initialized.
void	ParseForStatistics (bool pState)
	Set a flag to parse or not in a FBX file the Summary data section or the Definition data section when the importer is initialized.
bool	GetAxisInfo (KFbxAxisSystem *pAxisSystem, KFbxSystemUnit *pSystemUnits)
	Get FBX file Axis information and FBX file System units.
bool	GetStatistics (KFbxStatistics *pStatistics)
	Get FBX file Statistics informations.

---

Member Enumeration Documentation

enum EStreamOptionsGeneration

Stream options identifiers.

• eSTREAMOPTIONS_PARSE_FILE Parse the file
• eSTREAMOPTIONS_FAST Do not parse the file.
• eSTREAMOPTIONS_COUNT

Enumerator:

eSTREAMOPTIONS_PARSE_FILE
eSTREAMOPTIONS_FAST
eSTREAMOPTIONS_COUNT

Definition at line 204 of file kfbximporter.h.

---

Member Function Documentation

virtual bool Initialize	(	const char *	pFileName,
		const int	pFileFormat = -1,
		KFbxIOSettings *	pIOSettings = NULL
	)			[virtual]

Initialize object.

Parameters:

	pFileName	Name of file to access.
	pFileFormat	file format identifier User does not need to specify it by default. if not specified, plugin will detect the file format according to file suffix automatically.
	pIOSettings	client IOSettings, if not specified, a default IOSettings will be created

Returns:

true on success, false otherwise.

Remarks:

To identify the error that occurred, call KFbxIO::GetLastErrorID().

You do not need to give the pFileFormat if the suffix of pFileName is recognized

virtual bool Initialize	(	KFile *	pFile,
		const int	pFileFormat = -1,
		KFbxIOSettings *	pIOSettings = NULL
	)			[virtual]

Initialize object.

Parameters:

	pFile	file to access. Ownership is transfered to this object.
	pFileFormat	file format identifier User does not need to specify it by default. if not specified, plugin will detect the file format according to file suffix automatically.
	pIOSettings	client IOSettings, if not specified, a default IOSettings will be created

Returns:

true on success, false otherwise.

Remarks:

To identify the error that occurred, call KFbxIO::GetLastErrorID().

You do not need to give the pFileFormat if the suffix of pFileName is recognized

virtual KFile* GetFile

(

)

[virtual]

Get the file, if any.

Returns:

The file or NULL if the file has not been set.

void GetFileVersion	(	int &	pMajor,
		int &	pMinor,
		int &	pRevision
	)

Get the FBX version number of the FBX file.

FBX version numbers start at 5.0.0.

Parameters:

	pMajor	Version major number.
	pMinor	Version minor number.
	pRevision	Version revision number.

Remarks:

This function must be called after KFbxImporter::Initialize().

bool GetDefaultRenderResolution	(	KString &	pCamName,
		KString &	pResolutionMode,
		double &	pW,
		double &	pH
	)

Get the default rendering resolution if present in the file header.

Parameters:

	pCamName	Returned name of the camera.
	pResolutionMode	Returned resolution mode.
	pW	Returned width.
	pH	Returned height.

Returns:

true if the default rendering settings are defined in the file, otherwise returns false with empty parameters.

KFbxFileHeaderInfo* GetFileHeaderInfo

(

)

Get the complete file header information.

Returns:

valid pointer to the complete header information

bool GetImportOptions

(

EStreamOptionsGeneration

pStreamOptionsGeneration = eSTREAMOPTIONS_PARSE_FILE

)

Read the currently opened file header to retrieve information related to takes.

Parameters:

pStreamOptionsGeneration

Stream options identifier.

Returns:

true on success, false otherwise.

Remarks:

Caller gets ownership of the returned structure.

bool GetImportOptions

(

KFbx *

pFbxObject

)

Read the currently opened file header to retrieve information related to takes.

Parameters:

pFbxObject

Target FBX file.

Returns:

true on success, false otherwise.

Remarks:

Caller gets ownership of the returned structure.

bool Import	(	KFbxDocument *	pDocument,
		bool	pNonBlocking = false
	)

Import the currently opened file into a scene.

Parameters:

	pDocument	Document to fill with file content.
	pNonBlocking	If true, the import process will be executed in a new thread, allowing it to be non-blocking. To determine if the import finished, refer to the function IsImporting().

Returns:

true on success, false otherwise.

Remarks:

To identify the error that occurred, call KFbxIO::GetLastErrorID(). If the imported file is password protected and the password is not set or wrong, function KFbxIO::GetLastErrorID() returns KFbxIO::ePASSWORD_ERROR.

bool IsImporting

(

bool &

pImportResult

)

Check if the importer is currently importing.

Parameters:

pImportResult

This parameter, after the import finished, will contain the result of the import success or failure.

Returns:

Return true if the importer is currently importing.

Remarks:

This function will always return false if Import() was called with pNonBlocking set to false. This function should be used only in the context of pNonBlocking set to true. It is very important to periodically check if the import finished using this function, since it will also free up the thread's allocations when its done.

float GetProgress

(

KString &

pStatus

)

Get the progress status in non-blocking mode.

Parameters:

pStatus

KString reference to retrieve current status

Returns:

Percentage of the finished workload

void SetProgressCallback

(

KFbxProgressCallback

pHandler

)

Register a callback function for progress reporting in single thread mode.

Parameters:

pHandler

Pointer of the callback function

KFbxIOSettings* GetIOSettings

(

)

Access to a IOSettings object.

Returns:

The pointer to IOSettings or NULL if the object has not been allocated.

void SetIOSettings

(

KFbxIOSettings *

pIOSettings

)

Set the IOSettings pointer.

Parameters:

pIOSettings

Point to a KFbxIOSettings object.

void SetPassword

(

char *

pPassword

)

Set the password.

All subsequently imported files are opened with the given password.

Parameters:

pPassword

Password string.

K_DEPRECATED int GetTakeCount

(

)

Get the number of available takes in the file.

This method is deprecated an should be replaced with calls to GetAnimStackCount().

Returns:

Number of takes.

Remarks:

This function must be called after KFbxImporter::Initialize().

int GetAnimStackCount

(

)

Get the number of available animation stacks in the file.

Returns:

Number of animation stacks.

Remarks:

This function must be called after KFbxImporter::Initialize().

KFbxTakeInfo* GetTakeInfo

(

int

pIndex

)

Get the take information about an available take.

Use the returned reference to a KFbxTakeInfo object to set whether the indexed take is imported.

Parameters:

pIndex

Index of the requested take.

Returns:

Take information or NULL if function failed.

Remarks:

This function must be called after KFbxImporter::Initialize().

K_DEPRECATED char* GetCurrentTakeName

(

)

Return the current take name.

This method is deprecated an should be replaced with calls to GetActiveAnimStackName().

Returns:

Current take name if there is one, otherwise returns an empty string.

Remarks:

This function must be called after KFbxImporter::Initialize().

KString GetActiveAnimStackName

(

)

Return the active animation stack name.

Returns:

Active animation stack name if there is one, otherwise returns an empty string.

Remarks:

This function must be called after KFbxImporter::Initialize().

KFbxDocumentInfo* GetSceneInfo

(

)

Get the scene info.

Returns:

Pointer to the scene info or NULL if no scene information is available in the file.

int GetFileFormat

(

)

Returns the index of the reader (FbxReader) associated with the file format.

This index is considered the identifier of the file format. The array of registered readers can't be retrieved.

Returns:

Index of the registered FbxReader associated with the file format. If no reader found return -1.

Remarks:

According to the number of readers registered this value can change for the same reader between SDK Manager instantiations.

bool IsFBX

(

)

Returns:

true if the file format is a recognized FBX format.

void ParseForGlobalSettings

(

bool

pState

)

Set a flag to parse or not the GlobalSettings data section when the importer is initialized.

Parameters:

pState

true or false

Remarks:

This function is used internally by the FBX readers

void ParseForStatistics

(

bool

pState

)

Set a flag to parse or not in a FBX file the Summary data section or the Definition data section when the importer is initialized.

Parameters:

pState

true or false

Remarks:

This function is used internally by the FBX readers

bool GetAxisInfo	(	KFbxAxisSystem *	pAxisSystem,
		KFbxSystemUnit *	pSystemUnits
	)

Get FBX file Axis information and FBX file System units.

Parameters:

	pAxisSystem	pointer to a KFbxAxisSystem object
	pSystemUnits	pointer to a KFbxSystemUnit object

Returns:

true on success, false otherwise.

Remarks:

This function must be called after KFbxImporter::Initialize().

bool GetStatistics

(

KFbxStatistics *

pStatistics

)

Get FBX file Statistics informations.

Ex: Number of Models, Characters, Textures, Materials, etc.

Parameters:

pStatistics

pointer to a KFbxStatistics object

Returns:

true on success, false otherwise.

Remarks:

This function must be called after KFbxImporter::Initialize().