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 fbxscene.h
13#ifndef _FBXSDK_SCENE_H_
14#define _FBXSDK_SCENE_H_
15
16#include <fbxsdk/fbxsdk_def.h>
17
18#include <fbxsdk/core/base/fbxmultimap.h>
19#include <fbxsdk/core/base/fbxcharptrset.h>
20#include <fbxsdk/scene/fbxdocument.h>
21#include <fbxsdk/scene/animation/fbxanimevaluator.h>
22#include <fbxsdk/scene/geometry/fbxlayer.h>
23#include <fbxsdk/scene/geometry/fbxnodeattribute.h>
24#include <fbxsdk/fileio/fbxiosettings.h>
25#include <fbxsdk/fileio/fbxglobalsettings.h>
26
27#include <fbxsdk/fbxsdk_nsbegin.h>
28
29class FbxGeometry;
30class FbxTexture;
31class FbxSurfaceMaterial;
32class FbxCharacter;
33class FbxControlSetPlug;
34class FbxGenericNode;
35class FbxPose;
36class FbxCharacterPose;
37class FbxVideo;
38class FbxGlobalLightSettings;
39class FbxGlobalCameraSettings;
40
41/** This class contains the description of a 3D scene. It contains the nodes (including the root node) (FbxNode),
42 * materials, textures, videos, gobos,
43 * poses, characters, character poses, control set plugs,
44 * generic nodes,
45 * scene information, global settings,
46 * and a global evaluator.
47 * The nodes are structured in a tree under the scene's root node.
48 *
49 * When an object is created using the FBX SDK, a scene is usually passed as argument to the
50 * object creation function to specify that the object belongs to this scene.
51 * At this point, a connection is made with the object as source and the scene as destination.
52 *
53 * All objects in the scene can be queried by connection index. In addition,
54 * generic nodes, materials, and textures can also be queried by name. In this latter case, the
55 * first object with the queried name will be returned.
56 *
57 * The global evaluator (FbxAnimEvaluator) is used to compute animation values
58 * for animated scenes.
59 * \nosubgrouping
60 */
61class FBXSDK_DLL FbxScene : public FbxDocument
62{
63 FBXSDK_OBJECT_DECLARE(FbxScene, FbxDocument);
64
65public:
66 //! \name Scene Management
67 //@{
68 //! Clear the scene content by deleting the node tree below the root node and restoring default settings.
69 void Clear();
70
71 /** Get the root node of the scene.
72 * \return Pointer to the root node.
73 * \remarks This node is not saved. Do not use it to apply a global transformation to the node hierarchy. If a global transformation must be applied, insert a new node below this one. */
74 FbxNode* GetRootNode() const;
75 //@}
76
77 //! \name Texture Material and Video Access
78 //@{
79 /** Clear, then fill, a texture array with all existing textures included in the scene.
80 * \param pTextureArray An array of texture pointers. */
81 void FillTextureArray(FbxArray<FbxTexture*>& pTextureArray);
82
83 /** Clear, then fill, a material array with all existing materials included in the scene.
84 * \param pMaterialArray An array of material pointers. */
85 void FillMaterialArray(FbxArray<FbxSurfaceMaterial*>& pMaterialArray);
86 //@}
87
88 //! \name Generic Node Access
89 //@{
90 /** Get number of generic nodes in the scene.
91 * \return Number of Generic Nodes in this scene. */
92 int GetGenericNodeCount() const;
93
94 /** Get generic node at given index.
95 * \param pIndex Position in the list of the generic nodes.
96 * \return Pointer to the generic node or \c NULL if the index is out of bounds.
97 */
98 FbxGenericNode* GetGenericNode(int pIndex);
99
100 /** Access a generic node from its name.
101 * \param pName Name of the generic node.
102 * \return found generic node
103 */
104 FbxGenericNode* GetGenericNode(char* pName);
105
106 /** Add a generic node to this scene.
107 * \param pGenericNode Pointer to the generic node to be added.
108 * \return If the passed parameter is \c NULL, this method will return \c false, otherwise \c true. */
109 bool AddGenericNode(FbxGenericNode* pGenericNode);
110
111 /** Remove the generic node from this scene.
112 * \param pGenericNode Pointer to the generic node to be removed.
113 * \return If the passed parameter is \c NULL, this method will return \c false, otherwise \c true.
114 * \remarks The pointed object is not referenced by the scene anymore but is not deleted. */
115 bool RemoveGenericNode(FbxGenericNode* pGenericNode);
116 //@}
117
118
119 //! \name Character Management
120 //@{
121 /** Get number of characters.
122 * \return Number of characters in this scene. */
123 int GetCharacterCount() const;
124
125 /** Get character at given index.
126 * \param pIndex Position in the list of the characters.
127 * \return Pointer to the character or \c NULL if index is out of bounds. */
128 FbxCharacter* GetCharacter(int pIndex);
129
130 /** Create a new character.
131 * \param pName Name given to character.
132 * \return Index of the created character. */
133 int CreateCharacter(const char* pName);
134
135 /** Destroy character.
136 * \param pIndex Specify which character to destroy. */
137 void DestroyCharacter(int pIndex);
138 //@}
139
140 //! \name ControlSetPlug Management
141 //@{
142 /** Get number of ControlSetPlugs.
143 * \return Number of ControlSet plugs in this scene. */
144 int GetControlSetPlugCount() const;
145
146 /** Get ControlSetPlug at given index.
147 * \param pIndex Position in the list of the ControlSetPlug
148 * \return Pointer to ControlSetPlug or \c NULL if index is out of bounds. */
149 FbxControlSetPlug* GetControlSetPlug(int pIndex);
150
151 /** Create a new ControlSetPlug.
152 * \param pName Name given to ControlSetPlug.
153 * \return Index of created ControlSetPlug. */
154 int CreateControlSetPlug(char* pName);
155
156 /** Destroy ControlSetPlug.
157 * \param pIndex Specify which ControlSetPlug to destroy. */
158 void DestroyControlSetPlug(int pIndex);
159 //@}
160
161 //! \name Character Pose Management
162 //@{
163 /** Get number of character poses.
164 * \return Number of character poses in this scene.
165 * \remarks Character Poses and Poses are two distinct entities having their own lists. */
166 int GetCharacterPoseCount() const;
167
168 /** Get character pose at given index.
169 * \param pIndex Position in the list of character poses.
170 * \return Pointer to the character pose or \c NULL if index is out of bounds. */
171 FbxCharacterPose* GetCharacterPose(int pIndex);
172
173 /** Create a new character pose.
174 * \param pName Name given to character pose.
175 * \return Index of created character pose. */
176 int CreateCharacterPose(char* pName);
177
178 /** Destroy character pose.
179 * \param pIndex Specify which character pose to destroy. */
180 void DestroyCharacterPose(int pIndex);
181 //@}
182
183 //! \name Pose Management
184 //@{
185 /** Get number of poses.
186 * \return Number of poses in the scene.
187 * \remarks Poses and Character Poses are two distinct entities having their own lists. */
188 int GetPoseCount() const;
189
190 /** Get pose at given index.
191 * \param pIndex Position in the list of poses.
192 * \return Pointer to the pose or \c NULL if index is out of bounds. */
193 FbxPose* GetPose(int pIndex);
194
195 /** Add a pose to this scene.
196 * \param pPose The pose (for example: bind pose, rest pose) to be added to the scene.
197 * \return If the pose is correctly added to the scene, return \c true. Otherwise, if the pose is already in the scene, return \c false. */
198 bool AddPose(FbxPose* pPose);
199
200 /** Remove the specified pose from the scene.
201 * \param pPose The pose (for example: bind pose, rest pose) to be removed from the scene.
202 * \return If the pose was successfully removed from the scene, return \c true. Otherwise, if the pose could not be found return \c false. */
203 bool RemovePose(FbxPose* pPose);
204
205 /** Remove the pose at the given index from the scene.
206 * \param pIndex Index of the pose to be removed.
207 * \return If the pose was successfully removed from the scene, return \c true. Otherwise, if the pose could not be found return \c false. */
208 bool RemovePose(int pIndex);
209 //@}
210
211 //! \name Scene information
212 //@{
213 /** Get the scene information.
214 * \return Pointer to the scene information object. */
215 FbxDocumentInfo* GetSceneInfo() { return GetDocumentInfo(); }
216
217 /** Set the scene information.
218 * \param pSceneInfo Pointer to the scene information object. */
219 void SetSceneInfo(FbxDocumentInfo* pSceneInfo) { SetDocumentInfo(pSceneInfo); }
220 //@}
221
222 //! \name Global Settings
223 //@{
224 /** Access global settings.
225 * \return Reference to the Global Settings. */
226 FbxGlobalSettings& GetGlobalSettings();
227
228 /** Const access to global settings.
229 * \return Const reference to the Global Settings. */
230 const FbxGlobalSettings& GetGlobalSettings() const;
231 //@}
232
233 /** \name Scene Animation Evaluation
234 * The scene's animation evaluator is used to compute animation values for animated scenes. A typical
235 * usage would be to compute the global transform matrix of a node \c lNode at a given time \c lTime.
236 * \code
237 FbxAMatrix& lGlobalMatrix = lNode->GetScene()->GetAnimationEvaluator()->GetNodeGlobalTransform(lNode, lTime);
238
239 or the exact equivalent:
240
241 FbxAMatrix& lGlobalMatrix = lNode->EvaluateGlobalTransform(lTime);
242 * \endcode
243 *
244 * The user can create one or more evaluators in the scene. The default evaluator is set using SetEvaluator. When
245 * GetEvaluator is called, if the scene has no evaluator, an evaluator is created with default values. */
246 //@{
247 /** Set the current animation stack context used by the animation evaluator.
248 * \param pAnimStack The animation stack to set as current.
249 * \remark Changing the current animation stack will also cause the animation evaluator to reset its state. */
250 void SetCurrentAnimationStack(FbxAnimStack* pAnimStack);
251
252 /** Retrieve the current animation stack.
253 * \return the current animation stack. If none were set previously, the default one will be returned if it exists. */
254 FbxAnimStack* GetCurrentAnimationStack();
255
256 /** Set the global evaluator used by this scene evaluation engine.
257 * \param pEvaluator The evaluator to be used for evaluation processing of this scene. */
258 void SetAnimationEvaluator(FbxAnimEvaluator* pEvaluator);
259
260 /** Get the global evaluator used by this scene evaluation engine.
261 * If no evaluator were previously set, this function will return either the first evaluator found attached to this scene, or a new default evaluator.
262 * \return The evaluator to be used for evaluation processing of this scene. */
263 FbxAnimEvaluator* GetAnimationEvaluator();
264 //@}
265
266 /** Clear then fill a pose array with all existing pose included in the scene.
267 * \param pPoseArray An array of pose pointers. */
268 void FillPoseArray(FbxArray<FbxPose*>& pPoseArray);
269
270 //! \name Material Access
271 //@{
272 /** Get number of materials.
273 * \return Number of materials in this scene. */
274 int GetMaterialCount() const;
275
276 /** Get the material at the given index.
277 * \param pIndex Position in the list of materials.
278 * \return Pointer to the material or \c NULL if the index is out of bounds.
279 * \remarks pIndex must be between 0 and GetMaterialCount(). */
280 FbxSurfaceMaterial* GetMaterial(int pIndex);
281
282 /** Get the material by its name.
283 * \param pName Name of the material.
284 * \return Pointer to the material or \c NULL if not found. */
285 FbxSurfaceMaterial* GetMaterial(char* pName);
286
287 /** Add the material to this scene.
288 * \param pMaterial Pointer to the material to be added.
289 * \return true on successful addition. */
290 bool AddMaterial(FbxSurfaceMaterial* pMaterial);
291
292 /** Remove the material from this scene.
293 * \param pMaterial Pointer to the material to be removed.
294 * \return true on successful removal. */
295 bool RemoveMaterial(FbxSurfaceMaterial* pMaterial);
296 //@}
297
298 //! \name Texture Access
299 //@{
300 /** Get number of textures (type FbxTexture).
301 * \return Number of textures in this scene. Includes types FbxFileTexture, FbxLayeredTexture and FbxProceduralTexture.
302 * \remarks To get the number of textures of a specific type, use GetSrcCount(). For example:
303 * \code
304 * int lNbFileTextures = lScene->GetSrcObjectCount<FbxFileTexture>();
305 * int lNbLayeredTextures = lScene->GetSrcObjectCount<FbxLayeredTexture>();
306 * int lNbProceduralTextures = lScene->GetSrcObjectCount<FbxProceduralTexture>();
307 * \endcode */
308 int GetTextureCount() const;
309
310 /** Get the texture at the given index. pIndex must be between 0 and GetTextureCount().
311 * \param pIndex Position in the list of textures.
312 * \return Pointer to the texture or \c NULL if the index is out of bounds.
313 * \remarks To get the texture of a specific texture type, use GetSrcObject(). For example:
314 * \code
315 * FbxFileTexture* lFileTexture = lScene->GetSrcObject<FbxFileTexture>(i);
316 * FbxLayeredTexture* lLayeredTexture = lScene->GetSrcObject<FbxLayeredTexture>(i);
317 * FbxProceduralTexture* lProceduralTexture = lScene->GetSrcObject<FbxProceduralTexture>(i);
318 * \endcode */
319 FbxTexture* GetTexture(int pIndex);
320
321 /** Get the texture by its name.
322 * \param pName Name of the texture.
323 * \return Pointer to the texture or \c NULL if not found. */
324 FbxTexture* GetTexture(char* pName);
325
326 /** Add the texture to this scene.
327 * \param pTexture Pointer to the texture to be added.
328 * \return \c true on successful addition. */
329 bool AddTexture(FbxTexture* pTexture);
330
331 /** Remove the texture from this scene.
332 * \param pTexture Pointer to the texture to be removed.
333 * \return \c true on successful removal. */
334 bool RemoveTexture(FbxTexture* pTexture);
335 //@}
336
337 //! \name Node Access
338 //@{
339 /** Get number of nodes.
340 * \return Number of nodes in this scene. */
341 int GetNodeCount() const;
342
343 /** Get the node at the given index.
344 * \param pIndex Position in the list of nodes.
345 * \return Pointer to the node or \c NULL if the index is out of bounds.
346 * \remarks pIndex must be between 0 and GetNodeCount(). */
347 FbxNode* GetNode(int pIndex);
348
349 /** Add the node to this scene.
350 * \param pNode Pointer to the node to be added.
351 * \return true on successful addition. */
352 bool AddNode(FbxNode* pNode);
353
354 /** Remove the node from this scene.
355 * \param pNode Pointer to the node to be removed.
356 * \return true on successful removal. */
357 bool RemoveNode(FbxNode* pNode);
358
359 /** Helper method for determining the number of nodes that have curves on surface attributes in the scene. Since the curve-on-surface
360 * nodes are connected to nurbs geometry and not any FbxNode in the scene, they won't normally be picked up in a graph traversal.
361 * \return The number of curve-on-surface nodes in the scene */
362 int GetCurveOnSurfaceCount();
363
364 /** Get the first node with this name.
365 * \param pName Name of the node.
366 * \return Pointer to the node, or \c NULL if node is not found. */
367 FbxNode* FindNodeByName(const FbxString& pName);
368 //@}
369
370 //! \name Geometry Access
371 //@{
372 /** Get number of geometries.
373 * \return Number of geometries in this scene. */
374 int GetGeometryCount() const;
375
376 /** Get the geometry at the given index.
377 * \param pIndex Position in the list of geometries.
378 * \return Pointer to the geometry or \c NULL if the index is out of bounds.
379 * \remarks pIndex must be between 0 and GetGeometryCount(). */
380 FbxGeometry* GetGeometry(int pIndex);
381
382 /** Add the geometry to this scene.
383 * \param pGeometry Pointer to the geometry to be added.
384 * \return true on successful addition. */
385 bool AddGeometry(FbxGeometry* pGeometry);
386
387 /** Remove the geometry from this scene.
388 * \param pGeometry Pointer to the geometry to be removed.
389 * \return true on successful removal. */
390 bool RemoveGeometry(FbxGeometry* pGeometry);
391 //@}
392
393 //! \name Video Access
394 //@{
395 /** Get number of videos.
396 * \return Number of videos in this scene. */
397 int GetVideoCount() const;
398
399 /** Get the video at the given index.
400 * \param pIndex Position in the list of videos.
401 * \return Pointer to the video or \c NULL if the index is out of bounds.
402 * \remarks pIndex must be between 0 and GetVideoCount(). */
403 FbxVideo* GetVideo(int pIndex);
404
405 /** Add the video to this scene.
406 * \param pVideo Pointer to the video to be added.
407 * \return true on successful addition. */
408 bool AddVideo(FbxVideo* pVideo);
409
410 /** Remove the video from this scene.
411 * \param pVideo Pointer to the video to be removed.
412 * \return true on successful removal. */
413 bool RemoveVideo(FbxVideo* pVideo);
414 //@}
415
416 /** \name Utilities */
417 //@{
418 /** Synchronize all the Show properties of node instances.
419 * Walks all the node attributes defined in the scene and synchronize the Show property of all the nodes that reference the node attribute so that they all contain the same value.
420 * This method should be called after the FBX scene is completely created, typically right after the calls to the FbxImporter::Import() or just before the calls to the FbxExporter::Export().
421 * \remarks Applications only need to call this method if their interpretation of the Show property implies that setting the Show state on one instance affect all of them.
422 * \see FbxNode::Visibility property, FbxNode::Show property */
423 void SyncShowPropertyForInstance();
424
425 /** Compute the bounding box and its center for all (or selected) nodes.
426 * \param pBBoxMin The minimum value of the bounding box upon successful return.
427 * \param pBBoxMax The maximum value of the bounding box upon successful return.
428 * \param pBBoxCenter The center value of the bounding box upon successful return.
429 * \param pSelected If \c true, only take into account selected geometry, otherwise take all geometry into account.
430 * \param pTime If different from FBXSDK_TIME_INFINITE, time used to compute the bounding box for deformed geometry.
431 * \return \c true if successful, otherwise \c false.
432 * \remark If geometry have been unloaded from memory, their bounding box cannot be calculated and will use any value set previously. */
433 bool ComputeBoundingBoxMinMaxCenter(FbxVector4& pBBoxMin, FbxVector4& pBBoxMax, FbxVector4& pBBoxCenter, bool pSelected=false, const FbxTime& pTime=FBXSDK_TIME_INFINITE);
434 //@}
435
436/*****************************************************************************************************************************
437** WARNING! Anything beyond these lines is for internal use, may not be documented and is subject to change without notice! **
438*****************************************************************************************************************************/
439#ifndef DOXYGEN_SHOULD_SKIP_THIS
440 void ConvertNurbsSurfaceToNurbs();
441 void ConvertMeshNormals();
442 void ConvertNurbsCurvesToNulls();
443 void ConnectTextures();
444 void BuildTextureLayersDirectArray();
445 void FixInheritType(FbxNode *pNode);
446
447 void UpdateScaleCompensate(FbxNode *pNode, FbxIOSettings& pIOS);
448
449 FbxClassId ConvertAttributeTypeToClassID(FbxNodeAttribute::EType pAttributeType);
450
451 // These data structures are only used for legacy FBX files (version 6.x and earlier). The
452 // validity of their content is not guaranteed with the most recent versions.
453 FbxGlobalLightSettings& GlobalLightSettings() { return *mGlobalLightSettings; }
454 FbxGlobalCameraSettings& GlobalCameraSettings() { return *mGlobalCameraSettings; }
455
456 // Clone this scene object (and everything else it contains if clone type is eDeepClone)
457 virtual FbxObject* Clone(FbxObject::ECloneType pCloneType=eDeepClone, FbxObject* pContainer=NULL, void* pSet = NULL) const;
458 virtual FbxObject& Copy(const FbxObject& pObject);
459
460 void ConnectMaterials();
461
462 void BuildMaterialLayersDirectArray();
463 void ReindexMaterialConnections(); // called to make sure that eIndex is remapped to eIndexToDirect
464
465 FbxMultiMap* AddTakeTimeWarpSet(char *pTakeName);
466 FbxMultiMap* GetTakeTimeWarpSet(char *pTakeName);
467
468 // This function will destroy the scene (and all the objects directly connected to it) without sending
469 // the Connect notifications nor trying to disconnect the objects first. This is a bypass of the intended
470 // workflow and should be used with care.
471 void ForceKill();
472
473private:
474 virtual void Construct(const FbxObject* pFrom);
475 virtual void Destruct(bool pRecursive);
476
477 void ConnectTextureLayerElement(FbxLayerContainer* pLayerContainer, FbxLayerElement::EType pLayerType, FbxNode* pParentNode);
478 void BuildTextureLayersDirectArrayForLayerType(FbxLayerContainer* pLayerContainer, FbxLayerElement::EType pLayerType);
479
480 FbxNode* mRootNode;
481 FbxGlobalLightSettings* mGlobalLightSettings;
482 FbxGlobalCameraSettings* mGlobalCameraSettings;
483 FbxAnimEvaluator* mAnimationEvaluator;
484 FbxAnimStack* mCurrentAnimationStack;
485 FbxCharPtrSet mTakeTimeWarpSet;
486#endif /* !DOXYGEN_SHOULD_SKIP_THIS *****************************************************************************************/
487};
488
489#include <fbxsdk/fbxsdk_nsend.h>
490
491#endif /* _FBXSDK_SCENE_H_ */
492