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 fbxexporter.h
13#ifndef _FBXSDK_FILEIO_EXPORTER_H_
14#define _FBXSDK_FILEIO_EXPORTER_H_
15
16#include <fbxsdk/fbxsdk_def.h>
17
18#include <fbxsdk/core/fbxevent.h>
19#include <fbxsdk/core/base/fbxstring.h>
20#include <fbxsdk/fileio/fbxiobase.h>
21#include <fbxsdk/fileio/fbxiosettings.h>
22#include <fbxsdk/fileio/fbxprogress.h>
23#include <fbxsdk/utils/fbxrenamingstrategy.h>
24
25#include <fbxsdk/fbxsdk_nsbegin.h>
26
27class FbxIO;
28class FbxIOFileHeaderInfo;
29class FbxThread;
30class FbxWriter;
31
32struct FbxExportThreadArg;
33
34/** Class to export SDK objects into an FBX file.
35 * Normally this class is used as is. But for very special needs
36 * a user can override Initialize() for special purpose.
37 *
38 * An exporter will select the appropriate writer to a particular file.
39 * Ex: When an exporter must export an FBX 7 file,
40 * the exporter will ask for all registered writers if an FBX 7 file writer is available,
41 * then if a writer is found, the exporter will create
42 * the specialized FBX 7 writer and write the file.
43 * This way, an exporter can "write" many different type of files like FBX 5/6/7, 3DS, Obj, Dxf, Collada, etc.
44 * \see FbxWriter
45 *
46 * Typical workflow for using the FbxExporter class:
47 * -# create a SDKManager
48 * -# create an IOSettings object
49 * -# create an empty scene
50 * -# create an exporter
51 * -# initialize it with a file name
52 * -# set numerous options to control how the exporter will behave.\n
53 * ex: set IOSettings values to export Materials or Textures.
54 * -# call FbxExporter::Export() with the entity to export.
55 *
56 * \code
57 * // ex:
58 * // create a SdkManager
59 * FbxManager* lSdkManager = FbxManager::Create();
60 *
61 * // create an IOSettings object
62 * FbxIOSettings* ios = FbxIOSettings::Create(lSdkManager, IOSROOT);
63 *
64 * // set some IOSettings options
65 * ios->SetBoolProp(EXP_FBX_MATERIAL, true);
66 * ios->SetBoolProp(EXP_FBX_TEXTURE, true);
67 *
68 * // create an empty scene
69 * FbxScene* lScene = FbxScene::Create(lSdkManager, "");
70 *
71 * // create an exporter.
72 * FbxExporter* lExporter = FbxExporter::Create(lSdkManager, "");
73 *
74 * // initialize the exporter by providing a filename and the IOSettings to use
75 * lExporter->Initialize("C:\\myfile.fbx", -1, ios);
76 *
77 * // export the scene.
78 * lExporter->Export(lScene);
79 *
80 * // destroy the exporter
81 * lExporter->Destroy();
82 * \endcode
83 *
84 * \remarks According to the file suffix, a specialized writer will be created internally.\n
85 * Ex: for .fbx files a FBX Writer, for .3ds files, a 3ds writer, etc.\n
86 * Supported files formats: FBX 5/6/7 Binary & ASCII, Collada, DXF, OBJ, 3DS
87 * \nosubgrouping
88 */
89class FBXSDK_DLL FbxExporter : public FbxIOBase
90{
91 FBXSDK_OBJECT_DECLARE(FbxExporter, FbxIOBase);
92
93public:
94 /**
95 * \name Export Functions
96 */
97 //@{
98 /** Initialize object.
99 * \param pFileName Name of file to access.
100 * \param pFileFormat file format identifier User does not need to specify it by default.
101 if not specified, plugin will detect the file format according to file suffix automatically.
102 * \param pIOSettings client IOSettings, if not specified, a default IOSettings will be created
103 * \return \c true on success, \c false otherwise.
104 * \remarks To identify the error that occurred, inspect the status object accessed
105 * using the GetStatus() function.
106 */
107 virtual bool Initialize(const char* pFileName, int pFileFormat = -1, FbxIOSettings* pIOSettings = NULL);
108
109 /** Initialize object.
110 * \param pStream stream to access.
111 * \param pStreamData user-defined stream data.
112 * \param pFileFormat file format identifier User does not need to specify it by default.
113 if not specified, plugin will request the file format from the stream.
114 * \param pIOSettings client IOSettings, if not specified, a default IOSettings will be created
115 * \return \c true on success, \c false otherwise.
116 * \remarks To identify the error that occurred, inspect the status object accessed
117 * using the GetStatus() function.
118 */
119 virtual bool Initialize(FbxStream* pStream, void* pStreamData=NULL, int pFileFormat = -1, FbxIOSettings * pIOSettings = NULL);
120
121 /** Setup file export options settings.
122 * \return \c true on success, \c false otherwise.
123 */
124 bool GetExportOptions();
125
126 /** Access to a IOSettings object.
127 * \return The pointer to IOSettings or \c NULL \c if the object has not been allocated.
128 */
129 FbxIOSettings* GetIOSettings();
130
131 /** Set the IOSettings pointer
132 * \param pIOSettings Pointer on a FbxIOSettings object.
133 */
134 void SetIOSettings(FbxIOSettings* pIOSettings);
135
136
137 /** Export the document to the currently created file.
138 * \param pDocument Document to export.
139 * \param pNonBlocking If true, the export process will be executed in a new thread, allowing it to be non-blocking.
140 To determine if the export finished, refer to the function IsExporting().
141 * \return \c true on success, \c false otherwise.
142 * \remarks To identify the error that occurred, inspect the status object accessed
143 * using the GetStatus() function.
144 */
145 bool Export(FbxDocument* pDocument, bool pNonBlocking=false);
146
147 #if !defined(FBXSDK_ENV_WINSTORE) && !defined(FBXSDK_ENV_EMSCRIPTEN)
148 /** Check if the exporter is currently exporting.
149 * \param pExportResult This parameter, after the export finished, will contain the result of the export success or failure.
150 * \return Return true if the exporter is currently exporting.
151 * \remarks This function will always return false if Export() was called with pNonBlocking set to false.
152 * This function should be used only in the context of pNonBlocking set to true.
153 * It is very important to periodically check if the export finished using this function,
154 * since it will also free up the thread's allocations when its done.
155 */
156 bool IsExporting(bool& pExportResult);
157 #endif /* !FBXSDK_ENV_WINSTORE && ! FBXSDK_ENV_EMSCRIPTEN */
158
159 /** Get the progress status in non-blocking mode.
160 * \param pStatus Optional current status string.
161 * \return Percentage of the finished workload.
162 */
163 float GetProgress(FbxString* pStatus=NULL);
164
165 /** Register a callback function for progress reporting in single thread mode.
166 * \param pCallback Pointer of the callback function.
167 * \param pArgs Pointer to the arguments passed to the callback function.
168 */
169 void SetProgressCallback(FbxProgressCallback pCallback, void* pArgs=NULL);
170 //@}
171
172 /**
173 * \name File Format
174 */
175 //@{
176 /** Get the format of the exported file.
177 * \return File format identifier.
178 */
179 int GetFileFormat();
180
181 /** Return \c true if the file format is a recognized FBX format.
182 */
183 bool IsFBX();
184
185 /** Get the list of writable versions for the current file format.
186 * \return \c NULL or a null terminated array of strings.
187 * \remarks the strings returned match the writers registered for the current format.
188 * The array items can be retrieved with the following code:
189 * \code
190 * char const* const* lWV = lExporter->GetCurrentWritableVersions();
191 * if (lWV)
192 * {
193 * int i = 0;
194 * while (lWV[i] != NULL)
195 * {
196 * printf("fmt = %s\n", lWV[i]);
197 * i++;
198 * }
199 * }
200 * \endcode
201 *
202 */
203 char const* const* GetCurrentWritableVersions();
204
205 /** Set file version for a given file format.
206 * \param pVersion String description of the file format.
207 * \param pRenamingMode Renaming mode.
208 * \return \c true if mode is set correctly
209 */
210 bool SetFileExportVersion(FbxString pVersion, FbxSceneRenamer::ERenamingMode pRenamingMode=FbxSceneRenamer::eNone);
211
212 /** Set the resampling rate (only used when exporting to FBX 5.3 and lower)
213 * \param pResamplingRate resampling rate
214 */
215 inline void SetResamplingRate(double pResamplingRate){ mResamplingRate = pResamplingRate; }
216
217 /** Set the default rendering resolution.
218 * \param pCamName name of the camera.
219 * \param pResolutionMode resolution mode.
220 * \param pW width.
221 * \param pH height.
222 * \remark These values are ignored when exporting to FBX 7.x and higher. With FBX version 6.x and lower,
223 * the HeaderInfo is still accessible for legacy reasons and any other custom writers. For FBX filles,
224 * these values are used by the FBX QuickTime plug-in (obsolete now) to help it get the window size
225 * without loading the whole file. The information contained in the FbxIOFileHeaderInfo is a duplicate
226 * of AspectRatioMode, AspectWidth and AspectHeight properties defined in the FbxCamera class.
227 * Retrieveing the FileHeaderInfo starting from FBX 7.x will always return the uninitialized structure.
228 */
229 void SetDefaultRenderResolution(FbxString pCamName, FbxString pResolutionMode, double pW, double pH);
230
231 /** Get the complete file header information.
232 * \return valid pointer to the complete header information
233 */
234 FbxIOFileHeaderInfo* GetFileHeaderInfo();
235 //@}
236
237/*****************************************************************************************************************************
238** WARNING! Anything beyond these lines is for internal use, may not be documented and is subject to change without notice! **
239*****************************************************************************************************************************/
240#ifndef DOXYGEN_SHOULD_SKIP_THIS
241 bool GetExportOptions(FbxIO* pFbxObject);
242 bool Export(FbxDocument* pDocument, FbxIO* pFbxObject);
243
244protected:
245 virtual void Construct(const FbxObject* pFrom);
246 virtual void Destruct(bool pRecursive);
247 virtual void SetOrCreateIOSettings(FbxIOSettings* pIOSettings, bool pAllowNULL);
248
249 void Reset();
250 bool FileCreate();
251 void FileClose();
252
253private:
254 bool ExportProcess(FbxDocument* pDocument);
255
256 int mFileFormat;
257 FbxWriter* mWriter;
258#if !defined(FBXSDK_ENV_WINSTORE) && !defined(FBXSDK_ENV_EMSCRIPTEN)
259 FbxThread* mExportThread;
260 FbxExportThreadArg* mExportThreadArg;
261 bool mExportThreadResult;
262 bool mIsThreadExporting;
263#endif /* !FBXSDK_ENV_WINSTORE && !FBXSDK_ENV_EMSCRIPTEN */
264 FbxProgress mProgress;
265 FbxStream* mStream;
266 void* mStreamData;
267 FbxString mStrFileVersion;
268 double mResamplingRate;
269 FbxSceneRenamer::ERenamingMode mRenamingMode;
270 FbxIOFileHeaderInfo* mHeaderInfo;
271 FbxIOSettings* mIOSettings;
272 bool mClientIOSettings;
273
274 friend void ExportThread(void*);
275#endif /* !DOXYGEN_SHOULD_SKIP_THIS *****************************************************************************************/
276};
277
278//! Event that is emitted to plugins before a file is exported to the FBX format.
279class FBXSDK_DLL FbxEventPreExport : public FbxEvent<FbxEventPreExport>
280{
281 FBXSDK_EVENT_DECLARE(FbxEventPreExport);
282
283public:
284 FbxEventPreExport(FbxDocument* pDocument) : mDocument(pDocument) {};
285
286 //! The document to be exported
287 FbxDocument* mDocument;
288};
289
290//! Event that is emitted to plugins after a file is exported to the FBX format.
291class FBXSDK_DLL FbxEventPostExport : public FbxEvent<FbxEventPostExport>
292{
293 FBXSDK_EVENT_DECLARE(FbxEventPostExport);
294
295public:
296 FbxEventPostExport(FbxDocument* pDocument) : mDocument(pDocument) {};
297
298 //! The document to be exported
299 FbxDocument* mDocument;
300};
301
302#include <fbxsdk/fbxsdk_nsend.h>
303
304#endif /* _FBXSDK_FILEIO_EXPORTER_H_ */
305