Engine/source/gfx/sim/debugDraw.h

   1 //-----------------------------------------------------------------------------
   2 // Copyright (c) 2012 GarageGames, LLC
   3 //
   4 // Permission is hereby granted, free of charge, to any person obtaining a copy
   5 // of this software and associated documentation files (the "Software"), to
   6 // deal in the Software without restriction, including without limitation the
   7 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
   8 // sell copies of the Software, and to permit persons to whom the Software is
   9 // furnished to do so, subject to the following conditions:
  10 //
  11 // The above copyright notice and this permission notice shall be included in
  12 // all copies or substantial portions of the Software.
  13 //
  14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  17 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  19 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  20 // IN THE SOFTWARE.
  21 //-----------------------------------------------------------------------------
  22
  23 #ifndef _DEBUGDRAW_H_
  24 #define _DEBUGDRAW_H_
  25
  26 #ifndef _SIMOBJECT_H_
  27 #include "console/simObject.h"
  28 #endif
  29
  30 #ifndef _GFXDEVICE_H_
  31 #include "gfx/gfxDevice.h"
  32 #endif
  33
  34 #ifndef _PRIMBUILDER_H_
  35 #include "gfx/primBuilder.h"
  36 #endif
  37
  38 #ifndef _GFONT_H_
  39 #include "gfx/gFont.h"
  40 #endif
  41
  42 #ifndef _DATACHUNKER_H_
  43 #include "core/dataChunker.h"
  44 #endif
  45
  46 #ifndef _MPOLYHEDRON_H_
  47 #include "math/mPolyhedron.h"
  48 #endif
  49
  50
  51 class GFont;
  52
  53
  54 // We enable the debug drawer for non-shipping
  55 // builds.... you better be using shipping builds
  56 // for your final release.
  57 #ifndef TORQUE_SHIPPING
  58 #define ENABLE_DEBUGDRAW
  59 #endif
  60
  61
  62 /// Debug output class.
  63 ///
  64 /// This class provides you with a flexible means of drawing debug output. It is
  65 /// often useful when debugging collision code or complex 3d algorithms to have
  66 /// them draw debug information, like culling hulls or bounding volumes, normals,
  67 /// simple lines, and so forth. In TGE1.2, which was based directly on a simple
  68 /// OpenGL rendering layer, it was a simple matter to do debug rendering directly
  69 /// inline.
  70 ///
  71 /// Unfortunately, this doesn't hold true with more complex rendering scenarios,
  72 /// where render modes and targets may be in abritrary states. In addition, it is
  73 /// often useful to be able to freeze frame debug information for closer inspection.
  74 ///
  75 /// Therefore, Torque provides a global DebugDrawer instance, called gDebugDraw, which
  76 /// you can use to draw debug information. It exposes a number of methods for drawing
  77 /// a variety of debug primitives, including lines, triangles and boxes.
  78 /// Internally, DebugDrawer maintains a list of active debug primitives, and draws the
  79 /// contents of the list after each frame is done rendering. This way, you can be
  80 /// assured that your debug rendering won't interfere with TSE's various effect
  81 /// rendering passes or render-to-target calls.
  82 ///
  83 /// The DebugDrawer can also be used for more interesting uses, like freezing its
  84 /// primitive list so you can look at a situation more closely, or dumping the
  85 /// primitive list to disk for closer analysis.
  86 ///
  87 /// DebugDrawer is accessible by script under the name DebugDrawer, and by C++ under
  88 /// the symbol gDebugDraw. There are a variety of methods available for drawing
  89 /// different sorts of output; see the class reference for more information.
  90 ///
  91 /// DebugDrawer works solely in worldspace. Primitives are rendered with cull mode of
  92 /// none.
  93 ///
  94 class DebugDrawer : public SimObject
  95 {
  96 public:
  97    DECLARE_CONOBJECT(DebugDrawer);
  98
  99    DebugDrawer();
 100    ~DebugDrawer();
 101
 102    static DebugDrawer* get();
 103
 104    /// Called at engine init to set up the global debug draw object.
 105    static void init();
 106
 107    /// Called globally to render debug draw state. Also does state updates.
 108    void render(bool clear=true);
 109
 110    bool willDraw() { return isDrawing && mHead; }
 111
 112    void toggleFreeze()  { shouldToggleFreeze = true; };
 113    void toggleDrawing()
 114    {
 115 #ifdef ENABLE_DEBUGDRAW
 116       isDrawing = !isDrawing;
 117 #endif
 118    };
 119
 120
 121    /// @name ddrawmeth Debug Draw Methods
 122    ///
 123    /// @{
 124
 125    void drawBoxOutline(const Point3F &a, const Point3F &b, const ColorF &color = ColorF(1.0f, 1.0f, 1.0f));
 126    void drawTransformedBoxOutline(const Point3F &a, const Point3F &b, const ColorF &color, const MatrixF& transform);
 127
 128    void drawBox(const Point3F &a, const Point3F &b, const ColorF &color = ColorF(1.0f,1.0f,1.0f));
 129    void drawLine(const Point3F &a, const Point3F &b, const ColorF &color = ColorF(1.0f,1.0f,1.0f));
 130    void drawTri(const Point3F &a, const Point3F &b, const Point3F &c, const ColorF &color = ColorF(1.0f,1.0f,1.0f));
 131    void drawText(const Point3F& pos, const String& text, const ColorF &color = ColorF(1.0f,1.0f,1.0f));
 132    void drawCapsule(const Point3F &a, const F32 &radius, const F32 &height, const ColorF &color = ColorF(1.0f, 1.0f, 1.0f));
 133    void drawDirectionLine(const Point3F &a, const Point3F &b, const ColorF &color = ColorF(1.0f, 1.0f, 1.0f));
 134    void drawOutlinedText(const Point3F& pos, const String& text, const ColorF &color = ColorF(1.0f, 1.0f, 1.0f), const ColorF &colorOutline = ColorF(0.0f, 0.0f, 0.0f));
 135
 136    /// Render a wireframe view of the given polyhedron.
 137    void drawPolyhedron( const AnyPolyhedron& polyhedron, const ColorF& color = ColorF( 1.f, 1.f, 1.f ) );
 138
 139    /// Render the plane indices, edge indices, edge direction indicators, and point coordinates
 140    /// of the given polyhedron for debugging.
 141    ///
 142    /// Green lines are plane normals.  Red lines point from edge midpoints along the edge direction (i.e. to the
 143    /// second vertex).  This shows if the orientation is correct to yield CW ordering for face[0].  Indices and
 144    /// coordinates of vertices are shown in white.  Plane indices are rendered in black.  Edge indices and their
 145    /// plane indices are rendered in white.
 146    void drawPolyhedronDebugInfo( const AnyPolyhedron& polyhedron, const MatrixF& transform, const Point3F& scale );
 147
 148    /// Set the TTL for the last item we entered...
 149    ///
 150    /// Primitives default to lasting one frame (ie, ttl=0)
 151    enum : U32
 152    {
 153       DD_INFINITE = U32_MAX
 154    };
 155    // How long should this primitive be draw for, 0 = one frame, DD_INFINITE = draw forever
 156    void setLastTTL(U32 ms);
 157
 158    /// Disable/enable z testing on the last primitive.
 159    ///
 160    /// Primitives default to z testing on.
 161    void setLastZTest(bool enabled);
 162
 163    /// @}
 164 private:
 165    typedef SimObject Parent;
 166
 167    static DebugDrawer* sgDebugDrawer;
 168
 169    struct DebugPrim
 170    {
 171       /// Color used for this primitive.
 172       ColorF color;
 173       ColorF color2;
 174
 175       /// Points used to store positional data. Exact semantics determined by type.
 176       Point3F a, b, c;
 177       enum {
 178          Tri,
 179          Box,
 180          Line,
 181          Text,
 182          DirectionLine,
 183          OutlinedText,
 184          Capsule,
 185       } type;      ///< Type of the primitive. The meanings of a,b,c are determined by this.
 186
 187       SimTime dieTime;   ///< Time at which we should remove this from the list.
 188       bool useZ; ///< If true, do z-checks for this primitive.
 189       char mText[256];      // Text to display
 190
 191       DebugPrim *next;
 192    };
 193
 194
 195    FreeListChunker<DebugPrim> mPrimChunker;
 196    DebugPrim *mHead;
 197
 198    bool isFrozen;
 199    bool shouldToggleFreeze;
 200    bool isDrawing;
 201
 202    GFXStateBlockRef mRenderZOffSB;
 203    GFXStateBlockRef mRenderZOnSB;
 204    GFXStateBlockRef mRenderAlpha;
 205
 206    Resource<GFont> mFont;
 207
 208    void setupStateBlocks();
 209 };
 210
 211 #endif // _DEBUGDRAW_H_