Back

DrawTool

abstract
Provides utility functions for minimal debug drawing, including geometric shapes, text, transformations, and state management.
sheet
# DrawTool **Overview** DrawTool is a utility class in SOFA that provides methods for performing minimal debug drawing. It supports various graphical elements such as points, lines, triangles, quads, spheres, ellipsoids, bounding boxes, text, and more. The class also includes transformation methods (translate, scale) and state management techniques to maintain rendering consistency. **Parameters and Data** The `DrawTool` class does not expose any significant data fields; its functionality is primarily through method calls for drawing operations and transformations. **Dependencies and Connections** Components in SOFA receive a pointer to the DrawTool instance via the VisualParams parameter of their draw methods. This allows them to perform debug drawings using the provided functions.
componentOverview
{
  "description": "The `DrawTool` class in the SOFA (Simulation Open-Framework Architecture) framework provides an abstract interface for rendering various graphical elements and managing drawing states within a 3D scene.",
  "name": "DrawTool",
  "namespace": "sofa::helper::visual"
}
keyFeatures
  • {'name': 'Rendering Capabilities', 'description': 'The `DrawTool` class supports the rendering of various geometric shapes, including points, lines, triangles, quads, spheres, bounding boxes, and text. It also allows for drawing custom overlays with 2D text and managing polygon offsets.'}
  • {'name': 'State Management', 'description': 'It provides methods to save and restore the state of the drawing context using RAII (Resource Acquisition Is Initialization) technique through `StateLifeCycle` struct. This ensures that drawing states are correctly managed and restored after operations, maintaining consistency in rendering pipelines.'}
  • {'name': 'Transformation Methods', 'description': 'The class supports transformation operations like pushing and popping matrices from the stack, scaling, translating, and applying transformations with a matrix for complex scene manipulations.'}
  • {'name': 'Drawing Styles', 'description': 'Users can set material properties, polygon modes (fill or wireframe), lighting conditions, and enable/disable various rendering features such as blending, depth testing, and lighting to control the appearance of rendered objects.'}
  • {'name': 'Color Buffer Methods', 'description': 'It provides a method for reading pixel data from the color buffer (`readPixels`), which can be useful for implementing post-processing effects or performing screen-space operations like raytracing in software or capturing screenshots with depth information.'}
componentDetails
{
  "author": "The SOFA Team and external contributors",
  "dependencies": [
    "sofa::type"
  ],
  "license": "GNU Lesser General Public License (LGPL) version 2.1 or later"
}
usageInstructions
{
  "exampleCode": "```cpp\n#include \u003csofa/helper/visual/DrawTool.h\u003e\n\nusing namespace sofa::helper::visual;\n\n// Assuming drawTool is an instance of a specific DrawTool subclass like GLDrawTool\ndrawTool-\u003edrawSphere(Vec3(0.0, 0.0, 0.0), 1.0);\ndrawTool-\u003epushMatrix();\ndrawTool-\u003etranslate(2.0, 0.0, 0.0);\ndrawTool-\u003edrawTetrahedron(Vec3(0,0,0), Vec3(1,0,0), Vec3(0,1,0), Vec3(0,0,1));\ndrawTool-\u003epopMatrix();\n```",
  "overview": "To use the `DrawTool` class, instantiate a derived concrete implementation such as OpenGL-based renderer and call its methods to render graphical elements and manage drawing states."
}
maths
The `DrawTool` class in the SOFA framework is not directly involved with mathematical computations or physical simulations but rather serves as an interface for rendering and manipulating graphical elements within a 3D scene. The core functionalities provided by this class include various drawing operations, transformation methods, state management techniques, and overlay drawing functions. ### Drawing Operations The `DrawTool` class provides several member functions for drawing geometric shapes in the 3D space such as points, lines, triangles, quads, tetrahedra, hexahedra, spheres, ellipsoids, bounding boxes, and text. These functions allow setting vertices (points), normals, and colors to render these shapes. - **Drawing Points:** Functions like `drawPoint` accept a position vector (`Vec3`) and optionally a color (`RGBAColor`). - Mathematically, drawing a point involves plotting its position in the coordinate system defined by the scene's camera. - **Drawing Triangles and Quads:** Methods such as `drawTriangle` and `drawQuad` take vertices and normals (optional) to render filled polygons. These can include optional per-vertex colors for shading purposes. - Mathematically, these operations involve transforming vertex coordinates through the current model-view-projection matrix and interpolating colors across surfaces based on Gouraud or Phong shading models. ### Transformation Methods Transformation methods provided by `DrawTool` enable applying affine transformations (scale, translate, rotate) to objects being rendered. Functions like `translate`, `scale`, and `multMatrix` are used for modifying the model-view matrix which affects how objects appear on screen after projection. - Mathematically, transformation matrices are applied sequentially in a stack-based manner with functions like `pushMatrix` and `popMatrix`. Matrix multiplication is performed to combine multiple transformations into one composite transformation. ### State Management State management involves saving and restoring rendering states through functions such as `saveLastState` and `restoreLastState`, which help maintain consistency across different drawing operations without needing to manually set up the same state repeatedly. - Mathematically, this can involve copying current matrix stacks or other rendering settings like lighting modes into a stack and then reverting them when needed using standard LIFO (last-in-first-out) principles. ### Overlay Methods and Color Buffer Operations Overlay methods such as `writeOverlayText` enable drawing text directly on the screen at specified 2D coordinates. Additionally, functions like `readPixels` allow reading color data from the rendering buffer to retrieve RGB values or depth information (`z-buffer`). - Mathematically, these operations involve memory reads and writes within the frame buffer, which is a two-dimensional array of pixels representing the final rendered image. ### Lighting and Blending Operations The class provides methods for enabling/disabling lighting and blending modes that affect how colors are combined in the final rendering process. Functions such as `setLightingEnabled` and `enableBlending` control whether lighting calculations or alpha-blending should be applied during drawing operations, respectively. - Mathematically, these involve setting parameters in shaders used for fragment coloring based on light sources (for lighting) or combining colors using blend factors for transparency blending. 
{
  "name": "DrawTool",
  "main": {
    "name": "DrawTool",
    "namespace": "sofa::helper::visual",
    "module": "Sofa.framework.Helper",
    "include": "sofa/helper/visual/DrawTool.h",
    "doc": "Utility class to perform debug drawing.\n Class which contains a set of methods to perform minimal debug drawing regardless of the graphics API used.\n Components receive a pointer to the DrawTool through the VisualParams parameter of their draw method.\n Sofa provides a default concrete implementation of this class for the OpenGL API with the DrawToolGL class.\nk",
    "inherits": [],
    "templates": [],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawPoints",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "size",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawPoints",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "size",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawLine",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawInfiniteLine",
        "return_type": "void",
        "params": [
          {
            "name": "point",
            "type": "const Vec3 &"
          },
          {
            "name": "direction",
            "type": "const Vec3 &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "vanishing",
            "type": "const bool &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawInfiniteLine",
        "return_type": "void",
        "params": [
          {
            "name": "point",
            "type": "const Vec3 &"
          },
          {
            "name": "direction",
            "type": "const Vec3 &"
          },
          {
            "name": "size",
            "type": "const float &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "vanishing",
            "type": "const bool &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawLines",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "size",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawLines",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "size",
            "type": "float"
          },
          {
            "name": "colors",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawLines",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "index",
            "type": "const int &"
          },
          {
            "name": "size",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawLineStrip",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "size",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawLineLoop",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "size",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawDisk",
        "return_type": "void",
        "params": [
          {
            "name": "radius",
            "type": "float"
          },
          {
            "name": "from",
            "type": "double"
          },
          {
            "name": "to",
            "type": "double"
          },
          {
            "name": "resolution",
            "type": "int"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawCircle",
        "return_type": "void",
        "params": [
          {
            "name": "radius",
            "type": "float"
          },
          {
            "name": "lineThickness",
            "type": "float"
          },
          {
            "name": "resolution",
            "type": "int"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTriangles",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTriangles",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "normal",
            "type": "const Vec3 &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTriangles",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "index",
            "type": "const int &"
          },
          {
            "name": "normal",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTriangles",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "index",
            "type": "const int &"
          },
          {
            "name": "normal",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTriangles",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTriangles",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "normal",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTriangleStrip",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "normal",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTriangleFan",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "normal",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawFrame",
        "return_type": "void",
        "params": [
          {
            "name": "position",
            "type": "const Vec3 &"
          },
          {
            "name": "orientation",
            "type": "const Quaternion &"
          },
          {
            "name": "size",
            "type": "const Vec3f &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawFrame",
        "return_type": "void",
        "params": [
          {
            "name": "position",
            "type": "const Vec3 &"
          },
          {
            "name": "orientation",
            "type": "const Quaternion &"
          },
          {
            "name": "size",
            "type": "const Vec3f &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawSpheres",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "radius",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawSpheres",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "radius",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawFakeSpheres",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "radius",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawFakeSpheres",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "radius",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawCone",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "radius1",
            "type": "float"
          },
          {
            "name": "radius2",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "subd",
            "type": "int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawCube",
        "return_type": "void",
        "params": [
          {
            "name": "radius",
            "type": "const float &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "subd",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawCylinder",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "radius",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "subd",
            "type": "int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawCapsule",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "radius",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "subd",
            "type": "int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawArrow",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "radius",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "subd",
            "type": "int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawArrow",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "radius",
            "type": "float"
          },
          {
            "name": "coneLength",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "subd",
            "type": "int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawArrow",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "radius",
            "type": "float"
          },
          {
            "name": "coneLength",
            "type": "float"
          },
          {
            "name": "coneRadius",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "subd",
            "type": "int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawCross",
        "return_type": "void",
        "params": [
          {
            "name": "p",
            "type": "const Vec3 &"
          },
          {
            "name": "length",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawPlus",
        "return_type": "void",
        "params": [
          {
            "name": "radius",
            "type": "const float &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "subd",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawPoint",
        "return_type": "void",
        "params": [
          {
            "name": "p",
            "type": "const Vec3 &"
          },
          {
            "name": "c",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawPoint",
        "return_type": "void",
        "params": [
          {
            "name": "p",
            "type": "const Vec3 &"
          },
          {
            "name": "n",
            "type": "const Vec3 &"
          },
          {
            "name": "c",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTriangle",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "p3",
            "type": "const Vec3 &"
          },
          {
            "name": "normal",
            "type": "const Vec3 &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTriangle",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "p3",
            "type": "const Vec3 &"
          },
          {
            "name": "normal",
            "type": "const Vec3 &"
          },
          {
            "name": "c",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTriangle",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "p3",
            "type": "const Vec3 &"
          },
          {
            "name": "normal",
            "type": "const Vec3 &"
          },
          {
            "name": "c1",
            "type": "const RGBAColor &"
          },
          {
            "name": "c2",
            "type": "const RGBAColor &"
          },
          {
            "name": "c3",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTriangle",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "p3",
            "type": "const Vec3 &"
          },
          {
            "name": "normal1",
            "type": "const Vec3 &"
          },
          {
            "name": "normal2",
            "type": "const Vec3 &"
          },
          {
            "name": "normal3",
            "type": "const Vec3 &"
          },
          {
            "name": "c1",
            "type": "const RGBAColor &"
          },
          {
            "name": "c2",
            "type": "const RGBAColor &"
          },
          {
            "name": "c3",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawQuad",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "p3",
            "type": "const Vec3 &"
          },
          {
            "name": "p4",
            "type": "const Vec3 &"
          },
          {
            "name": "normal",
            "type": "const Vec3 &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawQuad",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "p3",
            "type": "const Vec3 &"
          },
          {
            "name": "p4",
            "type": "const Vec3 &"
          },
          {
            "name": "normal",
            "type": "const Vec3 &"
          },
          {
            "name": "c",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawQuad",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "p3",
            "type": "const Vec3 &"
          },
          {
            "name": "p4",
            "type": "const Vec3 &"
          },
          {
            "name": "normal",
            "type": "const Vec3 &"
          },
          {
            "name": "c1",
            "type": "const RGBAColor &"
          },
          {
            "name": "c2",
            "type": "const RGBAColor &"
          },
          {
            "name": "c3",
            "type": "const RGBAColor &"
          },
          {
            "name": "c4",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawQuad",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "p3",
            "type": "const Vec3 &"
          },
          {
            "name": "p4",
            "type": "const Vec3 &"
          },
          {
            "name": "normal1",
            "type": "const Vec3 &"
          },
          {
            "name": "normal2",
            "type": "const Vec3 &"
          },
          {
            "name": "normal3",
            "type": "const Vec3 &"
          },
          {
            "name": "normal4",
            "type": "const Vec3 &"
          },
          {
            "name": "c1",
            "type": "const RGBAColor &"
          },
          {
            "name": "c2",
            "type": "const RGBAColor &"
          },
          {
            "name": "c3",
            "type": "const RGBAColor &"
          },
          {
            "name": "c4",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawQuads",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawQuads",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "colors",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTetrahedron",
        "return_type": "void",
        "params": [
          {
            "name": "p0",
            "type": "const Vec3 &"
          },
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "p3",
            "type": "const Vec3 &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawScaledTetrahedron",
        "return_type": "void",
        "params": [
          {
            "name": "p0",
            "type": "const Vec3 &"
          },
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "p3",
            "type": "const Vec3 &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "scale",
            "type": "const float"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawTetrahedra",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawScaledTetrahedra",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "scale",
            "type": "const float"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawHexahedron",
        "return_type": "void",
        "params": [
          {
            "name": "p0",
            "type": "const Vec3 &"
          },
          {
            "name": "p1",
            "type": "const Vec3 &"
          },
          {
            "name": "p2",
            "type": "const Vec3 &"
          },
          {
            "name": "p3",
            "type": "const Vec3 &"
          },
          {
            "name": "p4",
            "type": "const Vec3 &"
          },
          {
            "name": "p5",
            "type": "const Vec3 &"
          },
          {
            "name": "p6",
            "type": "const Vec3 &"
          },
          {
            "name": "p7",
            "type": "const Vec3 &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawHexahedra",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawScaledHexahedra",
        "return_type": "void",
        "params": [
          {
            "name": "points",
            "type": "const int &"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "scale",
            "type": "const float"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawSphere",
        "return_type": "void",
        "params": [
          {
            "name": "p",
            "type": "const Vec3 &"
          },
          {
            "name": "radius",
            "type": "float"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawSphere",
        "return_type": "void",
        "params": [
          {
            "name": "p",
            "type": "const Vec3 &"
          },
          {
            "name": "radius",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawEllipsoid",
        "return_type": "void",
        "params": [
          {
            "name": "p",
            "type": "const Vec3 &"
          },
          {
            "name": "radii",
            "type": "const Vec3 &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawBoundingBox",
        "return_type": "void",
        "params": [
          {
            "name": "min",
            "type": "const Vec3 &"
          },
          {
            "name": "max",
            "type": "const Vec3 &"
          },
          {
            "name": "size",
            "type": "float"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "draw3DText",
        "return_type": "void",
        "params": [
          {
            "name": "p",
            "type": "const Vec3 &"
          },
          {
            "name": "scale",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "text",
            "type": "const char *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "draw3DText_Indices",
        "return_type": "void",
        "params": [
          {
            "name": "positions",
            "type": "const int &"
          },
          {
            "name": "scale",
            "type": "float"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "pushMatrix",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "popMatrix",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "multMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "float *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "scale",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "float"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "translate",
        "return_type": "void",
        "params": [
          {
            "name": "x",
            "type": "float"
          },
          {
            "name": "y",
            "type": "float"
          },
          {
            "name": "z",
            "type": "float"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setMaterial",
        "return_type": "void",
        "params": [
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "resetMaterial",
        "return_type": "void",
        "params": [
          {
            "name": "color",
            "type": "const RGBAColor &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "resetMaterial",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setPolygonMode",
        "return_type": "void",
        "params": [
          {
            "name": "_mode",
            "type": "int"
          },
          {
            "name": "_wireframe",
            "type": "bool"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setLightingEnabled",
        "return_type": "void",
        "params": [
          {
            "name": "_isAnabled",
            "type": "bool"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "enableBlending",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "disableBlending",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "enableLighting",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "disableLighting",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "enableDepthTest",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "disableDepthTest",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "saveLastState",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "restoreLastState",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "makeStateLifeCycle",
        "return_type": "StateLifeCycle",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "writeOverlayText",
        "return_type": "void",
        "params": [
          {
            "name": "x",
            "type": "int"
          },
          {
            "name": "y",
            "type": "int"
          },
          {
            "name": "fontSize",
            "type": "unsigned int"
          },
          {
            "name": "color",
            "type": "const RGBAColor &"
          },
          {
            "name": "text",
            "type": "const char *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "enablePolygonOffset",
        "return_type": "void",
        "params": [
          {
            "name": "factor",
            "type": "float"
          },
          {
            "name": "units",
            "type": "float"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "disablePolygonOffset",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "readPixels",
        "return_type": "void",
        "params": [
          {
            "name": "x",
            "type": "int"
          },
          {
            "name": "y",
            "type": "int"
          },
          {
            "name": "w",
            "type": "int"
          },
          {
            "name": "h",
            "type": "int"
          },
          {
            "name": "rgb",
            "type": "float *"
          },
          {
            "name": "z",
            "type": "float *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "clear",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "componentOverview": {
      "name": "DrawTool",
      "description": "The `DrawTool` class in the SOFA (Simulation Open-Framework Architecture) framework provides an abstract interface for rendering various graphical elements and managing drawing states within a 3D scene.",
      "namespace": "sofa::helper::visual"
    },
    "keyFeatures": [
      {
        "name": "Rendering Capabilities",
        "description": "The `DrawTool` class supports the rendering of various geometric shapes, including points, lines, triangles, quads, spheres, bounding boxes, and text. It also allows for drawing custom overlays with 2D text and managing polygon offsets."
      },
      {
        "name": "State Management",
        "description": "It provides methods to save and restore the state of the drawing context using RAII (Resource Acquisition Is Initialization) technique through `StateLifeCycle` struct. This ensures that drawing states are correctly managed and restored after operations, maintaining consistency in rendering pipelines."
      },
      {
        "name": "Transformation Methods",
        "description": "The class supports transformation operations like pushing and popping matrices from the stack, scaling, translating, and applying transformations with a matrix for complex scene manipulations."
      },
      {
        "name": "Drawing Styles",
        "description": "Users can set material properties, polygon modes (fill or wireframe), lighting conditions, and enable/disable various rendering features such as blending, depth testing, and lighting to control the appearance of rendered objects."
      },
      {
        "name": "Color Buffer Methods",
        "description": "It provides a method for reading pixel data from the color buffer (`readPixels`), which can be useful for implementing post-processing effects or performing screen-space operations like raytracing in software or capturing screenshots with depth information."
      }
    ],
    "componentDetails": {
      "author": "The SOFA Team and external contributors",
      "license": "GNU Lesser General Public License (LGPL) version 2.1 or later",
      "dependencies": [
        "sofa::type"
      ]
    },
    "usageInstructions": {
      "overview": "To use the `DrawTool` class, instantiate a derived concrete implementation such as OpenGL-based renderer and call its methods to render graphical elements and manage drawing states.",
      "exampleCode": "```cpp\n#include <sofa/helper/visual/DrawTool.h>\n\nusing namespace sofa::helper::visual;\n\n// Assuming drawTool is an instance of a specific DrawTool subclass like GLDrawTool\ndrawTool->drawSphere(Vec3(0.0, 0.0, 0.0), 1.0);\ndrawTool->pushMatrix();\ndrawTool->translate(2.0, 0.0, 0.0);\ndrawTool->drawTetrahedron(Vec3(0,0,0), Vec3(1,0,0), Vec3(0,1,0), Vec3(0,0,1));\ndrawTool->popMatrix();\n```"
    }
  },
  "maths": {
    "maths": "The `DrawTool` class in the SOFA framework is not directly involved with mathematical computations or physical simulations but rather serves as an interface for rendering and manipulating graphical elements within a 3D scene. The core functionalities provided by this class include various drawing operations, transformation methods, state management techniques, and overlay drawing functions.\n\n### Drawing Operations\nThe `DrawTool` class provides several member functions for drawing geometric shapes in the 3D space such as points, lines, triangles, quads, tetrahedra, hexahedra, spheres, ellipsoids, bounding boxes, and text. These functions allow setting vertices (points), normals, and colors to render these shapes.\n\n- **Drawing Points:** Functions like `drawPoint` accept a position vector (`Vec3`) and optionally a color (`RGBAColor`).\n  - Mathematically, drawing a point involves plotting its position in the coordinate system defined by the scene's camera.\n\n- **Drawing Triangles and Quads:** Methods such as `drawTriangle` and `drawQuad` take vertices and normals (optional) to render filled polygons. These can include optional per-vertex colors for shading purposes.\n  - Mathematically, these operations involve transforming vertex coordinates through the current model-view-projection matrix and interpolating colors across surfaces based on Gouraud or Phong shading models.\n\n### Transformation Methods\nTransformation methods provided by `DrawTool` enable applying affine transformations (scale, translate, rotate) to objects being rendered. Functions like `translate`, `scale`, and `multMatrix` are used for modifying the model-view matrix which affects how objects appear on screen after projection.\n  - Mathematically, transformation matrices are applied sequentially in a stack-based manner with functions like `pushMatrix` and `popMatrix`. Matrix multiplication is performed to combine multiple transformations into one composite transformation.\n\n### State Management\nState management involves saving and restoring rendering states through functions such as `saveLastState` and `restoreLastState`, which help maintain consistency across different drawing operations without needing to manually set up the same state repeatedly.\n  - Mathematically, this can involve copying current matrix stacks or other rendering settings like lighting modes into a stack and then reverting them when needed using standard LIFO (last-in-first-out) principles.\n\n### Overlay Methods and Color Buffer Operations\nOverlay methods such as `writeOverlayText` enable drawing text directly on the screen at specified 2D coordinates. Additionally, functions like `readPixels` allow reading color data from the rendering buffer to retrieve RGB values or depth information (`z-buffer`).\n  - Mathematically, these operations involve memory reads and writes within the frame buffer, which is a two-dimensional array of pixels representing the final rendered image.\n\n### Lighting and Blending Operations\nThe class provides methods for enabling/disabling lighting and blending modes that affect how colors are combined in the final rendering process. Functions such as `setLightingEnabled` and `enableBlending` control whether lighting calculations or alpha-blending should be applied during drawing operations, respectively.\n  - Mathematically, these involve setting parameters in shaders used for fragment coloring based on light sources (for lighting) or combining colors using blend factors for transparency blending."
  },
  "summary": {
    "abstract": "Provides utility functions for minimal debug drawing, including geometric shapes, text, transformations, and state management.",
    "sheet": "# DrawTool\n\n**Overview**\nDrawTool is a utility class in SOFA that provides methods for performing minimal debug drawing. It supports various graphical elements such as points, lines, triangles, quads, spheres, ellipsoids, bounding boxes, text, and more. The class also includes transformation methods (translate, scale) and state management techniques to maintain rendering consistency.\n\n**Parameters and Data**\nThe `DrawTool` class does not expose any significant data fields; its functionality is primarily through method calls for drawing operations and transformations.\n\n**Dependencies and Connections**\nComponents in SOFA receive a pointer to the DrawTool instance via the VisualParams parameter of their draw methods. This allows them to perform debug drawings using the provided functions."
  }
}