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 fbxplugin.h
13#ifndef _FBXSDK_CORE_PLUGIN_H_
14#define _FBXSDK_CORE_PLUGIN_H_
15
16#include <fbxsdk/fbxsdk_def.h>
17
18#ifndef FBXSDK_ENV_WINSTORE
19
20#include <fbxsdk/core/fbxobject.h>
21#include <fbxsdk/core/fbxmodule.h>
22#include <fbxsdk/core/fbxlistener.h>
23
24#include <fbxsdk/fbxsdk_nsbegin.h>
25
26class FbxManager;
27class FbxPluginContainer;
28
29//! Plug-in declaration macro that must to be used when defining new FbxPlugin objects.
30#define FBXSDK_PLUGIN_DECLARE(Plugin)\
31 FBXSDK_FRIEND_NEW();\
32public:\
33 static Plugin * Create(const FbxPluginDef& pDefinition, FbxModule pModuleHandle);\
34 void Destroy();
35
36//! Plug-in implementation macro that must be used when implementing new FbxPlugin objects.
37#define FBXSDK_PLUGIN_IMPLEMENT(Plugin)\
38 Plugin* Plugin::Create(const FbxPluginDef& pDefinition, FbxModule pModuleHandle){ return FbxNew<Plugin>(pDefinition, pModuleHandle); }\
39 void Plugin::Destroy(){ FbxDelete(this); }
40
41/** Structure used by plug-ins for identification purposes.
42 * \note To avoid confusions in the system, it is recommended to choose an appropriate unique identifier string name when
43 * defining your plug-in, as well as incrementing the version string to a correct value whenever something changes in the
44 * implementation of the plug-in. Both of these string are used when comparing plug-ins for searches, as well as
45 * identification in FBX files.
46 */
47struct FBXSDK_DLL FbxPluginDef
48{
49 //! Constructor
50 FbxPluginDef() :
51 mName("Unknown Name"),
52 mVersion("Unknown Version")
53 {
54 }
55
56 FbxString mName; //!< The identifier name string of the plug-in. If the name is already used by another plug-in, the plug-in will still register.
57 FbxString mVersion; //!< The version string of the plug-in.
58};
59
60/** Data used to communicate information between an application and the plug-in.
61 */
62struct FBXSDK_DLL FbxPluginData
63{
64 //! Constructor
65 FbxPluginData() :
66 mQueryEmitter(NULL),
67 mSDKManager(NULL),
68 mPluginContainer(NULL)
69 {
70 }
71
72 //! Copy Constructor
73 explicit FbxPluginData(const FbxPluginData& pOther) :
74 mQueryEmitter(pOther.mQueryEmitter),
75 mSDKManager(pOther.mSDKManager),
76 mPluginContainer(pOther.mPluginContainer)
77 {
78 }
79
80 FbxEmitter* mQueryEmitter; //!< The emitter on which the plug-in can listen to receive events.
81 FbxManager* mSDKManager; //!< The FBX SDK Manager on which the plug-in was instanced.
82 FbxPluginContainer* mPluginContainer; //!< The container which will have the ownership of the plug-in.
83};
84
85/** The base class to inherit from when creating new plug-ins for the FBX SDK. Plug-ins for the FBX SDK are extremely flexible
86 * allowing a wide-range of possibilities. For example, one can write his own plug-in to add new readers/writers to the current list
87 * of supported I/O formats, or add new dynamic classes to instantiate custom objects that can later be stored in FBX files. We also use the same
88 * interface for plug-ins written using the FBX Extension SDK, which allow additional callbacks for other various Autodesk products
89 * enabling greater interoperability with multiple various SDKs.
90 *
91 * Here is typical implementation of an FBX SDK plug-in that doesn't do anything else than just registering itself:
92 * \code
93 * class MyPlugin : public FbxPlugin
94 * {
95 * FBXSDK_PLUGIN_DECLARE(MyPlugin); //This macro is mandatory for any plug-in definition
96 *
97 * protected:
98 * explicit MyPlugin(const FbxPluginDef& pDefinition, FbxModule pModuleHandle) : FbxPlugin(pDefinition, pModuleHandle)
99 * {
100 * }
101 *
102 * //Abstract functions that *must* be implemented
103 * virtual bool SpecificInitialize()
104 * {
105 * //For example, here we could register as many new I/O readers/writers as we would like, or classes, etc.
106 * return true;
107 * }
108 *
109 * virtual bool SpecificTerminate()
110 * {
111 * //Here we would have to unregister whatever we registered to the FBX SDK
112 * return true;
113 * }
114 * };
115 *
116 * FBXSDK_PLUGIN_IMPLEMENT(MyPlugin); //This macro is mandatory for any plug-in implementation
117 *
118 * //Standard C export needed for any new FBX SDK plug-in
119 * extern "C"
120 * {
121 * static MyPlugin* sMyPluginInstance = NULL; //The module is owner of the plug-in
122 *
123 * //This function will be called when an application will request the plug-in
124 * #ifdef FBXSDK_ENV_WIN
125 * __declspec(dllexport) void FBXPluginRegistration(FbxPluginContainer& pContainer, FbxModule pModuleHandle)
126 * #else
127 * void FBXPluginRegistration(FbxPluginContainer& pContainer, FbxModule pModuleHandle)
128 * #endif
129 * {
130 * if( sPlugin == NULL )
131 * {
132 * //Create the plug-in definition which contains the information about the plug-in
133 * FbxPluginDef sPluginDef;
134 * sPluginDef.mName = "My Plugin";
135 * sPluginDef.mVersion = "1.0";
136 *
137 * //Create an instance of the plug-in
138 * sMyPluginInstance = MyPlugin::Create(sPluginDef, pLibHandle);
139 *
140 * //Register the plug-in with the FBX SDK
141 * pContainer.Register(*sPlugin);
142 * }
143 * }
144 * }
145 * \endcode
146 * \see FbxPluginDef, FbxPluginData
147 */
148class FBXSDK_DLL FbxPlugin : public FbxListener
149{
150 FBXSDK_INTRUSIVE_LIST_NODE(FbxPlugin, 1);
151
152public:
153 /** Abstract function called once at the end of the plug-in construction. At that moment, plug-in data have been properly initialized.
154 * This function must be implemented by anyone who writes a new plug-in for the FBX SDK.
155 */
156 virtual bool SpecificInitialize()=0;
157
158 /** Abstract function called once at the beginning of the plug-in destruction. At that moment, plug-in data is fully available.
159 * This function must be implemented by anyone who writes a new plug-in for the FBX SDK.
160 */
161 virtual bool SpecificTerminate()=0;
162
163 /** Virtual function called once when the FBX SDK is about to write an FBX file. Users can re-implement it in their plug-in if they need
164 * to perform tasks at that moment. The scene provided in parameter can be altered. If not re-implemented, this function does nothing.
165 * \param pScene The scene that is about to be written in the FBX file.
166 */
167 virtual void WriteBegin(FbxScene& pScene);
168
169 /** Virtual function called once when the FBX SDK is about to write plug-in's parameters. Users can re-implement it in their plug-in if they need
170 * to store properties in the FBX file for their own usage. The object in parameter is used to store those properties.
171 * If not re-implemented, this function does nothing.
172 * \param pParams An abstract object that can be used as a property container, to allow the plug-in to store properties about the plug-in.
173 */
174 virtual void WriteParameters(FbxObject& pParams);
175
176 /** Virtual function called once after the FBX SDK wrote an FBX file. Users can re-implement it in their plug-in if they need
177 * to perform tasks at that moment. The scene provided in parameter can be altered, but the changes will not appear in the FBX file.
178 * If not re-implemented, this function does nothing.
179 * \param pScene The scene that was written in the FBX file.
180 */
181 virtual void WriteEnd(FbxScene& pScene);
182
183 /** Virtual function called once when the FBX SDK is about to read an FBX file. Users can re-implement it in their plug-in if they need
184 * to perform tasks at that moment. The scene provided in parameter can be altered. If not re-implemented, this function does nothing.
185 * \param pScene The scene that is about to be read in the FBX file.
186 */
187 virtual void ReadBegin(FbxScene& pScene);
188
189 /** Virtual function called once after the FBX SDK reads the plug-in's parameters. Users can re-implement it in their plug-in if they need
190 * to retrieve properties for their own usage. The object in parameter is used to retrieve those properties.
191 * If not re-implemented, this function does nothing.
192 * \param pParams An abstract object that can be used as a property container, to allow the plug-in to read properties about the plug-in.
193 */
194 virtual void ReadParameters(FbxObject& pParams);
195
196 /** Virtual function called once after the FBX SDK read an FBX file. Users can re-implement it in their plug-in if they need
197 * to perform tasks at that moment. The scene provided in parameter can be altered. If not re-implemented, this function does nothing.
198 * \param pScene The scene that was read in the FBX file.
199 */
200 virtual void ReadEnd(FbxScene& pScene);
201
202 /** Accessor to the plug-in definition structure that contains basic information on the plug-in like its name or version. This is
203 * the only method available to differentiate plug-ins.
204 * \return The definition structure for this plug-in.
205 */
206 const FbxPluginDef& GetDefinition() const;
207
208 /** Retrieve the module address pointer for this plug-in. With this module instance handle, for example someone can query procedures addresses,
209 * allowing more complex interactions, as well as other operating system module specific functions.
210 */
211 FbxModule GetModuleHdl();
212
213protected:
214 /** Use the Create() and Destroy() methods declared and implemented in the FBXSDK_PLUGIN_DECLARE and FBXSDK_PLUGIN_IMPLEMENT macros to construct and destroy FbxPlugin objects.
215 * \param pDefinition The definition associated with this plug-in. Each plug-in must have its own definition to differentiate it with other plug-ins.
216 * \param pModuleHandle A pointer to the plug-in module address.
217 */
218 explicit FbxPlugin(const FbxPluginDef& pDefinition, FbxModule pModuleHandle);
219
220 /** Accessor to the plug-in private data.
221 * \return The data for the current plug-in.
222 */
223 FbxPluginData& GetData();
224
225 /** Const accessor to the plug-in private data.
226 * \return The const data for the current plug-in.
227 */
228 const FbxPluginData& GetData() 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
234public:
235 inline FbxObject& GetPluginSettings() { return *mPluginSettings; }
236 inline const FbxObject& GetPluginSettings() const { return *mPluginSettings; }
237 template <typename EventType, typename ListernerType> inline FbxEventHandler* Bind(void (ListernerType::*pFunc)(const EventType*))
238 {
239 return FbxListener::Bind<EventType,ListernerType>(*(GetData().mQueryEmitter), pFunc );
240 }
241 virtual void Destroy() = 0;
242
243protected:
244 virtual ~FbxPlugin();
245
246private:
247 bool Initialize(const FbxPluginData& pData);
248 bool Terminate();
249
250 bool mInitialized;
251 FbxPluginData mData;
252 FbxPluginDef mDefinition;
253 FbxModule mModuleHandle;
254 FbxObject* mPluginSettings;
255
256 friend class FbxLoadingStrategy;
257#endif /* !DOXYGEN_SHOULD_SKIP_THIS *****************************************************************************************/
258};
259
260#include <fbxsdk/fbxsdk_nsend.h>
261
262#endif /* !FBXSDK_ENV_WINSTORE */
263
264#endif /* _FBXSDK_CORE_PLUGIN_H_ */
265