1 /**********************************************************************
2 Engine - Engine interface and plugin factory.
4 Copyright (C) 2007 Donald Ephraim Curtis
6 This file is part of the Avogadro molecular editor project.
7 For more information, see <http://avogadro.sourceforge.net/>
9 Avogadro is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 2 of the License, or
12 (at your option) any later version.
14 Avogadro is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
23 **********************************************************************/
28 #include <avogadro/global.h>
29 #include <avogadro/primitivelist.h>
30 #include "painterdevice.h"
35 #define AVOGADRO_ENGINE(t) \
37 static QString staticType() { return t; } \
38 QString type() const { return staticType(); } \
41 #define AVOGADRO_ENGINE_FACTORY(n) \
43 Engine *createInstance(QObject *parent = 0) { return new n(parent); } \
45 QString className() { return n::staticMetaObject.className(); } \
46 QString type() { return n::staticType(); } \
54 * @class Engine engine.h <avogadro/engine.h>
55 * @brief Engine plugin interface.
56 * @author Donald Ephraim Curtis
57 * @author Marcus D. Hanwell
59 * This class provides an interface for our engines.
60 * Subclasses of this class are loaded by the GLWidget and used to render
61 * different parts of our project (Molecule, Atom, Bond, Residue) depending
62 * on what style of engine we are implementing.
63 * \sa GLWidget::render()
66 class A_EXPORT Engine
: public QObject
73 * Different properties an engine can set which affect the rendering order.
76 NoFlags
= 0x00, /// no flags
77 Transparent
= 0x01, /// renders transparency
78 Overlay
= 0x02, /// renders overlay
79 Bonds
= 0x04, /// renders bonds
80 Atoms
= 0x08, /// renders atoms
81 Molecules
= 0x10 /// renders molecules
83 Q_DECLARE_FLAGS(EngineFlags
, EngineFlag
)
89 Engine(QObject
*parent
= 0);
96 * @return the name of the engine.
101 * @param name the new name for the engine instance.
103 void setName(const QString
&name
);
106 * @return engine description.
108 QString
description() const;
111 * @param description the new description of this engine.
113 void setDescription(const QString
&description
);
116 * @return the flags for this engine.
118 virtual EngineFlags
flags() const;
121 * @return a string with the type of the engine.
123 virtual QString
type() const = 0;
126 * Render opaque elements. This function is allowed to render
127 * whatever opaque primitives it wishes. There is no requirement that it
128 * render every primitive.
130 * During generation of the GL view engines will have their render
131 * functions called at most once. It is the responsibility
132 * of the engine to render all of the objects in it's queue if
135 * @return @c true if the rendering was completed successfully, @c false otherwise
139 * Color *map = colorMap(); // possible custom color map
140 * if (!map) map = pd->colorMap(); // fall back to global color map
142 * // Get a list of bonds and render them
143 * QList<Primitive *> list;
144 * list = primitives().subList(Primitive::BondType);
146 * foreach(Primitive *p, list)
147 * render(static_cast<const Bond *>(p))
152 * @note To allow picking to happen you need to push the object type and name.
153 * If objects cannot be picked this may be omitted.
155 * For more information on the various primitive lists available see
159 virtual bool renderOpaque(PainterDevice
*pd
) = 0;
161 * Render transparent elements. This function is allowed to render
162 * whatever transparent primitives it wishes. There is no requirement that it
163 * render every primitive.
165 * During generation of the GL view engines will have their render
166 * functions called at most once. It is the responsibility
167 * of the engine to render all of the objects in it's queue if
170 * @return @c true if the rendering was completed successfully, @c false otherwise
174 * Color *map = colorMap(); // possible custom color map
175 * if (!map) map = pd->colorMap(); // fall back to global color map
177 * // Get a list of atoms and render the selected ones as transparent spheres
178 * QList<Primitive *> list;
179 * list = primitives().subList(Primitive::AtomType);
181 * foreach(Primitive *p, list) {
182 * const Atom *a = static_cast<const Atom *>(p);
184 * // Render the selection highlight
185 * if (pd->isSelected(a)) {
186 * map->set(0.3, 0.6, 1.0, 0.7);
187 * glEnable(GL_BLEND);
188 * pd->painter()->setColor(map);
189 * pd->painter()->setName(a);
190 * pd->painter()->drawSphere(a->pos(), 0.1 + radius( a ));
191 * glDisable(GL_BLEND);
196 * @note To allow picking to happen you need to push the object type and name.
197 * If objects cannot be picked this may be omitted.
199 * For more information on the various primitive lists available see
203 virtual bool renderTransparent(PainterDevice
*) { return true; }
206 * Render all elements the engine is responsible for quickly with an
207 * emphasis on maintaining interactivity even with very large molecules.
208 * By default this function calls renderOpaque but in most cases should
209 * be implemented and tuned using large molecule test cases. The GLWidget
210 * ensures dynamic scaling of geometric primitives is off before calling
211 * this rendering function.
213 virtual bool renderQuick(PainterDevice
*pd
)
220 * @return the engine's PrimitiveList containing all primitives the engine
223 PrimitiveList
primitives() const;
226 * Set the primitives that the engine instance can render.
227 * @param primitives the PrimitiveList the engine can render from.
229 virtual void setPrimitives(const PrimitiveList
&primitives
);
232 * Clear the primitives of the engine instance.
234 virtual void clearPrimitives();
236 /** Get the radius of the primitive referred to.
237 * @param primitive is the Primitive to get the radius of.
238 * @return the radius of the Primitive.
240 virtual double radius(const PainterDevice
*pd
, const Primitive
*primitive
= 0) const;
243 * @return transparency level, rendered low to high.
245 virtual double transparencyDepth() const;
248 * @return true if the engine is enabled or false if it is not.
250 bool isEnabled() const;
253 * Setter to enable or disable the engine instance.
254 * @param enabled true to enable the egine, false to disable the engine.
256 void setEnabled(bool enabled
);
259 * @return a QWidget containing the engine settings or 0
260 * if no settings widget is available.
262 virtual QWidget
*settingsWidget();
265 * @return a pointer to an identical engine or 0 if this fails
267 virtual Engine
*clone() const = 0;
270 * Write the engine settings so that they can be saved between sessions.
272 virtual void writeSettings(QSettings
&settings
) const;
275 * Read in the settings that have been saved for the engine instance.
277 virtual void readSettings(QSettings
&settings
);
281 * Signals that something has been changed and the engine needs to render
282 * after these changes were made.
288 * Add the primitive to the engines PrimitiveList.
289 * @param primitive to be added to the PrimitiveList.
291 virtual void addPrimitive(Primitive
*primitive
);
294 * Update the primitive in the engines PrimitiveList.
295 * @param primitive to be updated in the PrimitiveList.
297 virtual void updatePrimitive(Primitive
*primitive
);
300 * Remove the primitive to from the engines PrimitiveList.
301 * @param primitive to be removed from the PrimitiveList.
303 virtual void removePrimitive(Primitive
*primitive
);
305 /** Set the color map to be used for this engine.
306 * The default is to color each atom by element.
307 * @param map is the new colors to be used
309 virtual void setColorMap(Color
*map
);
311 /** @return the current color map used by this engine
313 virtual Color
*colorMap();
316 EnginePrivate
*const d
;
320 * @class EngineFactory engine.h <avogadro/engine.h>
321 * @brief Generates new instances of the Engine class for which it is defined.
322 * @warning This function needs to be looked at again. It was originally designed
323 * so that for a single thread we could have multiple rendering engines. We have
324 * decided that each molecule will have it's own window which will be it's own thread.
325 * However, this style of plugin creation may still be needed as we might want to have
326 * multiple views of the same molecule.
328 * This class is used to generate new instances of the Engine class for which
331 class A_EXPORT EngineFactory
337 virtual ~EngineFactory() {}
340 * @return pointer to a new instance of an Engine subclass object.
342 virtual Engine
*createInstance(QObject
*parent
=0) = 0;
345 * @return the name of the class.
347 virtual QString
className() = 0;
350 * @return the type of the engine instance.
352 virtual QString
type() = 0;
357 } // end namespace Avogadro
359 Q_DECLARE_METATYPE(Avogadro::Engine
*)
360 Q_DECLARE_INTERFACE(Avogadro::EngineFactory
, "net.sourceforge.avogadro.enginefactory/1.0")
361 Q_DECLARE_OPERATORS_FOR_FLAGS(Avogadro::Engine::EngineFlags
)