{"type":"doc","content":[{"type":"paragraph","content":[{"text":"This chapter aims at developers who want to extend Vortex with more functionality or communicate from Vortex to and from an external system.","type":"text"}]},{"type":"paragraph"},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"a55970b7-e33c-4032-8321-0aa3bbaab468"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"8c92bfb7-165d-4738-9a1b-37da571b3a7a"}},{"type":"heading","attrs":{"level":1},"content":[{"text":"About Plugins","type":"text"}]},{"type":"paragraph","content":[{"text":"Vortex plugins allow developers to add more functionality to Vortex. Functionality is added by Extensions and Modules.","type":"text"},{"type":"hardBreak"},{"text":"Extensions add features to content: They are mostly data containers with an implementation known by a module.","type":"text"},{"type":"hardBreak"},{"text":"Modules control an aspect of the simulation. They consume the extensions' data and provide behaviour.","type":"text"},{"type":"hardBreak"},{"text":"When an extension is used by a module, it is said that the extension is ","type":"text"},{"text":"managed","type":"text","marks":[{"type":"strong"}]},{"text":" by that Module and is considered ","type":"text"},{"text":"active","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Extensions and Modules are packaged in plugins. Vortex Studio provides multiples plugins and the Vortex Studio SDK allows users to create their own and extend Vortex.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Making a plugin","type":"text"}]},{"type":"paragraph","content":[{"text":"Technically speaking, plugins are actually dynamics libraries with a 'vxp' extension publishing specific interfaces to allow the plugin manager to gather information and instantiate modules and extensions.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Tutorials","type":"text"}]},{"type":"paragraph","content":[{"text":"Vortex Studio provides some tutorials showing how to create a plugin. It is strongly recommended to use them as a starting point. ","type":"text"},{"type":"hardBreak"},{"text":"Vortex uses CMAKE to generate the project solution and comes with a pre-generated Microsoft Visual Studio solution.","type":"text"}]},{"type":"paragraph","content":[{"text":"See code tutorials ","type":"text"},{"text":"C++ Tutorial 1: Plugins","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD2401/pages/3448061705"}}]},{"text":" and ","type":"text"},{"text":"Devices","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD2401/pages/3448062061"}}]},{"text":" for examples.","type":"text"},{"type":"hardBreak"},{"text":"The code tutorial are located in /tutorial","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Vortex Studio will load these .vxp files and will invoke the following methods, which ","type":"text"},{"text":"must","type":"text","marks":[{"type":"strong"}]},{"text":" be implemented:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Plugin.cpp","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"#include // needed to register extensions and modules\n\n#include // needed for type definition\n#include // needed for type definition and GetPluginBuildInfo()\n\n#ifdef _MSC_VER\n#define SYMBOL __declspec(dllexport)\n#else\n#define SYMBOL\n#endif\n \nextern \"C\" SYMBOL bool GetPluginInfo(VxPluginSystem::VxPluginInfo & pluginInfo)\n{\n pluginInfo.setDisplayName(\"My Plugin Name\");\n pluginInfo.setVendor(\"My Vendor Name\");\n pluginInfo.setDescription(\"A description of my plugin\");\n return true;\n}\n\nextern \"C\" SYMBOL bool InitializePlugin(VxPluginSystem::VxPluginManager & pluginManager, int /*unused*/, char ** /*unused*/, std::string * /*unused*/)\n{\n return VxSim::VxExtensionFactory::registerType(MyExtension::kFactoryKey, pluginManager.getCurrentVXP());\n}\n\nextern \"C\" SYMBOL bool UninitializePlugin(VxPluginSystem::VxPluginManager & pluginManager, std::string * /*unused*/)\n{\n return VxSim::VxExtensionFactory::unregisterType(MyExtension::kFactoryKey);\n}","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GetPluginInfo","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Used by the plugin manager to collect information on the plugin so that it can be displayed e.g. in a selection page of the Editor.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Failure to define this function will result in the following error: “Symbol GetPluginInfo was not found in this plugin.”","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"InitializePlugin","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Called by the plugin manager to allow the plugin to register its modules and extensions to the extension factory.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Failure to define this function will result in the following error: “Symbol InitializePlugin was not found in this plugin.”","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"UninitializePlugin","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Called by the plugin manager when unloading the plugin. Extensions and modules should be unregistered from the extension factory.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Failure to define this function will result in the following error: “Symbol UninitializePlugin was not found in this plugin.”","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GetPluginBuildInfo","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Called by the plugin manager when loading the plugin","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This function is defined and declared in ","type":"text"},{"text":"VxPluginSystem/VxPluginSystem.h","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Failure to include this header alongside the other 3 will result in the following error: There is no build information found for this plugin.","type":"text"},{"type":"hardBreak"}]}]}]}]}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Good Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"These methods code should be in a dedicated cpp file, e.g. plugin.cpp, inside the project of your plugin.","type":"text"},{"type":"hardBreak"},{"text":"Each implementation of a module or an extension should have its own cpp and header files.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"error"},"content":[{"type":"paragraph","content":[{"text":"Vortex Studio versions are not binary compatible. When upgrading Vortex Studio to a newer version, custom plugins MUST be recompiled.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Extensions and Modules","type":"text"}]},{"type":"paragraph","content":[{"text":"Extensions are first-class objects of Vortex. In Vortex Studio, everything you see in the Editor is an extension: scenes, parts, graphics galleries, graphic nodes and materials, source and listeners, Python scripts, etc.","type":"text"},{"type":"hardBreak"},{"text":"Objects added to the Setup are also extensions; modules are also extensions. The setup itself is an extension.","type":"text"}]},{"type":"paragraph","content":[{"text":"Knowing how to create extensions is essential for extending Vortex. An extension is a C++ class that implements the ","type":"text"},{"text":"IExtension","type":"text","marks":[{"type":"code"}]},{"text":" interface and some other interfaces depending on the target functionality.","type":"text"},{"type":"hardBreak"},{"text":"An extension is defined by its factory key and the interface it implements. Its data are called fields.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Factory Key","type":"text"}]},{"type":"paragraph","content":[{"text":"Each object is characterized by a factory key. A factory key uniquely defines a type of extension with a ","type":"text"},{"text":"universally unique identifier","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"UUID","type":"text","marks":[{"type":"strong"}]},{"text":").","type":"text"},{"type":"hardBreak"},{"text":"The UUID is simply a 128-bit value that shall never change once the extension is used in content: it will be used when any content is saved.","type":"text"},{"type":"hardBreak"},{"text":"Several tools can be used to generate a UUID (e.g. Visual Studio). ","type":"text"}]},{"type":"panel","attrs":{"panelType":"error"},"content":[{"type":"paragraph","content":[{"text":"Never copy a UUID of an extension to be used for another one as this will confuse the object management.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The factory key also has additional members that help to define the extension with human-readable information.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"FactoryKey","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"/// Information that allow access to a plugin through the VxExtensionFactory\n///\nclass VxFactoryKey\n{\npublic:\n /// UUID for this key\n ///\n VxUuid uuid;\n /// Category name\n ///\n std::string categoryName;\n /// Feature name\n ///\n std::string featureName;\n /// VXP, or DLL, file name if applicable without the extension\n ///\n std::string vxpName;\n};","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"uuid: Unique identifier of the extension","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Category Name: Category for the extension. Used for display in the editor as the category. However, all modules are bundled under modules no matter the category","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"mediaSingle","attrs":{"layout":"align-start","width":30.0},"content":[{"type":"media","attrs":{"width":514,"id":"42a23fe4-d4f5-4472-bcc9-83a40a9b7c42","collection":"contentId-3448056837","type":"file","height":309}}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Feature Name: Type of the extensions. This name appears in the editor in the toolbox","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"vxpname: Name of the vxp having this extension. When the factory creates an extension, it will look up this name and try to find the file having this name plus the extension \".vxp\".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The factory key can be created locally when registering the extension in the plugin. However, the key is also useful when creating or filtering from outside of the plugin so the SDK often publishes the key in a header.","type":"text"}]},{"type":"paragraph","content":[{"text":"The example below is the factory key of the dynamics module (sometimes called the Engine). The module can be loaded from the plugin VxDynamicsPlugin.vxp located in /plugins","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"align-start","width":35.0},"content":[{"type":"media","attrs":{"width":449,"id":"e865a91e-5f9d-4e2d-a018-dc3c101d52fb","collection":"contentId-3448056837","type":"file","height":190}}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"VxDynamicsModuleICD.h","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"/// Factory Key for the VxDynamicsModule\n///\nconst VxSim::VxFactoryKey kFactoryKey(VxSim::VxUuid(\"{3a6c7474-6a01-5f06-ac36-c3a0d7cad4bf}\"), \"Dynamics\", \"Engine\", \"VxDynamicsPlugin\");","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Extension Interface","type":"text"}]},{"type":"paragraph","content":[{"text":"There are three major types of extensions. Any extension must derive from one and only one of these interfaces:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"VxSim::IExtension","type":"text","marks":[{"type":"code"}]},{"text":": an extension that adds features to content (mechanism, scene) or the application.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"VxSim::IObject","type":"text","marks":[{"type":"code"}]},{"text":": an object that has the same features as IExtension, but can also have child extensions (useful to create more complex systems for content).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"VxSim::ISimulatorModule","type":"text","marks":[{"type":"code"}]},{"text":": a module manages certain types of extensions and calls their methods at the appropriate moment during the application update. Modules can only be added to a ","type":"text"},{"text":"VxApplication","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"ApplicationConfig","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The interface will be called at the appropriate moment by Vortex to achieve the desired functionality.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"IExtension Interface","type":"text"}]},{"type":"paragraph","content":[{"text":"IExtension is the most basic interface for extensions. It is necessary to support the basic functionalities of the Vortex Toolkit such as serialization, network, and keyframes.","type":"text"},{"type":"hardBreak"},{"text":"It should generally be used when implementing simple extensions. The extension's data is contained in VxSim::VxExtension which can be obtained with getProxy().","type":"text"}]},{"type":"paragraph","content":[{"text":"IExtension has a single constructor:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"IExtension::IExtension(VxSim::VxExtension* proxy, int version = 0);","type":"text"}]},{"type":"paragraph","content":[{"text":"It must be used by all extensions. The proxy will be provided by VxExtensionFactory but the version needs to be provided by the actual implementation. Versioning will be used when loading and saving the extension.","type":"text"}]},{"type":"paragraph","content":[{"text":"The constructor of an extension always has the following basic form:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"const int kCurrentVersion = 20210315; \n\nclass MyExtension : public VxSim::IExtension \n{ \n\tpublic: \n\t\tMyExtension(VxSim::VxExtension* proxy) \n\t\t\t: VxSim::IExtension(proxy, kCurrentVersion) \n\t\t{ \n\t\t} \n};","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Good Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"A good practice is to use the date of development as the version number. This reduces the risk of problems if several people work on the same code simultaneously.","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Application Context","type":"text"}]},{"type":"paragraph","content":[{"text":"An extension has access to some information about the application, notably the application mode, the current frame, and additional services. See ","type":"text"},{"text":"Vortex Studio SDK Advanced - Integrating the Application","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD2401/pages/3448062110#IntegratingVortexStudiousingtheSDK-MakingaVortexApplication-ApplicationContext"}}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Active and Inactive extension","type":"text"}]},{"type":"paragraph","content":[{"text":"When a module has accepted to manage an extension, the extension itself will be notified with the callback ","type":"text"},{"text":"IExtension::onActive()","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"},{"type":"hardBreak"},{"text":"This method is a good point to initialize your extension, create internal data, and register your observers.","type":"text"},{"type":"hardBreak"},{"text":"An active extension will have its observers called and will be processed by its module. An inactive extension will not be invoked. For example, a dynamics extension is active on the master node and inactive on the slave node. Its data is only processed on the master.","type":"text"},{"type":"hardBreak"},{"text":"When a module is done with an extension, the extension itself will be notified with the callback ","type":"text"},{"text":"IExtension::onInactive()","type":"text","marks":[{"type":"strong"}]},{"text":". This method is a good point to clean up your extension, generally undoing what was done in onActive().","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Good Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"Typically, ","type":"text"},{"text":"IExtension::onActive() ","type":"text","marks":[{"type":"strong"}]},{"text":"and ","type":"text"},{"text":"IExtension::onInactive() ","type":"text","marks":[{"type":"strong"}]},{"text":"are symmetric in behavior, one undoing what the other did.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Each method will be called the same number of times. It is not impossible that an extension becomes active, then inactive during loading, as some features can remove or disable extensions from the content loaded.","type":"text"},{"type":"hardBreak"},{"text":"See below, ","type":"text"},{"text":"onExtensionAdded","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"onExtensionRemoved","type":"text","marks":[{"type":"code"}]},{"text":" for the module equivalent.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"IObject Interface","type":"text"}]},{"type":"paragraph","content":[{"text":"IObject is an extended version of IExtension. In addition to all the functionalities of IExtension, it adds support for sub-extensions. It is generally used when implementing complex extension systems.","type":"text"},{"type":"hardBreak"},{"text":"The object's data is contained in VxSim::VxObject which can be obtained via the getProxy() method.","type":"text"}]},{"type":"paragraph","content":[{"text":"IObject has a single constructor, that is similar to the constructor of IExtension.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"IObject::IObject(VxSim::VxObject* proxy, int version = 0);","type":"text"}]},{"type":"paragraph","content":[{"text":"It must be used by all objects. The proxy will be provided by the VxExtensionFactory but the version needs to be provided by the actual implementation. Versioning will be used when loading and saving the object.","type":"text"}]},{"type":"paragraph","content":[{"text":"The constructor of an object always has this basic form:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"const int kCurrentVersion = 20210315; \n\nclass MyObject : public VxSim::IObject \n{ \n public: MyObject (VxSim::VxObject* proxy) \n : VxSim::IObject(proxy, kCurrentVersion) \n { \n } \n};","type":"text"}]},{"type":"paragraph","content":[{"text":"IObject ","type":"text","marks":[{"type":"strong"}]},{"text":"can accept child extensions, but not all extensions will be accepted. It is recommended to always override the ","type":"text"},{"text":"isCompatible() ","type":"text","marks":[{"type":"em"}]},{"text":"virtual method of IObject. ","type":"text"},{"text":"isCompatible ","type":"text","marks":[{"type":"em"}]},{"text":"works as a filter that will say whether a given extension can be added as a child or not. ","type":"text"}]},{"type":"paragraph","content":[{"text":"If you want the sub-extensions of your ","type":"text"},{"text":"IObject ","type":"text","marks":[{"type":"strong"}]},{"text":"to be visible in the ","type":"text"},{"text":"Vortex Editor","type":"text","marks":[{"type":"em"}]},{"text":", you need to accept ","type":"text"},{"text":"VxSim::IHierarchyView ","type":"text","marks":[{"type":"em"}]},{"text":"in the ","type":"text"},{"text":"isCompatible() ","type":"text","marks":[{"type":"em"}]},{"text":"override. In the example below, MyExtension will be allowed as a sub-extension of ","type":"text"},{"text":"MyObject","type":"text","marks":[{"type":"em"}]},{"text":"; however, without the inclusion of the VxSim::","type":"text"},{"text":"IHierarchyView ","type":"text","marks":[{"type":"em"}]},{"text":"interface type, ","type":"text"},{"text":"MyExtension ","type":"text","marks":[{"type":"em"}]},{"text":"would not be visible in the Vortex Editor.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"bool MyObject::isCompatible(VxSim::VxExtension* extension) const\n{\n if (VxSim::VxSmartInterface(extension).valid()) return true;\n if (VxSim::VxSmartInterface(extension).valid()) return true;\n return false;\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Additional Interfaces for Extensions","type":"text"}]},{"type":"paragraph","content":[{"text":"In addition to IExtension or IObject, an extension usually implements one or several interfaces. The choice of the interface depends on the desired functionality. The following is a list of useful interfaces with the modules that manage them.","type":"text"}]},{"type":"panel","attrs":{"panelType":"error"},"content":[{"type":"paragraph","content":[{"text":"The simulator module that manages an interface must be present in the VxApplication in order for the functionality to work. If it is not present, the extension will be inactive.","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Functionalities","type":"text"}]},{"type":"table","attrs":{"layout":"full-width","width":1800.0,"localId":"55659da2-e0c4-4224-86d9-b2176f4239fe"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[146.0]},"content":[{"type":"paragraph","content":[{"text":"Functionality","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[268.0]},"content":[{"type":"paragraph","content":[{"text":"Interface Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[165.0]},"content":[{"type":"paragraph","content":[{"text":"Managed by","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[1221.0]},"content":[{"type":"paragraph","content":[{"text":"Notes","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[146.0]},"content":[{"type":"paragraph","content":[{"text":"Object with a position","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[268.0]},"content":[{"type":"paragraph","content":[{"text":"VxSim::IMobile","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[165.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1221.0]},"content":[{"type":"paragraph","content":[{"text":"This interface represents an object that can be transformed with a position/orientation/scale.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":2,"colwidth":[146.0]},"content":[{"type":"paragraph","content":[{"text":"Dynamics","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[268.0]},"content":[{"type":"paragraph","content":[{"text":"VxSim::IDynamics","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[165.0]},"content":[{"type":"paragraph","content":[{"text":"Dynamics Engine Module","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1221.0]},"content":[{"type":"paragraph","content":[{"text":"IDynamics is the interface for all the extensions that need to be synchronized with the dynamics engine.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[268.0]},"content":[{"type":"paragraph","content":[{"text":"VxDynamics::ICollidable","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[165.0]},"content":[{"type":"paragraph","content":[{"text":"Dynamics Engine Module","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1221.0]},"content":[{"type":"paragraph","content":[{"text":"ICollidable adds the collision groups, which allows setting up collision rules with the extension.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[146.0]},"content":[{"type":"paragraph","content":[{"text":"Profiling","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[268.0]},"content":[{"type":"paragraph","content":[{"text":"VxSim::Monitoring::IProfilingDataCollector","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[165.0]},"content":[{"type":"paragraph","content":[{"text":"VxApplication","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1221.0]},"content":[{"type":"paragraph","content":[{"text":"Collector of profiling data. The extension will be called with all the profiling data","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[146.0]},"content":[{"type":"paragraph","content":[{"text":"Devices","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[268.0]},"content":[{"type":"paragraph","content":[{"text":"VxSim::IJoystick","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[165.0]},"content":[{"type":"paragraph","content":[{"text":"SDL Joystick Module","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1221.0]},"content":[{"type":"paragraph","content":[{"text":"Receive the raw gamepad/joystick device events. Use of ControlPreset is preferred over doing a custom IJoystick extension.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[146.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[268.0]},"content":[{"type":"paragraph","content":[{"text":"VxSim::IDevice","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[165.0]},"content":[{"type":"paragraph","content":[{"text":"VxApplication","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1221.0]},"content":[{"type":"paragraph","content":[{"text":"Defines a device that can be used in a Control Preset.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[146.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[268.0]},"content":[{"type":"paragraph","content":[{"text":"VxSim::IKeyboard","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[165.0]},"content":[{"type":"paragraph","content":[{"text":"Graphics Module","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1221.0]},"content":[{"type":"paragraph","content":[{"text":"Receive the raw key event.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[146.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[268.0]},"content":[{"type":"paragraph","content":[{"text":"VxSim::IMouse","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[165.0]},"content":[{"type":"paragraph","content":[{"text":"Graphics Module","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1221.0]},"content":[{"type":"paragraph","content":[{"text":"Receive the raw mouse event.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":2,"colwidth":[146.0]},"content":[{"type":"paragraph","content":[{"text":"Graphics","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[268.0]},"content":[{"type":"paragraph","content":[{"text":"VxGraphics::IGraphic","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[165.0]},"content":[{"type":"paragraph","content":[{"text":"Graphics Module","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1221.0]},"content":[{"type":"paragraph","content":[{"text":"IGraphic is a generic interface to implement a custom graphic feature.","type":"text"}]},{"type":"paragraph","content":[{"text":"IGraphic is a ILocalExtension, IMechanismAddOn, ISceneAddOn and a IRoleFeature","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[268.0]},"content":[{"type":"paragraph","content":[{"text":"VxGraphics::IAccessory","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[165.0]},"content":[{"type":"paragraph","content":[{"text":"Graphics Module","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1221.0]},"content":[{"type":"paragraph","content":[{"text":"This interface provides display functionality meant for User Interfaces. IAccessory are not meant to be visible during the simulation, but are useful while editing and building the simulation objects.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[146.0]},"content":[{"type":"paragraph","content":[{"text":"Metrics","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[268.0]},"content":[{"type":"paragraph","content":[{"text":"VxSim::IMetricsCollector","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[165.0]},"content":[{"type":"paragraph","content":[{"text":"Metrics Module","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1221.0]},"content":[{"type":"paragraph","content":[{"text":"For any extension that wishes to collect metric data, metric module will send collected metric every frame.","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Behaviour Modifiers","type":"text"}]},{"type":"table","attrs":{"layout":"full-width","width":1800.0,"localId":"8f053484-74ba-43c4-8099-8dffb937e9bb"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[110.0]},"content":[{"type":"paragraph","content":[{"text":"Functionality","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"Interface Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[1534.0]},"content":[{"type":"paragraph","content":[{"text":"Notes","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[110.0]},"content":[{"type":"paragraph","content":[{"text":"Network","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"VxSim::ILocalExtension","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1534.0]},"content":[{"type":"paragraph","content":[{"text":"In a network simulation, the outputs of an extension that implements ILocalExtension will not be transferred to other computers. The data will be transferred locally with connections, but not through the network. If an extension is managed on several computers in the network, this interface will prevent issues with the network.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[110.0]},"content":[{"type":"paragraph","content":[{"text":"Role & Seat","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"VxSim::IRoleFeature","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1534.0]},"content":[{"type":"paragraph","content":[{"text":"Only the extensions that implement IRoleFeature can be added to a role.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":4,"colwidth":[110.0]},"content":[{"type":"paragraph","content":[{"text":"Content Management","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"VxDynamics::IAssemblyAddOn","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1534.0]},"content":[{"type":"paragraph","content":[{"text":"Indicates that the extension or object can be added to an Assembly. Assembly will not accept the extension otherwise, contrary to a Mechanism of a scene.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"VxDynamics::IMechanismAddOn","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1534.0]},"content":[{"type":"paragraph","content":[{"text":"By default, Scene and Mechanism only accept IExtension, but not IObject. An extension that is an IObject can be added to a Mechanism when it implements IMechanismAddOn.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"VxContent::ISceneAddOn","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1534.0]},"content":[{"type":"paragraph","content":[{"text":"ISceneAddOn has the same effect on Scene, as IMechanismAddOn for Mechanism.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"VxContent::ISetupAddOn","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1534.0]},"content":[{"type":"paragraph","content":[{"text":"ISetupAddOn is an interface that allows an IExtension to be added to any VxContent::Setup","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"ISimulatorModule interface","type":"text"}]},{"type":"paragraph","content":[{"text":"An ISimulatorModule is a special kind of extension that can only be added to VxApplication (with VxApplication::insertModule) or to ApplicationConfig.","type":"text"},{"type":"hardBreak"},{"text":"When implemented, it will be contained in a VxSim::VxSimulatorModule that is returned with getProxy().","type":"text"}]},{"type":"paragraph","content":[{"text":"A module will manage its extensions and execute at each update either code based on their data or callbacks on their implementation.","type":"text"},{"type":"hardBreak"},{"text":"If you develop an extension already based on a predefined interface, e.g. IDynamics, a module will be already available and you won't need to develop your own.","type":"text"},{"type":"hardBreak"},{"text":"If you develop an extension based on a new interface, e.g. your own device, you will need to also code a module to manage the extensions of that type.","type":"text"}]},{"type":"paragraph","content":[{"text":"ISimulatorModule","type":"text","marks":[{"type":"link","attrs":{"href":"http://dionysos/Vortex%20Documentation%206.8/Vortex_Technical_Documentation/class_vx_sim_1_1_i_simulator_module.html"}}]},{"text":" has two constructors, that are similar to the constructor of ","type":"text"},{"text":"IExtension","type":"text","marks":[{"type":"link","attrs":{"href":"http://dionysos/Vortex%20Documentation%206.8/Vortex_Technical_Documentation/class_vx_sim_1_1_i_extension.html"}}]},{"text":".","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"ISimulatorModule::ISimulatorModule(VxSim::VxSimulatorModule* proxy, int version = 0); \nISimulatorModule::ISimulatorModule(VxSim::VxSimulatorModule *proxy, int preUpdatePriority, int updatePriority, int postUpdatePriority, int version = 0);","type":"text"}]},{"type":"paragraph","content":[{"text":"The proxy will be provided by the VxExtensionFactory but the version needs to be provided by the actual implementation. Versioning will be used when loading and saving the module.","type":"text"},{"type":"hardBreak"},{"text":"The priorities can also be given to the constructor; they control the order in which the VxApplication calls onPreUdpate(), onUpdate() and onPostUpdate() on all its modules.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The default priorities of updating in ISimulatorModule are correct in the vast majority of cases.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The constructor of a module usually has this basic form:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"const int kCurrentVersion = 20210315; \n\nclass MyModule: public VxSim::ISimulatorModule \n{ \n public: MyObject (VxSim::VxSimulatorModule * proxy) \n : VxSim::ISimulatorModule(proxy, kCurrentVersion) \n { \n } \n};","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Extension Management Support","type":"text"}]},{"type":"paragraph","content":[{"text":"The VxApplication notifies all ISimulatorModule of all extensions that are added to it through the ","type":"text"},{"text":"VxSim::ISimulatorModule::onExtensionAdded()","type":"text","marks":[{"type":"strong"}]},{"text":" method. It is there that each ISimulatorModule decides if it will manage the new extension or not.","type":"text"}]},{"type":"paragraph","content":[{"text":"Typically a module validates if it will accept the extension. To that end, the template class ","type":"text"},{"text":"VxSim::VxSmartInterface","type":"text","marks":[{"type":"strong"}]},{"text":" can be used to easily get a specific interface from an extension while ensuring that the object stays alive for as long as needed. When a module accepts an extension, the module must call ","type":"text"},{"text":"VxSim::ISimulatorModule::_addManagedExtension()","type":"text","marks":[{"type":"strong"}]},{"text":". When an extension is added to a module, the extension's callback ","type":"text"},{"text":"VxSim::IExtension:::OnActive()","type":"text","marks":[{"type":"strong"}]},{"text":" will be called.","type":"text"}]},{"type":"paragraph","content":[{"text":"Likewise, when an extension is removed from the application, it will call the ","type":"text"},{"text":"VxSim::ISimulatorModule::onExtensionRemoved()","type":"text","marks":[{"type":"strong"}]},{"text":" method. If the module accepted the extension when it was added, it must call ","type":"text"},{"text":"VxSim::ISimulatorModule::_removeManagedExtension()","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"},{"type":"hardBreak"},{"text":"When an extension is removed from a module, the extension's callback","type":"text"},{"text":" VxSim::IExtension:::OnInactive()","type":"text","marks":[{"type":"strong"}]},{"text":" will be called.","type":"text"}]},{"type":"panel","attrs":{"panelType":"error"},"content":[{"type":"paragraph","content":[{"text":"When ISimulatorModule receives an extension that it will manage, it is mandatory to notify the application by calling _addManagedExtension(). Otherwise, the extension may not work as expected.","type":"text"},{"type":"hardBreak"},{"text":"Likewise, if a managed extension is received in onExtensionRemoved(), the method _removeManagedExtension() must be called.","type":"text"}]},{"type":"paragraph","content":[{"text":"If _addManagedExtension() and _onRemovedExtension() are not called, the observers on the extension will not work.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Each method will be called the same number of times. It is not impossible that an extension will be added, then removed during loading, as some features can remove or disable extensions from the content loaded.","type":"text"}]},{"type":"paragraph","content":[{"text":"A module can get the list of its managed extensions by calling ","type":"text"},{"text":"VxSim::ISimulatorModule::_getManagedExtensions()","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example","type":"text"}]},{"type":"paragraph","content":[{"text":"The module MyModule needs to manage all MyExtension instances that are put in the content.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example of a module managing a type of extension","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"const int kCurrentVersion = 20210315; \n\nclass MyModule : public VxSim::ISimulatorModule \n{ \n void _prepareExtension(VxSim::VxSmartInterface my); \n void _cleanupExtension(VxSim::VxSmartInterface my); \n\npublic: \n MyModule(VxSim::VxSimulatorModule* proxy) \n : VxSim::ISimulatorModule(proxy, kCurrentVersion ) \n { \n }\n \n virtual void onExtensionAdded(VxSim::VxExtension* extension) \n { \n VxSim::VxSmartInterface my = extension; \n\n if (my.valid()) \n { \n _addManagedExtension(extension); \n _prepareExtension(my); \n } \n } \n\n virtual void onExtensionRemoved(VxSim::VxExtension* extension) \n { \n VxSim::VxSmartInterface my = extension; \n if (my.valid()) \n { \n _cleanupExtension(my); \n _removeManagedExtension(extension); \n } \n }\n\n\tvoid onPostUpdate(VxSim::eApplicationMode mode)\n\t{\n \tif ( mode == VxSim::kModeSimulating)\n \t{\n\t\t\t...\n\n \tconst auto& extensions = getProxy()->getManagedExtensions();\n \tfor (auto it = extensions.begin(); it != extensions.end(); ++it)\n \t{\n \t// get the MyExtension interface (should be valid since the module put it in the list)\n \tVxSim::VxSmartInterface myExt = *it;\n \tmyExt->updatePosition();\n \t}\n \t}\n\t} \n};\n\n","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Simulation Management Support","type":"text"}]},{"type":"paragraph","content":[{"text":"Several methods can be overridden to implement an ISimulatorModule-specific functionality.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Initialization and cleanup","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"virtual void VxSim::ISimulatorModule::onAddToApplication(VxApplication* application); \nvirtual void VxSim::ISimulatorModule::onRemoveFromApplication(VxApplication* application);","type":"text"}]},{"type":"paragraph","content":[{"text":"onAddToApplication() is called just after the ISimulatorModule is added to the VxApplication.","type":"text"}]},{"type":"paragraph","content":[{"text":"This is the right moment to perform any initialization required by the module: starting a thread, connecting to a network socket, loading some internal data, etc. This is usually done very early in the application start-up, but will not be done when building an ApplicationConfig. Any initialization that was done must be undone in onRemoveFromApplication.","type":"text"}]},{"type":"panel","attrs":{"panelType":"error"},"content":[{"type":"paragraph","content":[{"text":"The constructor of the derived ISimulatorModule is not a good place to do any resource initialization, as there may be more than one instance of the same class being created at the same time. Initialization should be done in onAddToApplication.","type":"text"}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Updates","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"virtual void VxSim::ISimulatorModule::onPreUpdate(VxSim::eApplicationMode mode); \nvirtual void VxSim::ISimulatorModule::onUpdate(VxSim::eApplicationMode mode); \nvirtual void VxSim::ISimulatorModule::onPostUpdate(VxSim::eApplicationMode mode); \nvoid VxSim::ISimulatorModule::_sortManagedExtensions();","type":"text"}]},{"type":"paragraph","content":[{"text":"Those methods are the heartbeat of the simulation. They are called in the VxApplication::update() loop. This is where you want to do the work that the module is designed to do. onPreUdpate is called before the dynamics, onPostUpdate is called after the dynamics but before the graphics. onUpdate is called in between the two. Generally, onUpdate is not used. All those methods receive the current application mode of the VxApplication.","type":"text"}]},{"type":"paragraph","content":[{"text":"_sortManagedExtensions() will make sure that the managed extensions are sorted according to their dependency as given by the connection layout.","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"When the module is managing several extensions that are likely to be interconnected, it is necessary to call _sortManagedExtensions() to process the extension in the right order. The dependencies between extension are exclusively deduced from the connections between extensions, i.e., if extension A's output is connected to extension B's input, extension A will be before extension B when it is sorted.","type":"text"}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example of a module update its extensions in the right sequence","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"class MyExtension : public VxSim::IExtension \n{ \n [...] \n\n void doOneStep(); \n}; \n\nclass MyModule : public VxSim::ISimulatorModule \n{ \n [...] \n\n virtual void onPreUpdate(VxSim::eApplicationMode mode) \n { \n if ( mode == VxSim::kModeSimulating ) \n { \n // make sure that the extension are sorted according to the connection graph layout \n // if already sorted, no time is spent here _sortManagedExtensions(); \n auto& extensions = getProxy()->getManagedExtensions(); \n for (auto it = extensions.begin(); it != extensions.end(); ++it) \n { \n VxSim::VxSmartInterface my = *it; \n my->doOneStep(); \n } \n } \n } \n};","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Application Mode","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":" virtual void VxSim::ISimulatorModule::onApplicationModeChange(VxSim::eApplicationMode previous, VxSim::eApplicationMode current);","type":"text"}]},{"type":"paragraph","content":[{"text":"onApplicationModeChange is called whenever the mode of the VxApplication is changing. It will be called right before the mode actually changes.","type":"text"},{"type":"hardBreak"},{"text":"Use this callback to do any special processing necessary when transitioning from one mode to another.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Good Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"This method is useful when some special initialization is necessary when going in simulation.","type":"text"},{"type":"hardBreak"},{"text":"It is the responsibility of the module to notify the extension of a mode change if the extension requires the information. The extension can only know the current mode from the context.","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Helper Functions","type":"text"}]},{"type":"paragraph","content":[{"text":"ISimulatorModule has a few helper functions:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"getProxy() gives access to the main Vortex Toolkit object that carries the data and implementation of the ISimulatorModule.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"getApplication() gives access to the VxApplication that contains the module.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Deploying Your Plugin","type":"text"}]},{"type":"paragraph","content":[{"text":"Your vxp file can reside anywhere on your file system. Typically, Vortex searches for vxp in its ","type":"text"},{"text":"plugins","type":"text","marks":[{"type":"em"}]},{"text":" folder and dll in its ","type":"text"},{"text":"bin","type":"text","marks":[{"type":"em"}]},{"text":" folder. ","type":"text"},{"type":"hardBreak"},{"text":"In order to add search locations, the Vortex Editor options, and your application setup file (including the player for example), must be edited to find and load your plugin.","type":"text"},{"type":"hardBreak"},{"text":"You can put your library files alongside your plugin file, Vortex will find them.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Vortex Studio Editor","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Launch the Vortex Studio Editor.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Go to Options.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Go to the setup section.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add your Plugin paths using the widget.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Save, you will be prompted to restart the editor.","type":"text"}]}]},{"type":"listItem","content":[{"type":"mediaSingle","attrs":{"layout":"align-start"},"content":[{"type":"media","attrs":{"width":960,"id":"6e60989e-47b8-44a5-a999-73bdde50ced9","collection":"contentId-3448056837","type":"file","height":917}}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Note the editor.vxc does not need to be modified.","type":"text"}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Simulator Application","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Launch the Vortex Studio Editor.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Open your setup file.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In the Explorer, select the root of your setup file.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In the Property view, expand the PluginDirectories field.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use the widget to increase the size.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Click on the ... button and select your folder.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Save your setup file.","type":"text"}]}]},{"type":"listItem","content":[{"type":"mediaSingle","attrs":{"layout":"align-start","width":75.0},"content":[{"type":"media","attrs":{"width":1280,"id":"c372b41c-7daf-4f00-997f-a3eae0374c9c","collection":"contentId-3448056837","type":"file","height":526}}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Extension Data","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Inputs, Outputs and Parameters","type":"text"}]},{"type":"paragraph","content":[{"text":"The extension data is stored in VxData::Field of the appropriate type. The use of fields gives us a high level of standardization, which simplifies Vortex Toolkit and improves overall performance. ","type":"text"}]},{"type":"paragraph","content":[{"text":"There are three major field containers in every extension: inputs, outputs and parameters.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Inputs: data that is fed to the extension. It can change anytime in the simulation.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Outputs: data produced by the extension. Outputs of one extension can be connected to inputs of another extension.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Parameters: constant data in the simulation. It can be changed while editing the object, but not during the simulation.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"All inputs, outputs and parameters in an extension are automatically serialized. They are written to file when saving, and put back in the extension when loaded.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Good Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"The decision to put a value as a parameter or an input has profound impact on the use of the extension.","type":"text"},{"type":"hardBreak"},{"text":"An input can be changed anytime during simulation and editing; the extension must be ready to react to a change at any time.","type":"text"},{"type":"hardBreak"},{"text":"A parameter should only change in while editing. Changing a parameter can trigger extensive recalculations that may not be suitable while simulating.","type":"text"}]},{"type":"paragraph","content":[{"text":"Because a module is not part of the content, it should only have parameters and there is not dataflow mechanism to transmit outputs to inputs.","type":"text"},{"type":"hardBreak"},{"text":"An extension should not modify its own inputs or parameters. Inputs and parameters are the API from which the extension is controlled.","type":"text"},{"type":"hardBreak"},{"text":"When the extension needs to deliver some results, it should have an output.","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Declaring data","type":"text"}]},{"type":"paragraph","content":[{"text":"The header file for an extension with three fields (one input, one output, and one parameter) would look like the following:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"class MyExtension : public VxSim::IExtension, public VxSim::IDynamics \n{ \n public: \n MyExtension(VxSim::VxExtension* proxy); \n\n // declaration of the fields \n VxData::Field inputEnable; \n VxData::Field outputScaleFactor; \n VxData::Field parameterTargetPart; \n};","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Good Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"The fields are part of the API of your extension.","type":"text"},{"type":"hardBreak"},{"text":"The fields are inherently public since they can always be accessed from the VxExtension. It is usually simpler to make them public, instead of creating getters/setters.","type":"text"},{"type":"hardBreak"},{"text":"Set the physical dimensions of the values and a description of the field. When it is done, the units will be displayed in the Editor and the description as a tooltip on the field.","type":"text"}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"The constructor must declare the name for the fields, whether they are inputs, outputs or parameters and optionally a default value.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"MyExtension::MyExtension(VxSim::VxExtension* proxy) \n : VxSim::IDynamics(proxy) \n , VxSim::IExtension(proxy, kCurrentVersion) \n , inputEnable(false, \"Enable\", &proxy->getInputContainer()) \n , outputScaleFactor(Math::Vector3(1,1,1), \"Scale\", &proxy->getOutputContainer()) \n , parameterTargetPart(nullptr, \"Target\", &proxy->getParameterContainer()) \n{ \n outputScaleFactor.setPhysicalDimension(Vx::VxPhysicalDimension::kScale);\n outputScaleFactor.setDescription(\"The scaling factor that was applied to the target part.\");\n}","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Field","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Field Types","type":"text"}]},{"type":"paragraph","content":[{"text":"Field represents a data value that has a type (from the template parameter), a name (from the constructor), and a value.","type":"text"}]},{"type":"table","attrs":{"layout":"wide","width":1800.0,"localId":"20ae32dd-27ce-423e-873d-341d51651fad"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":6,"colwidth":[212.0]},"content":[{"type":"paragraph","content":[{"text":"Numerical","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"same as VxData::Field","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":7,"colwidth":[212.0]},"content":[{"type":"paragraph","content":[{"text":"Compound Values","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"same as VxData::Field","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"same as VxData::Field","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":2,"colwidth":[212.0]},"content":[{"type":"paragraph","content":[{"text":"String","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains the path to a file or directory.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":13,"colwidth":[212.0]},"content":[{"type":"paragraph","content":[{"text":"Object","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to a VxSim::VxExtension","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to a Vx::VxMaterial","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to a VxDynamics::Part","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to a VxDynamics::Assembly","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to a VxDynamics::Attachment","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to a VxDynamics::AttachmentPoint","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to a VxDynamics::CollisionGeometry","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to a VxDynamics::Mechanism","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to a VxGraphics::Node","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to a VxGraphics::Mesh","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to a VxGraphics::Material","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to a VxGraphics::Texture","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field<","type":"text"},{"text":"Interface Type","type":"text","marks":[{"type":"em"}]},{"text":">","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Contains a reference to an Interface Type","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":2,"colwidth":[212.0]},"content":[{"type":"paragraph","content":[{"text":"Other","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Generic Enumeration","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[210.0]},"content":[{"type":"paragraph","content":[{"text":"VxData::Field<","type":"text"},{"text":"enum type","type":"text","marks":[{"type":"em"}]},{"text":">","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[538.0]},"content":[{"type":"paragraph","content":[{"text":"Specific Enumeration","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"All fields of pointer types have an additional feature. If the object pointed to by the Field is deleted, the value in the field will automatically become nullptr in order to avoid dangling pointers.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Using Field in an extension","type":"text"}]},{"type":"paragraph","content":[{"text":"Using Field is as simple as using a variable of type T.","type":"text"}]},{"type":"paragraph","content":[{"text":"To avoid any ambiguity, Field also has the method getValue() and setValue().","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"class MyExtension : public VxSim::IExtension, public VxSim::IDynamics \n{ \n public: \n MyExtension(VxSim::VxExtension* proxy); \n\n // declaration of the fields \n VxData::Field inputScale; \n VxData::Field outputScaleFactor; \n VxData::Field parameterTargetPart; \n\n [...] \n\n private: \n void _handleScale(double s); \n inline void _processInput() \n { \n // Field is used just like a double \n if ( inputScale > 0 ) \n { \n _handleScale( inputScale ); \n } \n else if ( inputScale > 0 ) \n { \n _handleScale( -inputScale.getValue() ); \n } \n } \n\n inline void _processOutput \n { \n // Fields with compound values like VxData::Field are used in the same way \n Math::Vector3 v(inputScale, inputScale, inputScale); \n outputScaleFactor = v; \n } \n\n inline void _processParameter() \n { \n // VxData::Field can be used like a VxDynamics::Part*\n VxDynamics::Part* p = parameterTargetPart; \n if ( parameterTargetPart != nullptr ) \n { \n parameterTargetPart->resetInertia(); \n } \n } \n};","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Additional information","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"Vortex Studio SDK Advanced - Fields And Extensions","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD2401/pages/3448047461"}}]},{"text":" for more information about using fields, and IExtension callbacks.","type":"text"},{"type":"hardBreak"},{"text":"See code tutorials ","type":"text"},{"text":"C++ Tutorial 1: Plugins","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD2401/pages/3448061705"}}]},{"text":" and ","type":"text"},{"text":"Devices","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD2401/pages/3448062061"}}]},{"text":" for extensions and module implementation examples. The code tutorial are located in /tutorial","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Vx::VxSmartPtr and VxSim::VxSmartInterface","type":"text"}]},{"type":"paragraph","content":[{"text":"Vortex objects are reference-counted via a special smart pointer class, ","type":"text"},{"text":"VxSmartPtr","type":"text","marks":[{"type":"em"}]},{"text":". When you need to keep an ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"em"}]},{"text":" alive, you should keep it in a ","type":"text"},{"text":"VxSmartPtr","type":"text","marks":[{"type":"em"}]},{"text":". Vortex internal's system uses those smart pointer to keep extensions alive.","type":"text"},{"type":"hardBreak"},{"text":"In some rare case, a developer might want to keep a pointer on a VxExtension without increasing the reference count. In this case, a VxWeakPtr should be used. A weak pointer will become invalid when the reference extension is destroyed.","type":"text"}]},{"type":"paragraph","content":[{"text":"Unless a developer needs to do generic things on extensions, using ","type":"text"},{"text":"VxSmartInterface ","type":"text","marks":[{"type":"em"}]},{"text":"should be favored. A ","type":"text"},{"text":"VxSmartInterface ","type":"text","marks":[{"type":"em"}]},{"text":"is both a VxSmartPtr to the extension and a pointer to the implementation.","type":"text"},{"type":"hardBreak"},{"text":"When a developer needs to query, test or use a specific interface, the safest, simplest way is to use a ","type":"text"},{"text":"VxSmartInterface object","type":"text","marks":[{"type":"em"}]},{"text":". A ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"em"}]},{"text":" can contain any kind of implementation: extension or module. ","type":"text"},{"text":"VxSmartInterface","type":"text","marks":[{"type":"em"}]},{"text":" can be used to query for a specific type of interface, if the interface is found, the extension will be referenced (thus will never be deleted) as long as the ","type":"text"},{"text":"VxSmartInterface ","type":"text","marks":[{"type":"em"}]},{"text":"has it. ","type":"text"},{"text":"VxSmartInterface","type":"text","marks":[{"type":"em"}]},{"text":" can be initialized with a ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"em"}]},{"text":"*, a ","type":"text"},{"text":"VxSmartPtr","type":"text","marks":[{"type":"em"}]},{"text":", or with any kind of ","type":"text"},{"text":"VxSmartInterace","type":"text","marks":[{"type":"em"}]},{"text":". ","type":"text"},{"text":"VxSmartInterface ","type":"text","marks":[{"type":"em"}]},{"text":"also contains its VxExtension via function ","type":"text"},{"text":"getExtension()","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example of using VxSmartInterface to find specific interfaces","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"void doSomethingWithAIMobile(VxSim::VxExtension* extension)\n{\n\tVxSim::VxSmartInterface imobile = extension;\n\tif ( imobile.valid() ) // check if the IMobile interface was found in the extension\n\t{\n\t\t// by using a VxSmartInterface, we are garanteed that extension will not be deleted during the call to _getTheNewPosition()\n\t\timobile->inputLocalTransform = _getTheNewPosition();\n \n\t\t// check if there is also the IGraphic interface (in addition to IMobile)\n\t\tVxSim::VxSmartInterface graphicAndMobile = imobile;\n\t\tif ( graphicAndMobile.valid() )\n\t\t{\n\t\t\t_doSomethingSpecial(graphicAndMobile);\n\t\t}\n\t}\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"VxWeakInterface ","type":"text","marks":[{"type":"em"}]},{"text":"is very similar but it does NOT increase the ref-count of the ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"em"}]},{"text":". There are very few cases where ","type":"text"},{"text":"VxWeakInterface","type":"text","marks":[{"type":"em"}]},{"text":"should be used instead of a ","type":"text"},{"text":"VxSmartInterface","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"},{"type":"hardBreak"},{"text":"The most important exception is when a class needs a member and does NOT want to keep it alive. Basically, you would only use ","type":"text"},{"text":"VxWeakInterface","type":"text","marks":[{"type":"em"}]},{"text":", if you would use a ","type":"text"},{"text":"VxWeakPtr","type":"text","marks":[{"type":"em"}]},{"text":". ","type":"text"}]}],"version":1}

Browser not supported