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 fbxdocument.h
13#ifndef _FBXSDK_SCENE_DOCUMENT_H_
14#define _FBXSDK_SCENE_DOCUMENT_H_
15
16#include <fbxsdk/fbxsdk_def.h>
17
18#include <fbxsdk/scene/fbxcollection.h>
19
20#include <fbxsdk/fbxsdk_nsbegin.h>
21
22class FbxStatus;
23class FbxTakeInfo;
24class FbxPeripheral;
25class FbxDocumentInfo;
26
27/** FbxDocument is a base class for FbxScene and FbxLibrary classes.
28 * A document is a collection (FbxCollection) of objects (FbxObject), called the root member objects.
29 * This is because these objects each form the root of an object graph. The manager (FbxManager) has access to all
30 * documents, scenes and libraries.
31 *
32 * A document can be contained in another document, thus, a hierarchy of documents
33 * can be built. The root of all documents is simply called the root document.
34 *
35 * A document manages animation stacks (FbxAnimStack). It also provides access to animation stack information (FbxTakeInfo).
36 *
37 * A document carries information in its FbxDocumentInfo.
38 *
39 * Documents manage peripherals to load and unload objects (see class FbxPeripheral),
40 * as well as references to other objects or documents.
41 *
42 * Error management is also available.
43 *
44 * \nosubgrouping
45 */
46class FBXSDK_DLL FbxDocument : public FbxCollection
47{
48 FBXSDK_OBJECT_DECLARE(FbxDocument, FbxCollection);
49
50public:
51 /**
52 * \name Properties
53 */
54 //@{
55 FbxPropertyT<FbxReference> Roots;
56 //@}
57
58 /**
59 * \name Document Member Manager
60 */
61 //@{
62 //! Remove document members and restore default settings.
63 virtual void Clear();
64
65 /** Add a member object and connect it to Roots.
66 * \param pMember Object to add to the document.
67 */
68 inline void AddRootMember(FbxObject* pMember){ AddMember(pMember); Roots.ConnectSrcObject(pMember); }
69
70 /** Remove a member object from the document.
71 * \param pMember Object to remove from the document.
72 */
73 inline void RootRootRemoveMember(FbxObject* pMember){ RemoveMember(pMember); Roots.DisconnectSrcObject(pMember); }
74
75 /** Find a member object in the document, that has the given type and name.
76 * \param pName Member name. */
77 template <class T> inline T* FindRootMember(char* pName){ return Roots.FindSrcObject<T>(pName); }
78
79 //! Return the number of objects in the document.
80 inline int GetRootMemberCount () const { return Roots.GetSrcObjectCount(); }
81
82 /** Return the number of objects of class T in the document.
83 * \return The number of objects of class T in the document. */
84 template <class T> inline int GetRootMemberCount() const { return Roots.GetSrcObjectCount<T>(); }
85
86 /** Return the number of objects of the document that satisfy the given criteria.
87 * \param pCriteria Criteria for selecting objects.
88 * \return The number of objects satisfying the given criteria.
89 */
90 int GetRootMemberCount(FbxCriteria pCriteria) const;
91
92 /** Return the member of the document at given index.
93 * \param pIndex Selection index.
94 */
95 inline FbxObject* GetRootMember(int pIndex=0) const { return Roots.GetSrcObject(pIndex); }
96
97 /** Return the member of class T of the document at given index.
98 * \param pIndex Selection index. */
99 template <class T> inline T* GetRootMember(int pIndex=0) const { return Roots.GetSrcObject<T>(pIndex); }
100
101 /** Return the document member which satisfies given criteria, for given index.
102 * \param pCriteria Criteria for selecting objects.
103 * \param pIndex Selection index.
104 */
105 FbxObject* GetRootMember(FbxCriteria pCriteria, int pIndex=0) const;
106
107 /** Is an object part of the document.
108 * \param pMember Queried object.
109 * \return \c true if pMember is an object part of the document, \c false otherwise.
110 */
111 virtual bool IsRootMember(FbxObject* pMember) const;
112 //@}
113
114
115 /**
116 * \name Document information
117 */
118 //@{
119 /** Get the document information.
120 * \return Pointer to the document information object.
121 */
122 FbxDocumentInfo* GetDocumentInfo() const;
123
124 /** Set the document information.
125 * \param pSceneInfo Pointer to the document information object.
126 */
127 void SetDocumentInfo(FbxDocumentInfo* pSceneInfo);
128 //@}
129
130 /**
131 * \name Offloading management
132 *
133 * Documents manage peripherals to load and unload objects (see
134 * class FbxPeripheral). A peripheral manipulates the content
135 * of an object. For instance, a peripheral can load the connections
136 * of an object on demand.
137 *
138 * The document does not own the peripheral therefore
139 * it will not attempt to delete it at destruction time. Cloning
140 * the document will share the pointer to the peripheral across
141 * the cloned objects. The assignment operator has a similar behavior.
142 */
143 //@{
144 /** Set the current peripheral to be used to load or unload objects from this document.
145 * \param pPeripheral The peripheral to be set.
146 */
147 void SetPeripheral(FbxPeripheral* pPeripheral);
148
149 /** Retrieve the current peripheral of the document.
150 * \return Current peripheral.
151 */
152 virtual FbxPeripheral* GetPeripheral();
153
154 /** Unload all the unloadable objects contained in the document using the currently set peripheral.
155 * \param pStatus The FbxStatus object to hold error codes.
156 * \return The number of objects that the document has been able to unload.
157 */
158 int UnloadContent(FbxStatus* pStatus = NULL);
159
160 /** Load all the objects contained in the document with the data from the currently set peripheral.
161 * \param pStatus The FbxStatus object to hold error codes.
162 * \return The number of loaded objects.
163 */
164 int LoadContent(FbxStatus* pStatus = NULL);
165
166 //@}
167
168 /**
169 * \name Referencing management
170 */
171 //@{
172
173 /**
174 * Fills an array of pointers to documents that reference objects in this document.
175 *
176 * \param pReferencingDocuments Array of pointers to documents.
177 * \returns Number of documents that reference objects in this document.
178 */
179 int GetReferencingDocuments(FbxArray<FbxDocument*>& pReferencingDocuments) const;
180
181 /**
182 * Fills an array of pointers to objects in a given document (pFromDoc)
183 * that reference objects in this document.
184 *
185 * \param pFromDoc Pointer to the document containing referencing objects.
186 * \param pReferencingObjects Array of pointers to referencing objects.
187 * \returns Number of objects that reference objects in this document.
188 */
189 int GetReferencingObjects(const FbxDocument* pFromDoc, FbxArray<FbxObject*>& pReferencingObjects) const;
190
191 /**
192 * Fills an array of pointers to documents that are referenced by objects in this document.
193 *
194 * \param pReferencedDocuments Array of pointers to documents.
195 * \returns Number of documents that are referenced by objects in this document.
196 */
197 int GetReferencedDocuments(FbxArray<FbxDocument*>& pReferencedDocuments) const;
198
199 /**
200 * Fills an array of pointers to objects in a given document (pToDoc)
201 * that are referenced by objects in this document.
202 *
203 * \param pToDoc Pointer to the document containing referenced objects.
204 * \param pReferencedObjects Array of pointers to referenced objects.
205 * \returns Number of objects that are referenced by objects in this document.
206 */
207 int GetReferencedObjects(const FbxDocument* pToDoc, FbxArray<FbxObject*>& pReferencedObjects) const;
208
209 /**
210 * Gets the path string to the root document, if the current document is contained in another document.
211 \returns Path to the root document.
212 */
213 FbxString GetPathToRootDocument(void) const;
214 /**
215 * Gets the document path to the root document as an array of documents, if the current document is contained in another document.
216 * \param pDocumentPath Array of FbxDocument to store the document path.
217 * \param pFirstCall Recursive flag: always use pFirstCall = \c true.
218 */
219 void GetDocumentPathToRootDocument(FbxArray<FbxDocument*>& pDocumentPath, bool pFirstCall = true) const;
220
221 /**
222 * Tells if this document is a root document.
223 \return \c false if the current document is contained in another document, \c true otherwise.
224 */
225 bool IsARootDocument(void) { return (NULL == GetDocument()); }
226 //@}
227
228 /**
229 * \name Animation Stack Management
230 * \remarks Animation stacks replaces the deprecated takes.
231 */
232 //@{
233 /** Holds the name of the FbxAnimStack that the application uses for animation in this document.
234 */
235 FbxPropertyT<FbxString> ActiveAnimStackName;
236
237 /** Adds a new animation stack object to this document.
238 * In case of error, FbxDocument::GetLastErrorID() will return
239 * \c eTakeError.
240 * \param pName Animation stack name.
241 * \param pStatus The FbxStatus object to hold error codes.
242 * \return \c true if a new FbxAnimStack has been successfully created,
243 * \c false if an error occurred or if the specified name defines
244 * a FbxAnimStack that already exists in the document.
245 */
246 bool CreateAnimStack(const char* pName, FbxStatus* pStatus = NULL);
247
248 /** Destroy the animation stack object identified by pName from this document.
249 * \param pName Name of the animation stack to be deleted.
250 * \return \c true if the FbxAnimStack has been destroyed and \c false otherwise.
251 */
252 bool RemoveAnimStack(const char* pName);
253
254 /** Fill a string array with all existing animation stack names.
255 * The array of string is cleared before it is used
256 * \param pNameArray An array of string objects.
257 */
258 void FillAnimStackNameArray(FbxArray<FbxString*>& pNameArray);
259
260 //@}
261
262 /**
263 * \name Animation Stack Information Management
264 * \remark Although takes are deprecated, class FbxTakeInfo is not deprecated and
265 * now contains animation stack information.
266 */
267 //@{
268 /** Set information about an animation stack.
269 * \param pTakeInfo Animation stack information. Field FbxTakeInfo::mName specifies
270 * the targeted animation stack.
271 * \return \c true if animation stack is found with this name, and if information is set.
272 */
273 bool SetTakeInfo(const FbxTakeInfo& pTakeInfo);
274
275 /** Get information about an animation stack.
276 * \param pTakeName Name of the targeted animation stack.
277 * \return Animation stack information, or \c NULL if animation stack isn't found or
278 * has no information set for this document.
279 */
280 FbxTakeInfo* GetTakeInfo(const FbxString& pTakeName) const;
281
282 //@}
283
284/*****************************************************************************************************************************
285** WARNING! Anything beyond these lines is for internal use, may not be documented and is subject to change without notice! **
286*****************************************************************************************************************************/
287#ifndef DOXYGEN_SHOULD_SKIP_THIS
288 virtual FbxObject& Copy(const FbxObject& pObject);
289 virtual void Compact();
290 void ConnectVideos();
291
292protected:
293 virtual void Construct(const FbxObject* pFrom);
294 virtual void ConstructProperties(bool pForceSet);
295 virtual void Destruct(bool pRecursive);
296
297 virtual bool ConnectNotify(const FbxConnectEvent& pEvent);
298 virtual void SetDocument(FbxDocument* pDocument);
299
300 bool FindTakeName(const FbxString& pTakeName);
301
302 FbxArray<FbxTakeInfo*> mTakeInfoArray;
303
304private:
305 FbxPeripheral* mPeripheral;
306 FbxDocumentInfo* mDocumentInfo;
307#endif /* !DOXYGEN_SHOULD_SKIP_THIS *****************************************************************************************/
308};
309
310#include <fbxsdk/fbxsdk_nsend.h>
311
312#endif /* _FBXSDK_SCENE_DOCUMENT_H_ */
313