1/****************************************************************************************
2
3 Copyright (C) 2015 Autodesk, Inc.
4 All rights reserved.
5
6 Use of this software is subject to the terms of the Autodesk license agreement
7 provided at the time of installation or download, or which otherwise accompanies
8 this software in either electronic or hard copy form.
9
10****************************************************************************************/
11
12//! \file fbximporter.h
13#ifndef _FBXSDK_FILEIO_IMPORTER_H_
14#define _FBXSDK_FILEIO_IMPORTER_H_
15
16#include <fbxsdk/fbxsdk_def.h>
17
18#include <fbxsdk/core/fbxsystemunit.h>
19#include <fbxsdk/core/base/fbxtime.h>
20#include <fbxsdk/fileio/fbxiobase.h>
21#include <fbxsdk/fileio/fbxprogress.h>
22#include <fbxsdk/fileio/fbxiosettings.h>
23#include <fbxsdk/fileio/fbxstatistics.h>
24#include <fbxsdk/scene/fbxaxissystem.h>
25
26#include <fbxsdk/fbxsdk_nsbegin.h>
27
28class FbxIO;
29class FbxIOFileHeaderInfo;
30class FbxDocumentInfo;
31class FbxTakeInfo;
32class FbxReader;
33class FbxThread;
34
35struct FbxImportThreadArg;
36
37/** Class to import an FBX file into SDK objects.
38* Normally this class is used as is. But for very special needs
39* a user can override Initialize() for special purpose.
40*
41* An importer will select the appropriate reader to a particular file.
42* Ex: When an importer must import an FBX 7 file,
43* the importer will ask for all registered readers if an FBX 7 file reader is available,
44* then if a reader is found, the importer will create
45* the specialized FBX 7 reader and read the file.
46* This way, an importer can "read" many different type of files like FBX 5/6/7, 3DS, Obj, Dxf, Collada, etc.
47* \see FbxReader
48*
49* Typical workflow for using the FbxImporter class:
50* -# create a SDKManager
51* -# create an IOSettings object
52* -# create an empty scene
53* -# create an importer
54* -# initialize the importer with a file name and IOSettings
55* -# set numerous states, take information, defining how the importer will behave
56* -# call FbxImporter::Import() with an empty scene
57* \code
58* ex:
59* // create a SdkManager
60* FbxManager *lSdkManager = FbxManager::Create();
61*
62* // create an IOSettings object
63* FbxIOSettings * ios = FbxIOSettings::Create(lSdkManager, IOSROOT );
64*
65* // set some IOSettings options
66* ios->SetBoolProp(IMP_FBX_MATERIAL, true);
67* ios->SetBoolProp(IMP_FBX_TEXTURE, true);
68*
69* // create an empty scene
70* FbxScene* lScene = FbxScene::Create(lSdkManager,"");
71*
72* // Create an importer.
73* FbxImporter* lImporter = FbxImporter::Create(lSdkManager, "");
74*
75* // Initialize the importer by providing a filename and the IOSettings to use
76* lImporter->Initialize("C:\\myfile.fbx", -1, ios);
77*
78* // Import the scene.
79* lImporter->Import(lScene);
80*
81* // Destroy the importer.
82* lImporter->Destroy();
83* \endcode
84*
85* \remarks According to the file suffix, a specialized reader will be created internally.
86* Ex: for .fbx files a FBX Reader, for .3ds files, a 3ds reader, etc.
87* Supported files formats: FBX 5/6/7 Binary & ASCII, Collada, DXF, OBJ, 3DS
88* \nosubgrouping
89*/
90class FBXSDK_DLL FbxImporter : public FbxIOBase
91{
92 FBXSDK_OBJECT_DECLARE(FbxImporter, FbxIOBase);
93
94public:
95 /**
96 * \name Import Functions
97 */
98 //@{
99
100 /** Initialize object.
101 * \param pFileName Name of file to access.
102 * \param pFileFormat file format identifier User does not need to specify it by default.
103 if not specified, plugin will detect the file format according to file suffix automatically.
104 * \param pIOSettings client IOSettings, if not specified, a default IOSettings will be created
105 * \return \c true on success, \c false otherwise.
106 * \remarks To identify the error that occurred, inspect the status object accessed
107 * using the GetStatus() function.
108 * \remarks You do not need to give the pFileFormat if the suffix of pFileName is recognized
109 */
110 virtual bool Initialize(const char* pFileName, int pFileFormat=-1, FbxIOSettings * pIOSettings=NULL);
111
112 /** Initialize object.
113 * \param pStream stream to access.
114 * \param pStreamData user-defined stream data.
115 * \param pFileFormat file format identifier User does not need to specify it by default.
116 if not specified, plugin will request the file format from the stream automatically.
117 * \param pIOSettings client IOSettings, if not specified, a default IOSettings will be created
118 * \return \c true on success, \c false otherwise.
119 * \remarks To identify the error that occurred, inspect the status object accessed
120 * using the GetStatus() function.
121 * \remarks You do not need to give the pFileFormat if the suffix of pFileName is recognized
122 */
123 virtual bool Initialize(FbxStream* pStream, void* pStreamData=NULL, const int pFileFormat=-1, FbxIOSettings* pIOSettings=NULL);
124
125 /** Get the FBX version number of the FBX file.
126 * FBX version numbers start at 5.0.0.
127 * \param pMajor Version major number.
128 * \param pMinor Version minor number.
129 * \param pRevision Version revision number.
130 * \remarks This function must be called after FbxImporter::Initialize().
131 */
132 void GetFileVersion(int& pMajor, int& pMinor, int& pRevision);
133
134 /** Get the default rendering resolution if present in the file header.
135 * \param pCamName Returned name of the camera.
136 * \param pResolutionMode Returned resolution mode.
137 * \param pW Returned width.
138 * \param pH Returned height.
139 * \return \c true if the default rendering settings are defined in the file, otherwise
140 * returns \c false with empty parameters.
141 */
142 bool GetDefaultRenderResolution(FbxString& pCamName, FbxString& pResolutionMode, double& pW, double& pH);
143
144 /** Get the complete file header information.
145 * \return valid pointer to the complete header information
146 */
147 FbxIOFileHeaderInfo* GetFileHeaderInfo();
148
149 /** \enum EStreamOptionsGeneration Stream options identifiers.
150 * - \e eParseFile Parse the file
151 * - \e eDoNotParseFile Do not parse the file.
152 */
153 enum EStreamOptionsGeneration
154 {
155 eParseFile, // Parse the file
156 eDoNotParseFile // Do not parse the file (fast)
157 };
158
159 /** Read the currently opened file header to retrieve information related to takes.
160 * \param pStreamOptionsGeneration Stream options identifier.
161 * \return \c true on success, \c false otherwise.
162 * \remarks Caller gets ownership of the returned structure.
163 */
164 bool GetImportOptions(EStreamOptionsGeneration pStreamOptionsGeneration = eParseFile);
165
166 /** Read the currently opened file header to retrieve information related to takes.
167 * \param pFbxObject Target FBX file.
168 * \return \c true on success, \c false otherwise.
169 * \remarks Caller gets ownership of the returned structure.
170 */
171 bool GetImportOptions(FbxIO* pFbxObject);
172
173 /** Import the currently opened file into a scene.
174 * \param pDocument Document to fill with file content.
175 * \param pNonBlocking If true, the import process will be executed in a new thread, allowing it to be non-blocking.
176 To determine if the import finished, refer to the function IsImporting().
177 * \return \c true on success, \c false otherwise.
178 * \remarks To identify the error that occurred, inspect the status object accessed
179 * using the GetStatus() function.
180 * If the imported file is password protected and the password is not
181 * set or wrong, the FbxStatus object access with GetStatus() will be set with
182 * FbxStatus::ePasswordError.
183 */
184 bool Import(FbxDocument* pDocument, bool pNonBlocking=false);
185
186#if !defined(FBXSDK_ENV_WINSTORE) && !defined(FBXSDK_ENV_EMSCRIPTEN)
187 /** Check if the importer is currently importing.
188 * \param pImportResult This parameter, after the import finished, will contain the result of the import success or failure.
189 * \return Return true if the importer is currently importing.
190 * \remarks This function will always return false if Import() was called with pNonBlocking set to false.
191 * This function should be used only in the context of pNonBlocking set to true.
192 * It is very important to periodically check if the import finished using this function,
193 * since it will also free up the thread's allocations when its done.
194 */
195 bool IsImporting(bool& pImportResult);
196#endif /* !FBXSDK_ENV_WINSTORE && !defined(FBXSDK_ENV_EMSCRIPTEN) */
197
198 /** Get the progress status in non-blocking mode.
199 * \param pStatus Optional current status string.
200 * \return Percentage of the finished workload
201 */
202 float GetProgress(FbxString* pStatus=NULL);
203
204 /** Register a callback function for progress reporting in single thread mode.
205 * \param pCallback Pointer of the callback function.
206 * \param pArgs pointer to the arguments passed to the callback function.
207 */
208 void SetProgressCallback(FbxProgressCallback pCallback, void* pArgs=NULL);
209
210 /** Explicitly set the embedding extraction folder. If this is never called, the FBX SDK will determine the best folder to extract embedded files.
211 * \param pExtractFolder The file path name where the embedded files should be extracted.
212 */
213 void SetEmbeddingExtractionFolder(const char* pExtractFolder);
214
215 /** Retrieve the current folder destination where the embedded files will be extracted. This might not be initialized until file I/O is performed.
216 */
217 const char* GetEmbeddingExtractionFolder();
218
219 /** Access to a IOSettings object.
220 * \return The pointer to IOSettings or \c NULL \c if the object has not been allocated.
221 */
222 FbxIOSettings* GetIOSettings();
223
224 /** Set the IOSettings pointer
225 * \param pIOSettings Point to a FbxIOSettings object.
226 */
227 void SetIOSettings(FbxIOSettings* pIOSettings);
228
229 /** Set the password.
230 * All subsequently imported files are opened with the given password.
231 * \param pPassword Password string.
232 */
233 void SetPassword(char* pPassword);
234
235 /**
236 * \name Animation Stack Description Access
237 * \see FbxAnimStack
238 */
239 //@{
240
241 /** Get the number of available animation stacks in the file.
242 * \return Number of animation stacks.
243 * \remarks This function must be called after FbxImporter::Initialize().
244 */
245 int GetAnimStackCount();
246
247 /** Get the take information about an available take.
248 * Use the returned reference to a FbxTakeInfo object to set whether the indexed take is imported.
249 * \param pIndex Index of the requested take.
250 * \return Take information or \c NULL if function failed.
251 * \remarks This function must be called after FbxImporter::Initialize().
252 */
253 FbxTakeInfo* GetTakeInfo(int pIndex);
254
255 /** Return the active animation stack name.
256 * \return Active animation stack name if there is one, otherwise returns an empty string.
257 * \remarks This function must be called after FbxImporter::Initialize().
258 */
259 FbxString GetActiveAnimStackName();
260
261 //@}
262
263 /**
264 * \name Scene Description Access
265 */
266 //@{
267
268 /** Get the scene info.
269 * \return Pointer to the scene info or \c NULL if no scene information
270 * is available in the file.
271 */
272 FbxDocumentInfo* GetSceneInfo();
273
274 //@}
275 /**
276 * \name File Format
277 */
278 //@{
279
280 /** Returns the index of the reader (FbxReader) associated with the file format.
281 This index is considered the identifier of the file format.
282 The array of registered readers can't be retrieved.
283 \return Index of the registered FbxReader associated with the file format.
284 If no reader found return -1.
285 \remarks According to the number of readers registered this value can change
286 for the same reader between SDK Manager instantiations.
287 */
288 int GetFileFormat ();
289
290 /** \return \c true if the file format is a recognized FBX format.
291 */
292 bool IsFBX();
293 //@}
294
295/*****************************************************************************************************************************
296** WARNING! Anything beyond these lines is for internal use, may not be documented and is subject to change without notice! **
297*****************************************************************************************************************************/
298#ifndef DOXYGEN_SHOULD_SKIP_THIS
299 FbxFile* GetFile();
300 FbxStream* GetStream();
301 void* GetStreamData();
302
303 void ParseForGlobalSettings(bool pState);
304 void ParseForStatistics(bool pState);
305 bool GetAxisInfo(FbxAxisSystem* pAxisSystem, FbxSystemUnit* pSystemUnits);
306 bool GetStatistics(FbxStatistics* pStatistics);
307 bool GetFrameRate(FbxTime::EMode &pTimeMode);
308
309protected:
310 virtual void Construct(const FbxObject* pFrom);
311 virtual void Destruct(bool pRecursive);
312 virtual void SetOrCreateIOSettings(FbxIOSettings* pIOSettings, bool pAllowNULL);
313
314 void Reset();
315 bool FileOpen(FbxFile* pFile = NULL);
316 bool FileOpen(FbxStream* pStream, void* pStreamData);
317 void FileClose();
318
319 void GetImportOptionsInfo();
320 bool IsNativeExtension ();
321
322 //These two internal functions are only used to read old character pose data
323 bool Initialize(FbxFile* pFile, const int pFileFormat=-1, FbxIOSettings* pIOSettings=NULL);
324 bool Import(FbxDocument* pDocument, FbxIO* pFbxObject);
325
326private:
327 bool ImportProcess(FbxDocument* pDocument);
328
329 int mFileFormat;
330 FbxReader* mReader;
331 FbxString mExtractFolder;
332 bool mParseForGlobalSettings;
333 FbxAxisSystem mAxisSystem;
334 FbxSystemUnit mSystemUnits;
335 FbxTime::EMode mFrameRate;
336 bool mParseForStatistics;
337 FbxStatistics mStatistics;
338#if !defined(FBXSDK_ENV_WINSTORE) && !defined(FBXSDK_ENV_EMSCRIPTEN)
339 FbxThread* mImportThread;
340 FbxImportThreadArg* mImportThreadArg;
341 bool mImportThreadResult;
342 bool mIsThreadImporting;
343#endif /* !FBXSDK_ENV_WINSTORE && !defined(FBXSDK_ENV_EMSCRIPTEN) */
344 FbxProgress mProgress;
345 FbxFile* mFile;
346 FbxStream* mStream;
347 void* mStreamData;
348 bool mImportOptionsDone;
349 FbxArray<FbxTakeInfo*> mTakeInfo;
350 FbxDocumentInfo* mSceneInfo;
351 FbxString mActiveAnimStackName;
352 int mMajorVersion;
353 int mMinorVersion;
354 int mRevisionVersion;
355 FbxIOFileHeaderInfo* mHeaderInfo;
356 FbxIOSettings* mIOSettings;
357 bool mClientIOSettings;
358
359 //For Initialize and Import
360 friend class FbxReaderFbx5;
361 friend class FbxReaderFbx6;
362 friend struct FbxReaderFbx7_Impl;
363
364 friend void ImportThread(void*);
365#endif /* !DOXYGEN_SHOULD_SKIP_THIS *****************************************************************************************/
366};
367
368//! Event that is emitted to plugins before a FBX file has been imported.
369class FBXSDK_DLL FbxEventPreImport : public FbxEvent<FbxEventPreImport>
370{
371 FBXSDK_EVENT_DECLARE(FbxEventPreImport);
372public:
373 inline FbxEventPreImport( FbxDocument* pDocument ) : mDocument(pDocument) {};
374
375 //! The document the FBX file is to be imported into.
376 FbxDocument* mDocument;
377};
378
379//! Event that is emitted to plugins after a FBX file has been imported.
380class FBXSDK_DLL FbxEventPostImport : public FbxEvent<FbxEventPostImport>
381{
382 FBXSDK_EVENT_DECLARE(FbxEventPostImport);
383public:
384 inline FbxEventPostImport( FbxDocument* pDocument ) : mDocument(pDocument) {};
385
386 //! The imported document
387 FbxDocument* mDocument;
388};
389
390#include <fbxsdk/fbxsdk_nsend.h>
391
392#endif /* _FBXSDK_FILEIO_IMPORTER_H_ */
393