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 fbxlibrary.h
13#ifndef _FBXSDK_SCENE_LIBRARY_H_
14#define _FBXSDK_SCENE_LIBRARY_H_
15
16#include <fbxsdk/fbxsdk_def.h>
17
18#include <fbxsdk/scene/fbxdocument.h>
19#include <fbxsdk/scene/fbxobjectfilter.h>
20
21#include <fbxsdk/fbxsdk_nsbegin.h>
22
23class FbxLocalizationManager;
24class FbxCriteria;
25
26/** This library class represents libraries that store sub-libraries and shading objects.
27 * Shading objects are objects of class FbxTexture, FbxSurfaceMaterial, and FbxLight.
28 * \nosubgrouping
29 */
30class FBXSDK_DLL FbxLibrary : public FbxDocument
31{
32 FBXSDK_OBJECT_DECLARE(FbxLibrary, FbxDocument);
33
34public:
35 //! Returns a pointer to the parent library if one exists.
36 FbxLibrary* GetParentLibrary(void) const;
37
38 /** Sets whether not this library is a system library.
39 * \param pSystemLibrary A flag which indicates whether or not this library is a system library.
40 */
41 void SystemLibrary(bool pSystemLibrary);
42
43 //! Returns whether or not this library is a system library.
44 bool IsSystemLibrary() const;
45
46 /** The prefix must not include the dash and language code, nor
47 * can it contain the extension. But if you want, it can contain
48 * a folder or sub-folder, such as: locales/mydocloc.
49 * This is resolved using the XRef Manager, with priority
50 * given to the library's ".fbm" folder, if one exists.
51 * \param pPrefix New prefix to be set.
52 */
53 void LocalizationBaseNamePrefix(const char* pPrefix);
54
55 //! Retrieves the localization prefix.
56 FbxString LocalizationBaseNamePrefix() const;
57
58 // =======================================================================
59 //
60 // sub-library
61 //
62 // =======================================================================
63
64 /** Adds a sub-library
65 * \param pSubLibrary The sub-library to be added.
66 * \return \c True if adding the sub-library is successful, returns \c false if not.
67 */
68 bool AddSubLibrary(FbxLibrary* pSubLibrary);
69
70 /** Removes a sub-library
71 * \param pSubLibrary The sub-library to be removed.
72 * \return \c True if the sub-library is removed, \c false if not.
73 */
74 bool RemoveSubLibrary(FbxLibrary* pSubLibrary);
75
76 //! Returns the total number of sub-libraries
77 int GetSubLibraryCount(void) const;
78
79 /** Returns the sub-library at the specified index.
80 * \param pIndex The sub-library index.
81 */
82 FbxLibrary* GetSubLibrary(int pIndex) const;
83
84 /** Clones the specified asset.
85 * \param pToClone The asset to be cloned.
86 * \param pOptionalDestinationContainer The container for the asset copy.
87 * \remarks The asset and all its dependents are cloned.
88 */
89 FbxObject* CloneAsset( FbxObject* pToClone, FbxObject* pOptionalDestinationContainer = NULL) const;
90
91
92 /** Returns a criteria filter which you can use to filter objects
93 * when iterating items in the library. Only real 'assets' are returned,
94 * rather than FBX support objects. This currently includes
95 * lights, environments, materials and textures (maps).
96 * This is typically used to IMPORT from a library.
97 */
98 static FbxCriteria GetAssetCriteriaFilter();
99
100 /** Returns a filter which you should use when you clone / export objects.
101 * This filters out objects that should remain in the asset library.
102 *
103 * Use this to EXPORT from a library (or CLONE from a library).
104 */
105 static FbxCriteria GetAssetDependentsFilter();
106
107 /** Transfers ownership from the source library to this library for any assets passing through the filter.
108 * It is assumed that name conflicts and other details have been resolved beforehand.
109 *
110 * External asset files required by the assets are copied (not moved). It's
111 * up to the owner of the source library to clean up the files if the files are
112 * not on a read-only transport. If this document hasn't been committed yet,
113 * the assets will not be copied.
114 *
115 * Returns true if no filtered assets were skipped. If no assets pass through
116 * the filter, it returns true, because nothing has been skipped.
117 *
118 * This may leave the source library in an invalid state. For example, the source library
119 * would be in an invalid state if you had decided to transfer texture objects to the library,
120 * but materials were kept in the source library.
121 *
122 * To safeguard against this, the transfer disconnects objects, and thus materials
123 * are left without textures.
124 *
125 * When you transfer an object, all its dependents come with it. If you move
126 * a material, it takes the associated textures as well. Although if you moved a texture,
127 * the material would not be transferred with it.
128 * \param pSrcLibrary The source library to be imported.
129 * \return \c True if no filtered assets are skipped.
130 **/
131 bool ImportAssets(FbxLibrary* pSrcLibrary);
132
133 /** Transfers ownership from the source library to this library for any assets passing through the filter.
134 * It is assumed that name conflicts and other details have been resolved beforehand.
135 *
136 * External asset files required by the assets are copied (not moved). It's
137 * up to the owner of the source library to clean up the files if the files are
138 * not on a read-only transport. If this document hasn't been committed yet,
139 * the assets will not be copied.
140 *
141 * Returns true if no filtered assets were skipped. If no assets pass through
142 * the filter, it returns true, because nothing has been skipped.
143 *
144 * This may leave the source library in an invalid state. For example, the source library
145 * would be in an invalid state if you had decided to transfer texture objects to the library,
146 * but materials were kept in the source library.
147 *
148 * To safeguard against this, the transfer disconnects objects, and thus materials
149 * are left without textures.
150 *
151 * When you transfer an object, all its dependents come with it. If you move
152 * a material, it takes the associated textures as well. Although if you moved a texture,
153 * the material would not be transferred with it.
154 * \param pSrcLibrary The source library to be imported.
155 * \param pAssetFilter The asset filter.
156 * \return \c True if no filtered assets are skipped.
157 **/
158 bool ImportAssets(FbxLibrary* pSrcLibrary, const FbxCriteria& pAssetFilter);
159
160
161 /** Returns a new instance of a library member.
162 * This instantiates the first object found that matches the filter.
163 * \param pFBX_TYPE The type of member
164 * \param pFilter A user specified filter
165 * \param pRecurse A flag that indicates whether to check sub-libraries
166 * \param pOptContainer Optional container for the cloned asset
167 * \return A new instance of the member. Note that the new member is not included with this library.
168 */
169 template < class T > T* InstantiateMember( const T* pFBX_TYPE, const FbxObjectFilter& pFilter, bool pRecurse = true, FbxObject* pOptContainer = NULL);
170
171
172 // =======================================================================
173 //
174 // Localization
175 //
176 // =======================================================================
177 /** Returns the localization manager for the library.
178 */
179
180 FbxLocalizationManager& GetLocalizationManager() const;
181
182 /** Localization helper function. Calls the FBX SDK manager implementation.
183 * Sub-classes that manage their own localization can over-ride this function.
184 * \param pID The identifier for the text to localize.
185 * \param pDefault The default text. Uses pID if NULL.
186 * \return The potentially localized text. May return the parameter passed in.
187 */
188 virtual const char* Localize( const char* pID, const char* pDefault = NULL ) const;
189
190 // =======================================================================
191 //
192 // Shading Object
193 //
194 // =======================================================================
195
196 /** Adds a shading object.
197 * \param pShadingObject The shading object to be added.
198 */
199 bool AddShadingObject(FbxObject* pShadingObject);
200
201 /** Removes a shading object.
202 * \param pShadingObject The shading object to be removed.
203 */
204 bool RemoveShadingObject(FbxObject* pShadingObject);
205
206 //! Returns the total number of shading objects
207 int GetShadingObjectCount(void) const;
208
209 /** Returns the shading object at the specified index.
210 * \param pIndex Shading object index.
211 * \return The shading object located at the specified index.
212 */
213 FbxObject* GetShadingObject(int pIndex) const;
214
215 /** Returns the number of shading objects according to their implementations.
216 * \param pCriteria Filtering criteria that identifies what kind of
217 * implementations to consider.
218 * \returns The number of shading objects corresponding to the filtering parameters
219 */
220 int GetShadingObjectCount(const FbxImplementationFilter& pCriteria) const;
221
222 /** Returns a handle on the shading object at the specified index that corresponds to the given filtering parameters.
223 * \param pIndex Shading object index.
224 * \param pCriteria Filtering criteria that identifies what kind of
225 * implementations to consider.
226 * \returns A handle on the shading object at the specified index that corresponds to the given filtering parameters.
227 */
228 FbxObject* GetShadingObject(int pIndex, const FbxImplementationFilter& pCriteria) const;
229
230/*****************************************************************************************************************************
231** WARNING! Anything beyond these lines is for internal use, may not be documented and is subject to change without notice! **
232*****************************************************************************************************************************/
233#ifndef DOXYGEN_SHOULD_SKIP_THIS
234protected:
235 virtual void Construct(const FbxObject* pFrom);
236 virtual void Destruct(bool pRecursive);
237
238 mutable FbxLocalizationManager* mLocalizationManager;
239#endif /* !DOXYGEN_SHOULD_SKIP_THIS *****************************************************************************************/
240};
241
242/*****************************************************************************************************************************
243** WARNING! Anything beyond these lines is for internal use, may not be documented and is subject to change without notice! **
244*****************************************************************************************************************************/
245#ifndef DOXYGEN_SHOULD_SKIP_THIS
246
247template <class T> T* FbxLibrary::InstantiateMember(const T* pFBX_TYPE, const FbxObjectFilter& pFilter, bool pRecurse, FbxObject* pOptContainer)
248{
249 //First check all materials in the library.
250 for( int i = 0; i < GetMemberCount<T>(); ++i )
251 {
252 T* lObject = GetMember<T>(i);
253 if( pFilter.Match(lObject) )
254 return FbxCast<T>(CloneAsset(lObject,pOptContainer));
255 }
256
257 if( pRecurse )
258 {
259 // then check all materials in each sub-library.
260 for( int i = 0; i < GetMemberCount<FbxLibrary>(); ++i )
261 {
262 FbxLibrary* lLibrary = GetMember<FbxLibrary>(i);
263 T* lClonedObject = lLibrary->InstantiateMember(pFBX_TYPE, pFilter, pRecurse, pOptContainer);
264 if( lClonedObject )
265 return lClonedObject;
266 }
267 }
268
269 return NULL;
270}
271
272class FBXSDK_DLL FbxEventPopulateSystemLibrary : public FbxEvent<FbxEventPopulateSystemLibrary>
273{
274 FBXSDK_EVENT_DECLARE(FbxEventPopulateSystemLibrary)
275
276public:
277 FbxEventPopulateSystemLibrary(FbxLibrary* pLibrary) { mLibrary = pLibrary; }
278 inline FbxLibrary* GetLibrary() const { return mLibrary; }
279
280private:
281 FbxLibrary* mLibrary;
282};
283
284class FBXSDK_DLL FbxEventUpdateSystemLibrary : public FbxEvent<FbxEventUpdateSystemLibrary>
285{
286 FBXSDK_EVENT_DECLARE(FbxEventUpdateSystemLibrary)
287
288public:
289 FbxEventUpdateSystemLibrary(FbxLibrary *pLibrary) { mLibrary = pLibrary; }
290 inline FbxLibrary* GetLibrary() const { return mLibrary; }
291
292private:
293 FbxLibrary* mLibrary;
294};
295
296class FBXSDK_DLL FbxEventWriteLocalization : public FbxEvent<FbxEventWriteLocalization>
297{
298 FBXSDK_EVENT_DECLARE(FbxEventWriteLocalization)
299
300public:
301 FbxEventWriteLocalization(FbxLibrary* pAssetLibrary) { mAssetLibrary = pAssetLibrary; }
302 inline FbxLibrary* GetLibrary() const { return mAssetLibrary; }
303
304private:
305 FbxLibrary* mAssetLibrary;
306};
307
308class FBXSDK_DLL FbxEventMapAssetFileToAssetObject : public FbxEvent<FbxEventMapAssetFileToAssetObject>
309{
310 FBXSDK_EVENT_DECLARE(FbxEventMapAssetFileToAssetObject)
311
312public:
313 FbxEventMapAssetFileToAssetObject(const char* pFile) :
314 mAsset(NULL),
315 mFilePath( pFile )
316 {
317 }
318
319 inline const char* GetFilePath() const { return mFilePath; }
320 mutable FbxObject* mAsset;
321
322private:
323 FbxString mFilePath;
324};
325
326#endif /* !DOXYGEN_SHOULD_SKIP_THIS *****************************************************************************************/
327
328#include <fbxsdk/fbxsdk_nsend.h>
329
330#endif /* _FBXSDK_SCENE_LIBRARY_H_ */
331