kalzium/libavogadro-kalzium/src/textrenderer.h

   1 /**********************************************************************
   2   TextRenderer - a temporary replacement for QGLWidget::renderText until it
   3   matures a bit more ;)
   4
   5   Copyright (C) 2007 Benoit Jacob
   6
   7   This file is part of the Avogadro molecular editor project.
   8   For more information, see <http://avogadro.sourceforge.net/>
   9
  10   Avogadro is free software; you can redistribute it and/or modify
  11   it under the terms of the GNU General Public License as published by
  12   the Free Software Foundation; either version 2 of the License, or
  13   (at your option) any later version.
  14
  15   Avogadro is distributed in the hope that it will be useful,
  16   but WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18   GNU General Public License for more details.
  19
  20   You should have received a copy of the GNU General Public License
  21   along with this program; if not, write to the Free Software
  22   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  23   02110-1301, USA.
  24  **********************************************************************/
  25
  26 #ifndef __TEXTRENDERER_H
  27 #define __TEXTRENDERER_H
  28
  29 #include <avogadro/global.h>
  30 #include <eigen/vector.h>
  31
  32
  33 /**
  34  * @class TextRenderer
  35  * @internal
  36  * @author Benoit Jacob
  37  *
  38  * NOTE: This class is only there as a temporary replacement for
  39  * QGLWidget::renderText(). As of Qt 4.2.3 and Qt 4.3-beta1, this function is
  40  * too slow and can't do outlined text. If a future version of Qt brings a
  41  * sufficiently improved QGLWidget::renderText(), we will of course drop this class.
  42  *
  43  * This class renders text inside a QGLWidget. It replaces the functionality
  44  * of QGLWidget::renderText().
  45  *
  46  * Its advantages over the renderText() in Qt 4.2.3 are that it is much faster both at
  47  * render-time and at startup, consumes less memory, and does outlined text. Its drawbacks are that
  48  * it can't yet handle rendering more than one font simultaneously, and that its Unicode-safeness is
  49  * not perfect as superpositions of unicode characters aren't handled.
  50  *
  51  * Every QFont can be used, every character encodings supported by Qt can be used.
  52  *
  53  * To draw plain 2D text on top of the scene, do:
  54  * @code
  55  textRenderer.begin();
  56  textRenderer.draw( x1, y1, string1 );
  57  textRenderer.draw( x2, y2, string2 );
  58  textRenderer.draw( x3, y2, string3 );
  59  textRenderer.end();
  60  * @endcode
  61  *
  62  * To draw text as a transparent object inside the scene, do:
  63  * @code
  64  textRenderer.begin();
  65  textRenderer.draw( pos1, string1 );
  66  textRenderer.draw( pos2, string2 );
  67  textRenderer.draw( pos3, string3 );
  68  textRenderer.end();
  69  * @endcode
  70  *
  71  * In order to set the text color, please call glColor3f or glColor4f before
  72  * calling draw(). Of course you can
  73  * also call qglColor or Color::apply(). You can achieve semitransparent text at
  74  * no additional cost by choosing a semitransparent color.
  75  *
  76  * Please make sure that no relevant OpenGL state change occurs between
  77  * begin() and end(), except the state changes performed by the TextRenderer
  78  * itself. In other words, please avoid calling glSomething() between begin() and
  79  * end(), except if you are sure that this call won't result in a conflicting state
  80  * change. Of course calling glColor*() is allowed.
  81  *
  82  * If you experience rendering problems, you can try the following:
  83  * - disable some OpenGL state bits. For instance, TextRenderer automatically
  84  *   disables fog and lighting during rendering, because it doesn't work
  85  *   correctly with them enabled. There probably are other OpenGL state bits
  86  *   that have to be disabled, so if your program enables some of them, you
  87  *   might have to disable them before rendering text.
  88  * - if you experience poor font quality, meake sure that your GLWidget is using
  89  *   an antialiased font.
  90  *
  91  */
  92
  93 namespace Avogadro
  94 {
  95
  96   class CharRenderer;
  97   class GLWidget;
  98
  99   class TextRendererPrivate;
 100   class TextRenderer
 101   {
 102     public:
 103       TextRenderer();
 104       ~TextRenderer();
 105
 106       /**
 107        * This should be called only once, before any printing occurs.
 108        * @param glwidget The GLWidget in which to render.
 109        */
 110 //       void setGLWidget( GLWidget *glwidget );
 111
 112       /**
 113        * Call this before drawing any text. This method saves the GL state
 114        * and changes it to prepare for text rendering.
 115        */
 116       void begin(GLWidget *widget);
 117
 118       /**
 119        * Call this after drawing text. This method restores the GL state
 120        * to what it was when begin() was called.
 121        */
 122       void end();
 123
 124       /**
 125        * Draw text inside the 3D scene. Must be called between begin() and end().
 126        * The text is centered (both horizontally and vertically) around the specified position.
 127        * @param pos the position of the text in the scene's coordinate system
 128        * @param string the QString to render
 129        * @returns the height in pixels of the text just rendered (0 for an empty string).
 130        */
 131       int draw( const Eigen::Vector3d & pos, const QString &string);
 132
 133       /**
 134        * Draw 2D text at the position (x,y) in window coordinates. Must be called
 135        * between begin() and end().
 136        * (0,0) is the top-left corner.
 137        * @param x the x-coordinate
 138        * @param y the y-coordinate
 139        * @param string the QString to render
 140        * @returns the height in pixels of the text just rendered (0 for an empty string).
 141        */
 142       int draw( int x, int y, const QString &string);
 143
 144       bool isActive();
 145
 146     private:
 147
 148       TextRendererPrivate * const d;
 149   };
 150
 151 } // namespace Avogadro
 152
 153 #endif // __TEXTRENDERER_H