kalzium/libavogadro-kalzium/src/painter.h

   1 /**********************************************************************
   2   Painter - drawing spheres, cylinders and text
   3
   4   Copyright (C) 2007 Benoit Jacob
   5   Copyright (C) 2007 Donald Ephraim Curtis
   6   Copyright (C) 2007 Marcus D. Hanwell
   7
   8   This file is part of the Avogadro molecular editor project.
   9   For more information, see <http://avogadro.sourceforge.net/>
  10
  11   Avogadro is free software; you can redistribute it and/or modify
  12   it under the terms of the GNU General Public License as published by
  13   the Free Software Foundation; either version 2 of the License, or
  14   (at your option) any later version.
  15
  16   Avogadro is distributed in the hope that it will be useful,
  17   but WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19   GNU General Public License for more details.
  20
  21   You should have received a copy of the GNU General Public License
  22   along with this program; if not, write to the Free Software
  23   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  24   02110-1301, USA.
  25  **********************************************************************/
  26
  27 #ifndef __PAINTER_H
  28 #define __PAINTER_H
  29
  30 #include <avogadro/global.h>
  31 #include <avogadro/primitive.h>
  32
  33 namespace Avogadro
  34 {
  35   /**
  36    * @class Painter painter.h
  37    * @brief Pure virtual Painter base class to be implemented by painters.
  38    * @author Marcus D. Hanwell
  39    *
  40    * This class is a pure virtual base class of the Painter. It should be
  41    * implemented by painters in order to satisfy all primitives objects to be
  42    * drawn by the engines.
  43    *
  44    * @sa GLPainter, POVPainter
  45    */
  46   class Color;
  47   class Painter : public QObject
  48   {
  49   public:
  50     /**
  51      * Constructor.
  52      */
  53     Painter();
  54
  55     /**
  56      * Destructor.
  57      */
  58     ~Painter();
  59
  60     /**
  61      * @return the current global quality setting.
  62      */
  63     virtual int quality() const = 0;
  64
  65     /**
  66      * Uses the primitive to set the type and name if the Paint Device supports it.
  67      * @param primitive the primitive about to be drawn.
  68      */
  69     virtual void setName (const Primitive *primitive) = 0;
  70
  71     /**
  72      * Sets the primitive type and id.
  73      * @param type the primitive type about to be drawn.
  74      * @param id the primitive id.
  75      */
  76     virtual void setName (Primitive::Type type, int id) = 0;
  77
  78     /**
  79      * Set the color to paint the primitive elements with.
  80      * @param color the color to be used for painting.
  81     */
  82     virtual void setColor (const Color *color) = 0;
  83
  84     /**
  85      * Set the color to paint elements with where 0.0 is the minimum and 1.0
  86      * is the maximum.
  87      * @param red component of the color.
  88      * @param green component of the color.
  89      * @param blue component of the color.
  90      * @param alpha component of the color.
  91      */
  92     virtual void setColor (float red, float green, float blue, float alpha = 1.0) = 0;
  93
  94     /**
  95      * Draws a sphere, leaving the Painter choose the appropriate detail level based on the
  96      * apparent radius (ratio of radius over distance) and the global quality setting.
  97      * @param center the position of the center of the sphere.
  98      * @param radius the radius of the sphere.
  99      */
 100     virtual void drawSphere (const Eigen::Vector3d & center, double radius) = 0;
 101
 102     /**
 103      * Draws a cylinder, leaving the Painter choose the appropriate detail level based on the
 104      * apparent radius (ratio of radius over distance) and the global quality setting.
 105      * @param end1 the position of the first end of the cylinder.
 106      * @param end2 the position of the second end of the cylinder.
 107      * @param radius the radius, i.e. half-width of the cylinder.
 108      */
 109     virtual void drawCylinder (const Eigen::Vector3d &end1,
 110                                const Eigen::Vector3d &end2,
 111                                double radius) = 0;
 112
 113     /**
 114      * Draws a multiple cylinder (see below), leaving the Painter choose the appropriate
 115      * detail level based on the apparent radius (ratio of radius over distance) and the
 116      * global quality setting.
 117      *
 118      * What is a "multiple cylinder"? Think bond of order two or more between two atoms.
 119      * This function is here to allow drawing multiple bonds in a single call.
 120      *
 121      * This function takes care of rendering multiple bonds in such a way that the individual
 122      * bonds avoid hiding each other, at least in the defaut viewpoint of a molecule.
 123      * To achieves that, it asks the GLWidget for the the normal vector of the
 124      * molecule's best-fitting plane.
 125      *
 126      * @param end1 the position of the first end of the bond.
 127      * @param end2 the position of the second end of the bond.
 128      * @param radius the radius, i.e. half-width of each cylinder.
 129      * @param order the multiplicity order of the bond, e.g. 2 for a double bond.
 130      *              When this parameter equals 1, this function is equivalent to
 131      *              drawCylinder().
 132      * @param shift how far away from the central axis the cylinders are shifted.
 133      *              In other words this influences the total width of multiple bonds.
 134      */
 135     virtual void drawMultiCylinder (const Eigen::Vector3d &end1,
 136                                     const Eigen::Vector3d &end2,
 137                                     double radius, int order, double shift) = 0;
 138
 139     /**
 140      * Draws a cone between the tip and the base with the base radius given.
 141      * @param base the position of the base of the cone.
 142      * @param tip the position of the tip of the cone.
 143      * @param radius the radius of the base of the cone.
 144      */
 145     virtual void drawCone(const Eigen::Vector3d &base,
 146                           const Eigen::Vector3d &tip,
 147                           double radius) = 0;
 148
 149     /**
 150      * Draws a line between the given points of the given width.
 151      * @param start the position of the start of the line.
 152      * @param end the position of the end of the line.
 153      * @param lineWidth the width of the line.
 154      */
 155     virtual void drawLine(const Eigen::Vector3d &start,
 156                           const Eigen::Vector3d &end,
 157                           double lineWidth) = 0;
 158
 159     /**
 160      * Draws a multiple line between the given points. This function is the
 161      * line equivalent to the drawMultiCylinder function and performs the
 162      * same basic operations using simpler and quicker lines.
 163      * @param start the position of the start of the line.
 164      * @param end the position of the end of the line.
 165      * @param lineWidth the width of the line.
 166      * @param order the order of the bond, e.g. 2 for a double bond.
 167      * @param stipple The stipple parameter for the bond, can be used to
 168      * draw aromatic bonds etc.
 169      * sa drawMultiCylinder
 170      */
 171     virtual void drawMultiLine(const Eigen::Vector3d &start,
 172                                const Eigen::Vector3d &end, double lineWidth,
 173                                int order, short stipple) = 0;
 174
 175     /**
 176      * Draws a triangle with vertives on the three given points. This function
 177      * calculates the normal of the triangle and corrects the winding order to
 178      * ensure the front face is facing the camera.
 179      * @param p1 first triangle vertex.
 180      * @param p2 second triangle vertex.
 181      * @param p3 third triangle vertex.
 182      */
 183     virtual void drawTriangle(const Eigen::Vector3d &p1,
 184                               const Eigen::Vector3d &p2,
 185                               const Eigen::Vector3d &p3) = 0;
 186
 187     /**
 188      * Draws a triangle with vertives on the three given points using the
 189      * given normal. This function corrects the triangle's winding order.
 190      * @param p1 first triangle vertex.
 191      * @param p2 second triangle vertex.
 192      * @param p3 third triangle vertex.
 193      * @param n the normal of the triangle.
 194      */
 195     virtual void drawTriangle(const Eigen::Vector3d &p1,
 196                               const Eigen::Vector3d &p2,
 197                               const Eigen::Vector3d &p3,
 198                               const Eigen::Vector3d &n) = 0;
 199
 200     /**
 201      * Draw a cubic B-spline between the given points.
 202      * @param pts QVector containing the points to draw the cubic B-spline
 203      * along.
 204      * @param radius the radius of the cubic B-spline.
 205      */
 206     virtual void drawSpline(const QVector<Eigen::Vector3d>& pts,
 207                             double radius) = 0;
 208
 209     /**
 210      * Draws a shaded sector of a circle.  The sector is defined by three vectors,
 211      * the center of the circle, and two vectors that define the lines going out
 212      * from the centre of the circle to the circumference of the circle.  The
 213      * actual points on the circumference are found using these two vectors and
 214      * the radius of the circle.
 215      *
 216      * @param origin the center of the circle this sector is a portion of.
 217      * @param direction1 a vector defining the line the first point will lie on.
 218      * @param direction2 a vector defining the line the second point will lie on.
 219      * @param radius the radius of the circle this sector is a portion of.
 220      * @param alternateAngle whether to draw the obtuse angle made by the
 221      * two vectors instead of the acute angle between them.
 222      */
 223     virtual void drawShadedSector(Eigen::Vector3d origin,
 224                                   Eigen::Vector3d direction1,
 225                                   Eigen::Vector3d direction2, double radius,
 226                                   bool alternateAngle = false) = 0;
 227
 228     /**
 229      * Draws an arc.  The arc is defined by three vectors, the center of the circle,
 230      * and two vectors that define the lines going out from the center of the
 231      * circle to the circumference of the circle.  The actual points on the
 232      * circumference are found using these two vectors and the radius of the circle.
 233      *
 234      * @param origin the center of the circle whose circumference this arc is a portion of.
 235      * @param direction1 a vector defining the line the start of the arc will lie on.
 236      * @param direction2 a vector defining the line the end of the arc will lie on.
 237      * @param radius the radius of the circle whose circumference this arc is a portion of.
 238      * @param lineWidth the thickness of the line the arc will be drawn with.
 239      * @param alternateAngle whether to draw the obtuse angle made by the two vectors
 240      *                       instead of the acute angle between them.
 241      */
 242     virtual void drawArc(Eigen::Vector3d origin, Eigen::Vector3d direction1,
 243                          Eigen::Vector3d direction2, double radius,
 244                          double lineWidth, bool alternateAngle = false) = 0;
 245
 246     /**
 247      * Draws a solid two dimensional quadrilateral in three dimensional space.
 248      *
 249      * @param point1 the first of the four corners of the quadrilateral.
 250      * @param point2 the second of the four corners of the quadrilateral.
 251      * @param point3 the third of the four corners of the quadrilateral.
 252      * @param point4 the last of the four corners of the quadrilateral.
 253      */
 254     virtual void drawShadedQuadrilateral(Eigen::Vector3d point1,
 255                                          Eigen::Vector3d point2,
 256                                          Eigen::Vector3d point3,
 257                                          Eigen::Vector3d point4) = 0;
 258
 259     /**
 260      * Draws the outline of a two dimensional quadrilateral in three dimensional space.
 261      *
 262      * @param point1 the first of the four corners of the quadrilateral.
 263      * @param point2 the second of the four corners of the quadrilateral.
 264      * @param point3 the third of the four corners of the quadrilateral.
 265      * @param point4 the last of the four corners of the quadrilateral.
 266      * @param lineWidth the thickness of the line the quadrilateral will be drawn with.
 267      */
 268     virtual void drawQuadrilateral(Eigen::Vector3d point1,
 269                                    Eigen::Vector3d point2,
 270                                    Eigen::Vector3d point3,
 271                                    Eigen::Vector3d point4,
 272                                    double lineWidth) = 0;
 273
 274     /**
 275      * Draws text at a given window position, on top of the scene.
 276      * @note Calls to drawText methods must be enclosed between begin() and end().
 277      * @note Text is rendered as a transparent object, and should therefore be
 278      * rendered after the opaque objects.
 279      * @param x,y the window coordinates of the top-left corner of the text to
 280      * render, (0, 0) is the top-left corner of the window.
 281      * @param string the string to render. All character encodings are allowed
 282      * but superposed characters are not supported yet. For accented letters,
 283      * use a character giving the whole accented letter, not a separate
 284      * character for the accent.
 285      * @sa begin(), drawText(const Eigen::Vector3d &, const QString &) const,
 286      *     drawText(const QPoint &, const QString &) const
 287      */
 288     virtual int drawText (int x, int y, const QString &string) const = 0;
 289
 290     /**
 291      * Draws text at a given window position, on top of the scene.
 292      * @note Calls to drawText methods must be enclosed between begin() and endText().
 293      * @note Text is rendered as a transparent object, and should therefore be
 294      * rendered after the opaque objects.
 295      * @param pos the window coordinates of the top-left corner of the text to
 296      * render, (0, 0) is the top-left corner of the window.
 297      * @param string the string to render. All character encodings are allowed
 298      * but superposed characters are not supported yet. For accented letters,
 299      * use a character giving the whole accented letter, not a separate
 300      * character for the accent.
 301      * @sa begin(), drawText(const Eigen::Vector3d &, const QString &) const,
 302      *     drawText(int, int, const QString &) const
 303      */
 304     virtual int drawText (const QPoint& pos, const QString &string) const = 0;
 305
 306     /**
 307      * Draws text at a given scene position, inside the scene.
 308      * @note Calls to drawText methods must be enclosed between begin() and endText().
 309      * @note Text is rendered as a transparent object, and should therefore be
 310      * rendered after the opaque objects.
 311      * @param pos the scene coordinates of the top-left corner of the text to
 312      * render.
 313      * @param string The string to render. All character encodings are allowed
 314      * but superposed characters are not supported yet. For accented letters,
 315      * use a character giving the whole accented letter, not a separate
 316      * character for the accent.
 317      * @sa begin(), drawText(const QPoint&, const QString &) const,
 318      *     drawText(int, int, const QString &) const
 319      */
 320     virtual int drawText (const Eigen::Vector3d & pos,
 321                           const QString &string) const = 0;
 322   };
 323 } // end namespace Avogadro
 324
 325 #endif