kalzium/libavogadro-kalzium/src/engine.h

   1 /**********************************************************************
   2   Engine - Engine interface and plugin factory.
   3
   4   Copyright (C) 2007 Donald Ephraim Curtis
   5
   6   This file is part of the Avogadro molecular editor project.
   7   For more information, see <http://avogadro.sourceforge.net/>
   8
   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.
  13
  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.
  18
  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
  22   02110-1301, USA.
  23  **********************************************************************/
  24
  25 #ifndef __ENGINE_H
  26 #define __ENGINE_H
  27
  28 #include <avogadro/global.h>
  29 #include <avogadro/primitivelist.h>
  30 #include "painterdevice.h"
  31
  32 #include <QSettings>
  33 #include <QtPlugin>
  34
  35 #define AVOGADRO_ENGINE(t) \
  36   public: \
  37     static QString staticType() { return t; } \
  38     QString type() const { return staticType(); } \
  39   private:
  40
  41 #define AVOGADRO_ENGINE_FACTORY(n) \
  42     public: \
  43       Engine *createInstance(QObject *parent = 0) { return new n(parent); } \
  44  \
  45       QString className() { return n::staticMetaObject.className(); } \
  46       QString type() { return n::staticType(); } \
  47     private:
  48
  49 namespace Avogadro {
  50
  51   class PainterDevice;
  52
  53   /**
  54    * @class Engine engine.h <avogadro/engine.h>
  55    * @brief Engine plugin interface.
  56    * @author Donald Ephraim Curtis
  57    * @author Marcus D. Hanwell
  58    *
  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()
  64    */
  65   class EnginePrivate;
  66   class A_EXPORT Engine : public QObject
  67   {
  68     Q_OBJECT
  69
  70     public:
  71     /**
  72      * \enum EngineFlag
  73      * Different properties an engine can set which affect the rendering order.
  74      */
  75       enum EngineFlag {
  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
  82       };
  83       Q_DECLARE_FLAGS(EngineFlags, EngineFlag)
  84
  85     public:
  86       /**
  87        * Constructor
  88        */
  89       Engine(QObject *parent = 0);
  90       /**
  91        * Destructor
  92        */
  93       virtual ~Engine();
  94
  95       /**
  96        * @return the name of the engine.
  97        */
  98       QString name() const;
  99
 100       /**
 101        * @param name the new name for the engine instance.
 102        */
 103       void setName(const QString &name);
 104
 105       /**
 106        * @return engine description.
 107        */
 108       QString description() const;
 109
 110       /**
 111        * @param description the new description of this engine.
 112        */
 113       void setDescription(const QString &description);
 114
 115       /**
 116        * @return the flags for this engine.
 117        */
 118       virtual EngineFlags flags() const;
 119
 120       /**
 121        * @return a string with the type of the engine.
 122        */
 123       virtual QString type() const = 0;
 124
 125       /**
 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.
 129        *
 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
 133        * it can.
 134        *
 135        * @return @c true if the rendering was completed successfully, @c false otherwise
 136        *
 137        * Example
 138        * @code
 139        * Color *map = colorMap(); // possible custom color map
 140        * if (!map) map = pd->colorMap(); // fall back to global color map
 141        *
 142        * // Get a list of bonds and render them
 143        * QList<Primitive *> list;
 144        * list = primitives().subList(Primitive::BondType);
 145        *
 146        * foreach(Primitive *p, list)
 147        *   render(static_cast<const Bond *>(p))
 148        *
 149        * return true;
 150        * @endcode
 151        *
 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.
 154        *
 155        * For more information on the various primitive lists available see
 156        * PrimitiveList.
 157        *
 158        */
 159       virtual bool renderOpaque(PainterDevice *pd) = 0;
 160       /**
 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.
 164        *
 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
 168        * it can.
 169        *
 170        * @return @c true if the rendering was completed successfully, @c false otherwise
 171        *
 172        * Example
 173        * @code
 174        * Color *map = colorMap(); // possible custom color map
 175        * if (!map) map = pd->colorMap(); // fall back to global color map
 176        *
 177        * // Get a list of atoms and render the selected ones as transparent spheres
 178        * QList<Primitive *> list;
 179        * list = primitives().subList(Primitive::AtomType);
 180        *
 181        * foreach(Primitive *p, list) {
 182        *   const Atom *a = static_cast<const Atom *>(p);
 183        *
 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);
 192        *   }
 193        * }
 194        * @endcode
 195        *
 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.
 198        *
 199        * For more information on the various primitive lists available see
 200        * PrimitiveList.
 201        *
 202        */
 203       virtual bool renderTransparent(PainterDevice *) { return true; }
 204
 205       /**
 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.
 212        */
 213       virtual bool renderQuick(PainterDevice *pd)
 214       {
 215         renderOpaque(pd);
 216         return true;
 217       }
 218
 219       /**
 220        * @return the engine's PrimitiveList containing all primitives the engine
 221        * can render.
 222        */
 223       PrimitiveList primitives() const;
 224
 225       /**
 226        * Set the primitives that the engine instance can render.
 227        * @param primitives the PrimitiveList the engine can render from.
 228        */
 229       virtual void setPrimitives(const PrimitiveList &primitives);
 230
 231       /**
 232        * Clear the primitives of the engine instance.
 233        */
 234       virtual void clearPrimitives();
 235
 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.
 239        */
 240       virtual double radius(const PainterDevice *pd, const Primitive *primitive = 0) const;
 241
 242       /**
 243        * @return transparency level, rendered low to high.
 244        */
 245       virtual double transparencyDepth() const;
 246
 247       /**
 248        * @return true if the engine is enabled or false if it is not.
 249        */
 250       bool isEnabled() const;
 251
 252       /**
 253        * Setter to enable or disable the engine instance.
 254        * @param enabled true to enable the egine, false to disable the engine.
 255        */
 256       void setEnabled(bool enabled);
 257
 258       /**
 259        * @return a QWidget containing the engine settings or 0
 260        * if no settings widget is available.
 261        */
 262       virtual QWidget *settingsWidget();
 263
 264       /**
 265        * @return a pointer to an identical engine or 0 if this fails
 266        */
 267       virtual Engine *clone() const = 0;
 268
 269       /**
 270        * Write the engine settings so that they can be saved between sessions.
 271        */
 272       virtual void writeSettings(QSettings &settings) const;
 273
 274       /**
 275        * Read in the settings that have been saved for the engine instance.
 276        */
 277       virtual void readSettings(QSettings &settings);
 278
 279     Q_SIGNALS:
 280       /**
 281        * Signals that something has been changed and the engine needs to render
 282        * after these changes were made.
 283        */
 284       void changed();
 285
 286     public Q_SLOTS:
 287       /**
 288        * Add the primitive to the engines PrimitiveList.
 289        * @param primitive to be added to the PrimitiveList.
 290        */
 291       virtual void addPrimitive(Primitive *primitive);
 292
 293       /**
 294        * Update the primitive in the engines PrimitiveList.
 295        * @param primitive to be updated in the PrimitiveList.
 296        */
 297       virtual void updatePrimitive(Primitive *primitive);
 298
 299       /**
 300        * Remove the primitive to from the engines PrimitiveList.
 301        * @param primitive to be removed from the PrimitiveList.
 302        */
 303       virtual void removePrimitive(Primitive *primitive);
 304
 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
 308        */
 309       virtual void setColorMap(Color *map);
 310
 311       /** @return the current color map used by this engine
 312        */
 313       virtual Color *colorMap();
 314
 315     private:
 316       EnginePrivate *const d;
 317   };
 318
 319   /**
 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.
 327    *
 328    * This class is used to generate new instances of the Engine class for which
 329    * it is defined.
 330    */
 331   class A_EXPORT EngineFactory
 332   {
 333     public:
 334       /**
 335        * Destructor.
 336        */
 337       virtual ~EngineFactory() {}
 338
 339       /**
 340        * @return pointer to a new instance of an Engine subclass object.
 341        */
 342       virtual Engine *createInstance(QObject *parent=0) = 0;
 343
 344       /**
 345        * @return the name of the class.
 346        */
 347       virtual QString className() = 0;
 348
 349       /**
 350        * @return the type of the engine instance.
 351        */
 352       virtual QString type() = 0;
 353
 354   };
 355
 356
 357 } // end namespace Avogadro
 358
 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)
 362
 363 #endif