pluginProgramming.docu 7.2 KB
Newer Older
Mike Kremer's avatar
Mike Kremer committed
1 2
/*! \page pluginProgramming Plugin Programming
 *
Jan Möbius's avatar
Jan Möbius committed
3
 * 
Mike Kremer's avatar
Mike Kremer committed
4 5 6 7 8 9
 * \section quickref Quick references:
 * - \ref plugin_sec
 * - \ref plugin_prog_sec
 * - \ref geometryData
 * \section tuts Tutorials
 * - \ref ex1
10
 * - \ref ex1c
Mike Kremer's avatar
Mike Kremer committed
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102
 * - \ref ex1b
 * - \ref ex2
 * - \ref ex3
 * - \ref ex4
 *
 * \section plugin_sec Plugin Basics
 * 
 * As mentioned above Openflipper is a plugin based system. It uses the qt plugin implementation to
 * load and unload plugins at runtime. Every algorithm should be added as one of these plugins. 
 * 
 * The plugins have to be created as .so (or under windows : .dll) files which should be symlinked or 
 * copied to the Plugin subfolder. OpenFlipper distinguishes between 32/64-bit plugin versions and
 * max or dbg (release/debug) versions. So the compiled plugins have to reside in the right subdir of
 * Plugins. The Plugins are loaded on startup of the application (they may also be loaded at runtime 
 * later). 
 * 
 * \section plugin_prog_sec Plugin programming
 * The interface between the core and the plugins is managed via simple interfaces based on the signal/slot
 * metaphor of qt. Your plugins have to be derived from these interfaces. You dont have to implement
 * all functions or signals of the interfaces you include. This has only to be done for the BaseInterface 
 * which must be implemented by every plugin. See the BaseInterface Documentation for details.
 * 
 * Unimplemented functions will be left unconnected from the core and wont have any impact on the applications
 * speed or stability. As stated above, every plugin has to be derived from the BaseInterface. This is the
 * basic factory which makes the core aware of the plugin. The name and the description of the plugin is 
 * exported via the baseinterface. The initialization of each plugin is done via this interface too.
 * See \ref dataFlow for an overview of OpenFlipper's data flow and interface function calls.
 * 
 * After this interface of the plugin is sucessfully processed all other interfaces will be initialized
 * and connected to the core. For details about the individual interfaces see their documentation. 
 * \ref interfaces
 *
 * \section geometryData Handling geometry data within a plugin
 *
 * \subsection addingAndRemovingGeometry Adding and removing mesh objects in OpenFlipper
 *
 * If you want to load geometry data from a file or simply add objects to the scene
 * from within a plugin, it has to implement the \ref LoadSavePlugin.
 *
 * LoadSaveInterface::load(	QString _file, DataType _type, int&	_id) tries to
 * load file with file name _file of type _type, _id contains the new created
 * object's id or -1 if loading failed. OpenFlipper will then create all
 * the necessary scene graph nodes such that the developer generally does
 * not need to know in detail how to create and add the required nodes to the scene.
 *
 * Otherwise if a file has been loaded externally, slot
 *
 * LoadSaveInterface::openedFile (int _id) is called.
 *
 * When removing objects from the scene, the plugin simply has to emit signal
 *
 * LoadSaveInterface::deleteObject(int _id)
 *
 * or
 *
 * LoadSaveInterface::deleteAllObjects() in order to clear the scene.
 *
 * \subsection pluginFunctions OpenFlipper's plugin functions
 *
 * As a plugin in most cases operates on geometry data, developers might want to know how to gain access to mesh data
 * from within a plugin. In our tutorial \ref ex2 we roughly mentioned that the communication between OpenFlipper
 * and it's plugins is accomplished through either one of the provided \ref interfaces or the \ref PluginFunctions.
 *
 * For example iterating over all objects that have been marked as source objects is done via
 * 
 * <code>
 * for ( PluginFunctions::ObjectIterator o_it(PluginFunctions::SOURCE_OBJECTS);<br />
 * o_it != PluginFunctions::objectsEnd(); ++o_it) { ... }
 * </code>
 *
 * Possible restrictions are \c ALL_OBJECTS (to iterate over all objects in the scene), \c TARGET_OBJECTS (objects
 * that were marked as target) and \c SOURCE_OBJECTS.
 *
 * Another way to get handles to scene objects is to use the functions \c PluginFunctions::getObject() or
 * PluginFunctions::getPickedObject(). These functions provide a pointer to either a \ref BaseObjectData
 * or \ref BaseObject object. As in \ref ex2 one can easily test the type of an object by calling
 *
 * \c o_it->dataType(DATA_TYPE)
 *
 * where \c o_it is an object iterator and \c DATA_TYPE is one of the data types specified in \ref OpenFlipper/common/Types.hh.
 * \c o_it->dataType(DATA_TRIANGLE_MESH) for example will return true if the object is a triangle mesh.
 *
 * The mesh data itself can be obtained by calling the appropriate handle plugin function. For example if we consider
 * a triangle mesh, we get a handle to the mesh itself by calling
 *
 * <code>TriMesh* mesh = PluginFunctions::triMesh(*o_it);</code>
 *
 * where \c o_it once again is our object iterator. See \ref PluginFunctions for a complete overview.
 *
 * \subsection updatingObjects Updating objects
 *
 * Once your plugin has manipulated object data we have to inform OpenFlipper's core about the changes.
103
 * When doing this, OpenFlipper distinguishes between five basic types of changes:
Mike Kremer's avatar
Mike Kremer committed
104
 *
105 106 107 108 109
 * - Object selections
 * - Visibility
 * - Geometry
 * - Topology
 * - Selections (Vertices, Edges, Faces)
Mike Kremer's avatar
Mike Kremer committed
110 111 112 113
 *
 * When changing geometry, OpenFlipper's core will be forced to redraw the object that has been
 * changed by emitting signal
 *
114
 * \ref BaseInterface::updatedObject(int _id, UpdateType _type)
Mike Kremer's avatar
Mike Kremer committed
115
 *
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
 * where \c _id is the object's id and _type is the type of changes that have been made.
 * Note: UpdateType offers the following values
 *
 * - UPDATE_ALL
 * - UPDATE_OBJECT_SELECTION
 * - UPDATE_VISIBILITY
 * - UPDATE_GEOMETRY
 * - UPDATE_TOPOLOGY
 * - UPDATE_SELECTION (ALL THREE KINDS)
 * - UPDATE_SELECTION_VERTICES
 * - UPDATE_SELECTION_EDGES
 * - UPDATE_SELECTION_FACES
 * - UPDATE_UNUSED
 *
 * If the second parameter of this signal is not specified, it will fall back
 * to the default value UPDATE_ALL for compatibility reasons which actually updates
 * each of the types. Unless it is really necessary this should generally be avoided
 * since it consumes a lot of computation time.
 *
135 136 137 138
 * Additionally, when overriding the slot BaseInterface::slotObjectUpdated(int, const UpdateType),
 * a plugin receives the updated object's id (first parameter) and the type
 * of changes (second parameter).
 *
139
 * See \ref BaseInterface for more information.
Mike Kremer's avatar
Mike Kremer committed
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161
 *
 * When changing object properties it won't be necessary to redraw the scene
 * since it can be expensive in computation power. In this case, one should emit
 *
 * \ref BaseInterface::objectPropertiesChanged(int _id)
 *
 * where \c _id once again is the object's id.
 *
 * If a plugin changed an object's visibility (hide, show), it should emit
 *
 * \ref BaseInterface::visibilityChanged(int _id)
 *
 * for the core to update the visibility state of object with identifier \c _id.
 *
 * Last, when changing an object's selection, it
 * will be updated by emitting
 *
 * \ref BaseInterface::objectSelectionChanged(int _id)
 *
 * where \c _id as in the examples above is the object's identifier.
 *
 * Also see \ref BaseInterface.
Jan Möbius's avatar
Jan Möbius committed
162 163 164 165 166
 *
 * \section Related pages
 *
 * \subpage pluginExamples Programming examples for OpenFlipper plugins
 * \subpage interfaces Plugin Interfaces
Mike Kremer's avatar
Mike Kremer committed
167
 */