include/drawstuff/drawstuff.h

   1 /*************************************************************************
   2  *                                                                       *
   3  * Open Dynamics Engine, Copyright (C) 2001-2003 Russell L. Smith.       *
   4  * All rights reserved.  Email: russ@q12.org   Web: www.q12.org          *
   5  *                                                                       *
   6  * This library is free software; you can redistribute it and/or         *
   7  * modify it under the terms of EITHER:                                  *
   8  *   (1) The GNU Lesser General Public License as published by the Free  *
   9  *       Software Foundation; either version 2.1 of the License, or (at  *
  10  *       your option) any later version. The text of the GNU Lesser      *
  11  *       General Public License is included with this library in the     *
  12  *       file LICENSE.TXT.                                               *
  13  *   (2) The BSD-style license that is included with this library in     *
  14  *       the file LICENSE-BSD.TXT.                                       *
  15  *                                                                       *
  16  * This library 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 files    *
  19  * LICENSE.TXT and LICENSE-BSD.TXT for more details.                     *
  20  *                                                                       *
  21  *************************************************************************/
  22
  23 /** @defgroup drawstuff DrawStuff
  24
  25 DrawStuff is a library for rendering simple 3D objects in a virtual
  26 environment, for the purposes of demonstrating the features of ODE.
  27 It is provided for demonstration purposes and is not intended for
  28 production use.
  29
  30 @section Notes
  31
  32 In the virtual world, the z axis is "up" and z=0 is the floor.
  33
  34 The user is able to click+drag in the main window to move the camera:
  35   * left button - pan and tilt.
  36   * right button - forward and sideways.
  37   * left + right button (or middle button) - sideways and up.
  38 */
  39
  40
  41 #ifndef __DRAWSTUFF_H__
  42 #define __DRAWSTUFF_H__
  43
  44 /* Define a DLL export symbol for those platforms that need it */
  45 #if defined(ODE_PLATFORM_WINDOWS)
  46   #if defined(DS_DLL)
  47     #define DS_API __declspec(dllexport)
  48   #elif !defined(DS_LIB)
  49     #define DS_DLL_API __declspec(dllimport)
  50   #endif
  51 #endif
  52
  53 #if !defined(DS_API)
  54   #define DS_API
  55 #endif
  56
  57 #ifdef __cplusplus
  58 extern "C" {
  59 #endif
  60
  61
  62 #include <drawstuff/version.h>
  63
  64
  65 /* texture numbers */
  66   enum DS_TEXTURE_NUMBER
  67   {
  68     DS_NONE = 0,       /* uses the current color instead of a texture */
  69     DS_WOOD,
  70     DS_CHECKERED,
  71     DS_GROUND,
  72     DS_SKY
  73   };
  74
  75 /* draw modes */
  76
  77 #define DS_POLYFILL  0
  78 #define DS_WIREFRAME 1
  79
  80 /**
  81  * @struct dsFunctions
  82  * @brief Set of functions to be used as callbacks by the simulation loop.
  83  * @ingroup drawstuff
  84  */
  85 typedef struct dsFunctions {
  86   int version;                  /* put DS_VERSION here */
  87   /* version 1 data */
  88   void (*start)();              /* called before sim loop starts */
  89   void (*step) (int pause);     /* called before every frame */
  90   void (*command) (int cmd);    /* called if a command key is pressed */
  91   void (*stop)();               /* called after sim loop exits */
  92   /* version 2 data */
  93   const char *path_to_textures; /* if nonzero, path to texture files */
  94 } dsFunctions;
  95
  96
  97 /**
  98  * @brief Initializes output console.
  99  *
 100  * The function performs initialization routines for the application console.
 101  *
 102  * The function is to be called only if @fn dsSimulationLoop is not invoked.
 103  *
 104  * @param argc Reserved for future use
 105  * @param argv Reserved for future use
 106  * @ingroup drawstuff
 107  */
 108 DS_API void dsInitializeConsole(int argc, char **argv);
 109
 110
 111 /**
 112  * @brief Finalizes output console.
 113  *
 114  * The function performs all the necessary finalization for the application console.
 115  *
 116  * The function is to be called only if @fn dsSimulationLoop is not invoked.
 117  *
 118  * @ingroup drawstuff
 119  */
 120 DS_API void dsFinalizeConsole();
 121
 122
 123 /**
 124  * @brief Does the complete simulation.
 125  * @ingroup drawstuff
 126  * This function starts running the simulation, and only exits when the simulation is done.
 127  * Function pointers should be provided for the callbacks.
 128  * @param argv supports flags like '-notex' '-noshadow' '-pause'
 129  * @param fn Callback functions.
 130  */
 131 DS_API void dsSimulationLoop (int argc, char **argv,
 132                        int window_width, int window_height,
 133                        struct dsFunctions *fn);
 134
 135 /**
 136  * @brief exit with error message.
 137  * @ingroup drawstuff
 138  * This function displays an error message then exit.
 139  * @param msg format strin, like printf, without the newline character.
 140  */
 141 DS_API void dsError (const char *msg, ...);
 142
 143 /**
 144  * @brief exit with error message and core dump.
 145  * @ingroup drawstuff
 146  * this functions tries to dump core or start the debugger.
 147  * @param msg format strin, like printf, without the newline character.
 148  */
 149 DS_API void dsDebug (const char *msg, ...);
 150
 151 /**
 152  * @brief print log message
 153  * @ingroup drawstuff
 154  * @param msg format string, like printf, without the \n.
 155  */
 156 DS_API void dsPrint (const char *msg, ...);
 157
 158 /**
 159  * @brief Sets the viewpoint
 160  * @ingroup drawstuff
 161  * @param xyz camera position.
 162  * @param hpr contains heading, pitch and roll numbers in degrees. heading=0
 163  * points along the x axis, pitch=0 is looking towards the horizon, and
 164  * roll 0 is "unrotated".
 165  */
 166 DS_API void dsSetViewpoint (float xyz[3], float hpr[3]);
 167
 168
 169 /**
 170  * @brief Gets the viewpoint
 171  * @ingroup drawstuff
 172  * @param xyz position
 173  * @param hpr heading,pitch,roll.
 174  */
 175 DS_API void dsGetViewpoint (float xyz[3], float hpr[3]);
 176
 177 /**
 178  * @brief Stop the simulation loop.
 179  * @ingroup drawstuff
 180  * Calling this from within dsSimulationLoop()
 181  * will cause it to exit and return to the caller. it is the same as if the
 182  * user used the exit command. using this outside the loop will have no
 183  * effect.
 184  */
 185 DS_API void dsStop();
 186
 187 /**
 188  * @brief Get the elapsed time (on wall-clock)
 189  * @ingroup drawstuff
 190  * It returns the nr of seconds since the last call to this function.
 191  */
 192 DS_API double dsElapsedTime();
 193
 194 /**
 195  * @brief Toggle the rendering of textures.
 196  * @ingroup drawstuff
 197  * It changes the way objects are drawn. these changes will apply to all further
 198  * dsDrawXXX() functions.
 199  * @param the texture number must be a DS_xxx texture constant.
 200  * The current texture is colored according to the current color.
 201  * At the start of each frame, the texture is reset to none and the color is
 202  * reset to white.
 203  */
 204 DS_API void dsSetTexture (int texture_number);
 205
 206 /**
 207  * @brief Set the color with which geometry is drawn.
 208  * @ingroup drawstuff
 209  * @param red Red component from 0 to 1
 210  * @param green Green component from 0 to 1
 211  * @param blue Blue component from 0 to 1
 212  */
 213 DS_API void dsSetColor (float red, float green, float blue);
 214
 215 /**
 216  * @brief Set the color and transparency with which geometry is drawn.
 217  * @ingroup drawstuff
 218  * @param alpha Note that alpha transparency is a misnomer: it is alpha opacity.
 219  * 1.0 means fully opaque, and 0.0 means fully transparent.
 220  */
 221 DS_API void dsSetColorAlpha (float red, float green, float blue, float alpha);
 222
 223 /**
 224  * @brief Draw a box.
 225  * @ingroup drawstuff
 226  * @param pos is the x,y,z of the center of the object.
 227  * @param R is a 3x3 rotation matrix for the object, stored by row like this:
 228  *        [ R11 R12 R13 0 ]
 229  *        [ R21 R22 R23 0 ]
 230  *        [ R31 R32 R33 0 ]
 231  * @param sides[] is an array of x,y,z side lengths.
 232  */
 233 DS_API void dsDrawBox (const float pos[3], const float R[12], const float sides[3]);
 234
 235 /**
 236  * @brief Draw a sphere.
 237  * @ingroup drawstuff
 238  * @param pos Position of center.
 239  * @param R orientation.
 240  * @param radius
 241  */
 242 DS_API void dsDrawSphere (const float pos[3], const float R[12], float radius);
 243
 244 /**
 245  * @brief Draw a triangle.
 246  * @ingroup drawstuff
 247  * @param pos Position of center
 248  * @param R orientation
 249  * @param v0 first vertex
 250  * @param v1 second
 251  * @param v2 third vertex
 252  * @param solid set to 0 for wireframe
 253  */
 254 DS_API void dsDrawTriangle (const float pos[3], const float R[12],
 255                      const float *v0, const float *v1, const float *v2, int solid);
 256
 257 /**
 258  * @brief Draw triangles.
 259  * @ingroup drawstuff
 260  * @param pos Position of center
 261  * @param R orientation
 262  * @param v list of vertices (x0, y0, z0, x1, y1, z1, ...)
 263  * @param n number of vertices
 264  * @param solid set to 0 for wireframe
 265  */
 266 DS_API void dsDrawTriangles (const float pos[3], const float R[12],
 267                      const float *v, const int n, int solid);
 268
 269 /**
 270  * @brief Draw a z-aligned cylinder
 271  * @ingroup drawstuff
 272  */
 273 DS_API void dsDrawCylinder (const float pos[3], const float R[12],
 274                      float length, float radius);
 275
 276 /**
 277  * @brief Draw a z-aligned capsule
 278  * @ingroup drawstuff
 279  */
 280 DS_API void dsDrawCapsule (const float pos[3], const float R[12],
 281                     float length, float radius);
 282
 283 /**
 284  * @brief Draw a line.
 285  * @ingroup drawstuff
 286  */
 287 DS_API void dsDrawLine (const float pos1[3], const float pos2[3]);
 288
 289 /**
 290  * @brief Draw a convex shape.
 291  * @ingroup drawstuff
 292  */
 293 DS_API void dsDrawConvex(const float pos[3], const float R[12],
 294                   const float *_planes,
 295                   unsigned int _planecount,
 296                   const float *_points,
 297                   unsigned int _pointcount,
 298                   const unsigned int *_polygons);
 299
 300  /* these drawing functions are identical to the ones above, except they take
 301  * double arrays for `pos' and `R'.
 302  */
 303 DS_API void dsDrawBoxD (const double pos[3], const double R[12],
 304                  const double sides[3]);
 305 DS_API void dsDrawSphereD (const double pos[3], const double R[12],
 306                     const float radius);
 307 DS_API void dsDrawTriangleD (const double pos[3], const double R[12],
 308                       const double *v0, const double *v1, const double *v2, int solid);
 309 DS_API void dsDrawTrianglesD (const double pos[3], const double R[12],
 310                       const double *v, const int n, int solid);
 311 DS_API void dsDrawCylinderD (const double pos[3], const double R[12],
 312                       float length, float radius);
 313 DS_API void dsDrawCapsuleD (const double pos[3], const double R[12],
 314                      float length, float radius);
 315 DS_API void dsDrawLineD (const double pos1[3], const double pos2[3]);
 316 DS_API void dsDrawConvexD(const double pos[3], const double R[12],
 317                   const double *_planes,
 318                   unsigned int _planecount,
 319                   const double *_points,
 320                   unsigned int _pointcount,
 321                   const unsigned int *_polygons);
 322
 323 /**
 324  * @brief Set the quality with which curved objects are rendered.
 325  * @ingroup drawstuff
 326  * Higher numbers are higher quality, but slower to draw.
 327  * This must be set before the first objects are drawn to be effective.
 328  * Default sphere quality is 1, default capsule quality is 3.
 329  */
 330 DS_API void dsSetSphereQuality (int n);         /* default = 1 */
 331 DS_API void dsSetCapsuleQuality (int n);                /* default = 3 */
 332
 333 /**
 334  * @brief Set Drawmode 0=Polygon Fill,1=Wireframe).
 335  * Use the DS_POLYFILL and DS_WIREFRAME macros.
 336  * @ingroup drawstuff
 337  */
 338 DS_API void dsSetDrawMode(int mode);
 339
 340 /* Backwards compatible API */
 341 #define dsDrawCappedCylinder dsDrawCapsule
 342 #define dsDrawCappedCylinderD dsDrawCapsuleD
 343 #define dsSetCappedCylinderQuality dsSetCapsuleQuality
 344
 345 /* closing bracket for extern "C" */
 346 #ifdef __cplusplus
 347 }
 348 #endif
 349
 350 #endif
 351